CPersona

---

独立仓库 — 这是供 Claude Desktop、Claude Code、Codex CLI、Cursor、VS Code 及其他 MCP 客户端使用的独立版本（注册表）。 如果你是 ClotoCore 用户，请改为从应用内市场（ClotoHub）安装 CPersona — 它分发的就是同一个仓库。

项目状态 — 2.4.x 为稳定版；2.6.x 为当前版本，所有 修复都会在此版本线上发布，目前正在等待生产环境浸泡认证。首个正式版 2.6.0 首次启动时会将架构从版本 13 迁移到 17，并更改部分 工具行为，因此请按照从 2.5 升级到 2.6迁移 2.5 数据库。 2.5.x 为候选版：已不再是最新版本线，且尚未通过认证， 可通过指定确切版本获取。该运行哪个版本，以及各版本线 会持续获得修复多久： SUPPORT.md。 各版本线的发展方向：路线图。

要从 2.5.2 或更早版本升级？ 有两件事需要你决定。 v2.5.3 在未设置 CPERSONA_AUTH_TOKEN 时不会启动 HTTP 传输， 无论绑定地址为何 — 请设置该变量，或通过 CPERSONA_ALLOW_UNAUTHENTICATED_HTTP=true 选择不启用（原因；stdio 不受影响）。 v2.5.2 更改了工具响应格式 — 请根据 ok is false 进行分支判断，并将任何携带 error 的响应视为失败，无论是否存在 ok （契约 §10）。

问题

Claude 会忘记会话之间的所有内容。每次对话都从零开始——不了解你的项目、偏好，也不知道你昨天讨论了什么。

cpersona 解决了这个问题。它是一个 MCP 服务，可将记忆存储在本地 SQLite 文件中，并通过混合搜索检索记忆。Claude 会记住你。它可在任何兼容 MCP 的宿主上运行——Claude Desktop、Claude Code、ClotoCore（cpersona 起源于此的 AI Agent 平台，也是它的记忆层），或你自己的客户端。

快速开始

要将其设置为 AI Agent 使用吗？ 请阅读 Agent Skill ——在克隆的仓库中对应 skills/cpersona-memory/SKILL.md ——并从头到尾照此操作。 这是完整流程：安装、嵌入服务、注册，以及快速开始中常被跳过的两个步骤——在新会话中验证，并持久化记忆策略，以便下一会话知道哪个 agent_id 保存了记忆。

自己使用 Claude Code 吗？ 同一技能也随 wheel 一同提供。安装好 cpersona 后，将其复制进去，然后说 “设置 CPersona。”

python -c "import cpersona,pathlib,shutil; s=pathlib.Path(cpersona.__file__).parent/'skills'/'cpersona-memory'; shutil.copytree(s, pathlib.Path.home()/'.claude/skills/cpersona-memory', dirs_exist_ok=True)"

1. 安装 — Python 3.11+，单命令方式还需要 uv。

uvx cpersona          # run directly, no install step
pip install cpersona  # or install it

2. 运行嵌入服务 — 强烈推荐；它为向量层提供支持

uvx --from "cembedding[onnx]" cembedding-download-model --model jina-v5-nano
EMBEDDING_PROVIDER=onnx_jina_v5_nano uvx --from "cembedding[onnx]" cembedding   # serves http://127.0.0.1:8401/embed

参考服务的生命周期与其标准输入绑定。如果启动时标准输入已关闭——例如由服务管理器、通过 nohup … </dev/null，或从 Agent 的后台 Shell 启动——它会绑定端口，并在同一秒内以状态码 0 退出。请为其提供一个保持打开的标准输入（sleep infinity | cembedding）；详情请参阅入门指南。

任何实现嵌入契约的端点都可使用，同样值得推荐；CEmbedding 是参考实现。后端由你选择——我们的建议是连接一个后端，而不是非要连接那个后端。

即使没有后端，cpersona 仍可运行——使用 FTS5 + 关键词搜索，并且每次召回时都会说明功能已降级，而不会悄悄减少返回结果。这是受支持的回退方案，但并非推荐的运行方式：召回只会匹配共有词语，因此，表述方式与问题不同的记忆可能无法找到，较早的记忆也可能无法找到。

3. 在 MCP 客户端中注册

对于 Codex、Cursor、VS Code 或 Claude Desktop，请参阅 客户端注册表。 下面的命令适用于 Claude Code。

claude mcp add-json cpersona '{"type":"stdio","command":"uvx","args":["cpersona"],"env":{"CPERSONA_DB_PATH":"/home/you/.claude/cpersona.db","EMBEDDING_MODE":"http","EMBEDDING_HTTP_URL":"http://127.0.0.1:8401/embed"}}' -s user

4. 在新会话中验证 — 请 Agent store 一些内容，然后在全新会话中 recall 这些内容。跨越会话边界后仍能保留，正是它的核心价值。

5. 让设置持久生效 — 注册会为 Agent 提供工具，但不会告诉下一会话使用这些工具，也不会告知哪个 agent_id 保存了记忆：召回严格限定于完全匹配的 agent_id，因此猜错 ID 的会话将无法找回任何内容。将简短的策略段落写入客户端每次会话都会加载的文件（~/.claude/CLAUDE.md、AGENTS.md 等）——请参阅入门指南 §5。

服务器启动时会向 pypi.org 查询是否有更新版本，并通过 recall 告知调用方 Agent；设置 CPERSONA_UPDATE_CHECK=false 可关闭此功能。更新绝不会自动进行。

Claude Desktop 配置、Windows 路径、从源码安装以及完整操作指南：请参阅入门指南。

你将获得什么

• 混合搜索——向量搜索（由嵌入服务提供支持）、FTS5 （采用三元组，因此适用于日语和其他不使用空格的文字）以及关键词搜索， 按排名或相对分数融合。FTS 和关键词搜索可弥补向量搜索的不足：标识符、错误字符串和精确名称。
• 可追溯的证据——reconstruct 是推荐的记忆问答方式，它会在字符预算范围内返回引用其依据的已存储行的条目。长记录中超出嵌入窗口的文本仍可访问（默认启用分块访问）。
• 三种记忆类型——事实、会话摘要和累积的个人资料。
• 不依赖大模型——cpersona 从不调用生成式模型；由你的 Agent 负责总结并传递结果。在校准后的门控阈值下，召回结果具有确定性；但由于门控阈值采用采样方式，因此使用相同数据的两个安装实例可能会得到不同的结果。
• 单文件 SQLite——无需外部数据库；使用 sqlite3 .backup 复制语料库（还需复制其旁边的校准辅助文件；如果某条 ACL 记录设置了 per_subject，也要复制别名账本）。
• 易于运维——自动校准阈值、可自动修复的健康检查、嵌入层失效时的提示、JSONL 导出/导入、Agent 间合并。
• 隔离——agent_id、project_id 和 channel 可让多个 Agent 和项目共用一个数据库，同时避免彼此数据泄漏。

了解其运作方式：架构 · 了解工具的功能：工具 · 了解可依赖的行为：行为约定。

基准测试

基于 OmniMemEval 的 LongMemEval-S 流程进行测量：使用清理后的 LongMemEval-S 中的 500 个问题，由 gpt-4.1-mini 作答，再由 gpt-4o-mini 判定；所用的测试框架、提示词和模型与 OmniMemEval 复现的记忆后端相同。准确率表示判定为正确的问题占比；上下文令牌数表示每道题发送给 答案模型的平均令牌数，其中包括提示词。

后端	部署方式	SS-User	SS-Asst	SS-Pref	Temp. Reas	Multi-S	Know. Upd	Overall	上下文令牌数
CPersona 2.6.11（pro 模式）	本地	97.14	94.64	96.67	86.47	85.71	88.46	89.60	4,262.5
CPersona 2.6.11（lite 模式）	本地	95.71	83.93	90.00	80.45	74.44	82.05	82.20	993.3
MemOS	云端	100.00	100.00	100.00	89.47	78.95	84.62	89.20	4,151

并列第一：每道题 4,262.5 个令牌，准确率为 89.60%，这是本项目自行运行的结果。在 OmniMemEval 通过同一流程复现的 12 个后端中，MemOS 与其表现相当（准确率为 89.20%， 每道题 4,151 个令牌），其余后端的得分都至少低 9 个百分点。CPersona 的两种模式使用这 500 道题中的 100 道进行调优，其余 400 道用于发布检查；在这 400 道题上，pro 模式的 准确率为 88.75%，仍与 MemOS 相当。（“相当”指差异处于两次独立运行的 95% 抽样误差范围内。） lite 模式的回答较短，准确率为 82.20%，每道题使用 993.3 个令牌：低于 MemOS，与 EverOS、 Zep / Graphiti、mem9 和 Letta 相当，所用令牌数不超过它们的四分之一。在 LoCoMo（1,540 道题， 使用相同模型）上，pro 模式的准确率为 84.03%，每道题使用 4,441 个令牌：低于 MemOS（88.83%）， 与 Cognee、EverOS 和 Hindsight 相当，所用令牌少于它们中的任何一个。CPersona 会原样存储 每段对话，存储或回忆时都不会调用生成模型。

与 OpenViking 0.5.0 相比，本项目运行时未使用其 推荐的重排功能：在 LoCoMo 上，CPersona 的准确率为 84.03%，OpenViking 为 59.09%；在 Open Agent Memory Benchmark 的 60 道题 LongMemEval 筛选测试中，CPersona 答对 52 道，OpenViking 答对 51 道；CPersona 使用的 证据令牌数仅为四分之一，写入时也不使用生成模型令牌（OpenViking 的模型使用了 3,700 万个 输入和输出令牌。并非所有成本都对 CPersona 有利：在 LoCoMo 上，pro 模式的搜索速度较慢 （中位数为 72.7 毫秒，对比 50.0 毫秒），其上下文长度为 OpenViking 的 0.58 倍。

本项目在 2.6.11 发布版本上各运行了一次。设置、已注册规则以及所有偏离干净运行的情况： 结果； 早期运行：2.6.3a1 和 2.6.4a1；LMEB 上仅检索的测量结果： benchmarks/。

文档

cloto-dev.github.io/CPersona 是权威文档——如果本 README 与其内容不一致，以网站为准。

快速入门	安装、嵌入式服务、客户端注册、验证
行为契约	可依赖的行为：召回排序、去重、扫描窗口、响应格式
工具	所有工具，按用途分组
架构	存储、检索流程、隔离维度
路线图	各发布线的用途及可能的破坏性变更；计划中的检索功能和扩展阶梯
运维手册	备份、降级检测、调优、CJK 指南、语料库同步
配置	所有环境变量及其默认值
质量保证	发布如何通过审核：审计、缺陷台账、结构和变异门禁
常见问题	简要解答运维人员实际会问的问题

日语译文可通过语言选择器查看（英文为权威版本），Agent 也可以阅读 llms.txt。 日语长文：设计与设置指南和一篇介绍会话结束 → /clear → recall 的令牌经济学的文章。

质量保证

每个版本都要通过一套可由机器验证的流程：多 Agent 审计轮次并进行对抗性验证；缺陷台账，若修复标记消失或已移除的缺陷再次出现，CI 就会失败；用于检查普通测试无法表达的不变量的结构门禁；证明不变量遭破坏时这些门禁会转为红色的变异测试；以及确保文档中的计数、默认值和版本声明与定义它们的源保持一致的门禁。

其背后是：约 3,865 个测试函数，分布在约 297 个测试模块中（参数化后约 5,413 个测试用例，测试代码量超过服务端代码），运行于 Schema v20 之上——了解发布如何通过审核。

支持

分为三个层级——稳定版（通过生产认证，仅提供关键修复）、当前版 （最新发布线，所有修复都会在此推出）和实验版（可选择加入的预发布版本）。被取代的发布线仍会获得为期 30 天的关键修复支持。**固定版本前，请阅读 SUPPORT.md § 已知问题 **——其中一些问题会影响你应该运行的版本。

发现 Bug，或文档未能解释清楚的问题？请提交 Bug 报告 或功能请求， 即使你不确定也可以提交——把配置问题误认为 Bug，说明文档不够清晰，这本身也是一个缺陷。请通过 SECURITY.md 私下报告安全漏洞。

赞助

CPersona 采用 MIT 许可，无论是否有人赞助，均可完整使用。赞助不会带来任何功能、发布版本层级或问题队列中的优先位置——问题会根据影响、可复现性和安全性进行分类处理，对任何人都一视同仁。

如果 CPersona 已成为你工作流的一部分，而你希望这项工作继续下去，可以在 GitHub 上赞助 Cloto-dev。该页面也介绍了 CPersona、ClotoCore 以及该账号下发布的其他项目；赞助款将用于开发、测试和基础设施、文档编写与维护。

资金并非唯一能提供帮助的东西，也不是本项目最需要的东西。为仓库点星、说明设置过程中令人困惑的部分、提交可复现的问题，或纠正文档中的一句话，都能推动项目向前发展。

许可证

MIT — 可不受限制地从任何 MCP 主机使用。