CPersona

<div align="center"> # CPersona ### MCP 内存服务器 为 Claude 提供跨会话的持久记忆。 单个 SQLite 文件。29 个工具。零 LLM 依赖。 [](https://github.com/Cloto-dev/cpersona/blob/master/LICENSE) []() []() [快速入门](#快速入门) · [功能](#功能) · [架构](#架构) · [所有工具](#所有工具) · [Zenn 书 (JP)](https://zenn.dev/cloto/books/claude-memory-mcp-server) </div> --- > **独立仓库** — 这是与 Claude Desktop、Claude Code 和任何 MCP 客户端一起使用的独立版本。 > 如果您是 [ClotoCore](https://github.com/Cloto-dev/ClotoCore) 用户，请从应用商店 ([ClotoHub](https://hub.cloto.dev)) 安装 CPersona — 它分发的是同一个仓库。 > **项目状态（2026 年 7 月）** — 2.4 系列是 **稳定** 线（最新：v2.4.40，由三轮全面审计 — 见 [质量保证](#质量保证) 控制）。2.5 系列是 **当前** 线（最新：v2.5.1）— 一个内部稳定线，已经通过完整的发布门控，并且所有修复都已落地，待生产浸泡认证；DB 模式和 MCP 工具合同保留，功能开发在 2.6 中恢复。层级和支持窗口：[发布频道和支持](#发布频道--支持)。 ## 问题 Claude 会在会话之间忘记所有内容。每次对话都从零开始 — 没有关于您的项目、偏好或昨天讨论的任何上下文。 cpersona 解决了这个问题。它是一个 [MCP](https://modelcontextprotocol.io/) 服务器，存储本地 SQLite 文件中的记忆，并通过混合搜索检索它们。Claude 记得您。 ## 快速入门 **先决条件：** Python 3.11+（和 [uv](https://docs.astral.sh/uv/) 用于一键路径）。 > **Claude Code？让代理执行设置。** 此仓库附带一个 [代理技能](https://github.com/Cloto-dev/cpersona/blob/master/skills/cpersona-memory/SKILL.md)，它引导 Claude 完成整个安装过程 — cpersona、嵌入服务器、MCP 注册和存储/召回烟雾测试 — 更重要的是，它教导 Claude 何时存储、召回和存档记忆： > > ```bash > # 从 PyPI 安装？技能包含在轮中 — 无需克隆： > 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)" > > # 通过 uvx 运行（隔离环境），或尚未安装： > git clone --depth 1 https://github.com/Cloto-dev/cpersona.git /tmp/cpersona > mkdir -p ~/.claude/skills && cp -r /tmp/cpersona/skills/cpersona-memory ~/.claude/skills/ > ``` > > 然后只需告诉 Claude Code： *"设置 CPersona — 我想要持久记忆。"* 以下手动步骤适用于 Claude Desktop 用户和任何喜欢手动配置的人。 ### 1. 安装 cpersona ```bash uvx cpersona # 直接运行，无需安装步骤 # 或 pip install cpersona # 然后 `cpersona` 命令在您的 PATH 上 ``` <details> <summary>从源代码（用于开发）</summary> ```bash git clone https://github.com/Cloto-dev/cpersona.git cd cpersona python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install . ``` 使用 `python -m cpersona`（或 `python server.py`）运行它。 </details> ### 2. 设置嵌入服务器（推荐） cpersona 的混合搜索与嵌入服务器配合使用效果最佳。cpersona 是嵌入服务器无关的：指向 `CPERSONA_EMBEDDING_URL`（见步骤 3）到任何实现以下最小合约的 HTTP 端点。 ``` POST /embed 请求： { "texts": ["string", ...] } # 非空数组，每批最多 100 个 响应： { "embeddings": [[float, ...], ...], "dimensions": <int> } ``` 合约要求（2.5.0b1 澄清）： - **嵌入必须归一化为 L2。** cpersona 将相似度计算为原始点积；返回未归一化向量的后端会使排名偏差于向量幅度。所有支持的后端（客户端的 `api` 模式和所有 CEmbedding 提供程序）已经归一化。 - **合约是无角色的** — 查询和文档通过相同的调用嵌入。提示前缀模型（e5-style，提示 bge）将在其后表现不佳；对称或检索合并的模型（jina-v5-nano，bge-m3，MiniLM）是预期的适配。 - **在同一 URL 后交换模型：** cpersona 仅通过嵌入维度指纹识别后端（合约不携带模型身份）。相同维度的模型交换静默地使存储的语料库无效 — 在一个之后，重新嵌入（`check_health(fix=true)` 修复 NULL 行）和 `calibrate_threshold`。 参考服务器是 [CEmbedding](https://github.com/Cloto-dev/CEmbedding) （MIT）— 它在设备上运行 jina-v5-nano（CPU）并恰好公开此端点： ```bash git clone https://github.com/Cloto-dev/CEmbedding.git && cd CEmbedding python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate pip install ".[onnx]" python download_model.py --model jina-v5-nano EMBEDDING_PROVIDER=onnx_jina_v5_nano python server.py # 提供 http://127.0.0.1:8401/embed ``` cpersona 配备了针对 jina-v5-nano（768d）的默认调优参数。任何其他满足上述合约的服务器也适用 — 见 [基准测试](#基准测试) 以获取已发布测量值的模型。 > 如果没有嵌入服务器，cpersona 仅使用 FTS5 + 关键词搜索作为后备。向量搜索（最强的检索层）将被禁用。 ### 3. 配置您的 MCP 客户端 **Claude Desktop** — 添加到 `claude_desktop_config.json`： ```json { "mcpServers": { "cpersona": { "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" } } } } ``` 步骤 2 中的嵌入服务器是一个普通的 HTTP 进程，而不是 MCP 服务器 — 像运行后台服务一样运行它（终端、launchd/systemd 等）； cpersona 只需要它的 URL。 > **Windows：** 使用 `C:/Users/you/.claude/cpersona.db` 作为数据库路径。 > **还没有嵌入服务器？** 删除两个 `EMBEDDING_*` 行（或设置 `EMBEDDING_MODE=none`）— cpersona 运行在 FTS5 + 关键词上，并告知您何时性能下降。 **Claude Code：** ```bash 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 ``` 就这样。Claude 现在有持久的记忆。要求它 `store` 某些内容，并在后面的会话中 `recall` 它。 ## 功能 **混合搜索** — 三个独立的检索策略并行运行，并通过 Reciprocal Rank Fusion（RRF）合并结果： | 层 | 方法 | 优势 | |-------|--------|----------| | 向量 | 余弦相似度（jina-v5-nano，768d） | 语义含义 | | FTS5 | SQLite 全文搜索，带三元组标记 | 确切术语、名称、ID | | 关键词 | 后备模式匹配 | 边缘情况、部分匹配 | **记忆类型：** - **陈述记忆** — 通过 `store` 存储的单个事实、决定、指令 - **情景记忆** — 通过 `archive_episode` 存档的对话摘要 - **配置文件记忆** — 通过 `update_profile` 累积的用户/项目属性 **置信度评分** — 每个召回的记忆都会获得一个结合以下因素的置信度评分: - 余弦相似度（语义相关性） - 动态时间衰减（适应语料库时间范围 — 1 年前的语料库和 1 天前的语料库使用不同的衰减曲线） - 召回增强（频繁有用的记忆更轻松地浮现，具有自然的淡出） - 完成因子（已解决的主题更快地衰减） **零 LLM 依赖** — cpersona 是一个纯数据服务器。它在内部从不调用 LLM。所有总结和提取都由调用代理执行。这意味着 cpersona 本身没有 API 成本、确定性行为和隐藏延迟。 **附加功能：** - 代理命名空间隔离 — 多个代理共享一个数据库而不会相互干扰 - 后台任务队列 — 数据库持久、崩溃恢复的异步处理 - JSONL 导出/导入 — 环境间的完整记忆可移植性 - 代理到代理的记忆合并 — 原子复制/移动，带重复数据删除 - 自动校准 — 通过空分布 z-score 的统计阈值调谐（无需标签） - 健康检查 — 带有严重性标记的问题的 20 个检查注册表，具有自动修复（污染、重复、FTS 完整性、嵌入维度漂移、模式对象、隔离轴卫生、过时任务、无效数据），以及用于 CI 门控的 `python -m cpersona.checkup` CLI - 深度检查 — 具有自动修复的语义数据质量分析（匿名源恢复、短内容、过时配置文件、孤立剧集） - 记忆保护 — 锁定/解锁以防止意外删除或编辑 - 最近召回惩罚 — 抑制频繁召回记忆的回音室效应 - stdio + 流式 HTTP 传输 - 单文件 SQLite — 无需外部数据库 ## 架构 ``` ┌─────────────────────────────────────┐ │ MCP 主机 │ │ （Claude Desktop / Claude Code） │ └──────────────┬──────────────────────┘ │ MCP（JSON-RPC） ┌──────────────▼──────────────────────┐ │ cpersona │ │ （server.py） │ │ │ │ ┌─────────┐ ┌─────────┐ │ │ │ 存储 │ │ 召回 │ ... │ │ └────┬────┘ └────┬────┘ │ │ │ │ │ │ ┌────▼─────────────▼────────────┐ │ │ │ SQLite 数据库 │ │ │ │ │ │ │ │ 记忆 （内容 + 嵌入） │ │ │ │ 剧集 （摘要） │ │ │ │ 配置文件 （属性） │ │ │ │ memories_fts （FTS5 索引） │ │ │ │ episodes_fts （FTS5 索引） │ │ │ │ pending_memory_tasks （队列） │ │ │ └────────────────────────────────┘ │ │ │ └──────────────┬───────────────────────┘ │ HTTP ┌──────────────▼──────────────────────┐ │ 嵌入服务器 │ │ （jina-v5-nano ONNX，768d） │ └─────────────────────────────────────┘ ``` **召回流程（RRF 模式）：** ``` 查询 → ┌── 向量搜索（余弦相似度） ──┐ ├── FTS5 搜索（剧集 + 记忆） ──┼── RRF 合并 → 置信度评分 → 前 K └── 关键词后备 ──┘ ``` ## 基准测试 在 LMEB（Long-horizon Memory Embedding Benchmark，arXiv:2603.12572）上测量 — 22 个数据集涵盖 LoCoMo 和 LongMemEval，在此处测量为 22 个检索任务。指标是所有 22 个任务的平均 NDCG@10。 两个轨道隔离管道的贡献： - **轨道 A** — 原始嵌入模型本身（基线检索）。 - **轨道 B** — 相同的嵌入通过 cpersona 的实际 `store`/`recall` 代码路径：SQLite + FTS5 + RRF 融合 + 每个代理的自动校准（cpersona v2.4.40，全排名机制）。 | 嵌入模型 | 参数 | 维度 | 轨道 A（原始） | 轨道 B（cpersona） | Δ | |---|---|---|---|---|---| | all-MiniLM-L6-v2 | 22M | 384 | 43.67 | **50.10** | +6.43 | | bge-m3 | 568M | 1024 | 56.83 | **57.66** | +0.83 | cpersona 的混合管道在两个模型上都优于原始嵌入（Track B > Track A）— 融合层增加了信号而不是简单地保留向量。嵌入越弱，管道的贡献越大：FTS5/关键词层弥补了向量搜索单独遗漏的查询。方法论、测量工具和复制制度生活在 [`benchmarks/`](https://github.com/Cloto-dev/cpersona/blob/master/benchmarks/README.md) 中。 ## 所有工具 | 工具 | 描述 | |------|-------------| | `store` | 将消息存储在代理内存中 | | `recall` | 召回相关记忆（向量 + FTS5 + 关键词，RRF 合并） | | `recall_with_context` | 使用外部对话上下文召回（自动重复数据删除） | | `get_contents` | 展开召回预览引用（`mem:<id>` / `ep:<id>`）以获取完整内容 | | `get_profile` | 获取当前代理配置文件 | | `update_profile` | 保存预计算的代理配置文件 | | `get_operating_context` | 读取提供给每个客户端的操作员拥有的操作上下文（只读；编辑在文件系统上） | | `archive_episode` | 存档带有摘要和关键词的对话剧集 | | `list_memories` | 列出最近的记忆 | | `list_episodes` | 列出存档的剧集 | | `update_memory` | 更新记忆内容（拒绝如果锁定） | | `lock_memory` | 锁定记忆以防止删除/编辑 | | `unlock_memory` | 解锁记忆以允许删除/编辑 | | `delete_memory` | 删除单个记忆（强制执行所有权） | | `delete_episode` | 删除单个剧集（强制执行所有权） | | `delete_agent_data` | 删除所有代理数据 | | `calibrate_threshold` | 通过 z-score 自动校准向量搜索阈值 | | `set_recall_precision` | 设置代理的召回精度（旋钮 3）并校准其门控 | | `get_recall_precision` | 读取代理的有效召回精度（旋钮 3） | | `pause_persistence` | 将写入操作转为 no-ops 以获得一个 opt-in TTL 窗口 | | `resume_persistence` | 立即重新启用持久性 | | `persistence_status` | 报告是否暂停持久性以及剩余的 TTL | | `migrate_channel_axis` | 将桥接型记忆迁移到其具体通道 | | `export_memories` | 导出到 JSONL（记忆， 导入到 JSONL（msg_id 消除重复） | | `merge_memories` | 将一个代理的数据合并到另一个（原子，带重复数据删除） | | `get_queue_status` | 后台任务队列状态 | | `check_health` | 注册驱动的健康检查（严重性标记的问题）具有自动修复 | | `deep_check` | 具有自动修复的深度语义数据质量分析 | ## 配置 所有设置均通过环境变量，并具有合理的默认值： | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `CPERSONA_DB_PATH` | `./cpersona.db` | SQLite 数据库路径 | | `CPERSONA_EMBEDDING_MODE` | `none` | 嵌入模式（`http` 或 `none`） | | `CPERSONA_EMBEDDING_URL` | *(未设置)* | 嵌入服务器 URL，例如 `http://127.0.0.1:8401/embed` | | `CPERSONA_VECTOR_SEARCH_MODE` | `local` | 向量搜索执行（本地余弦处理，或远程卸载） | | `CPERSONA_RECALL_MODE` | `rrf` | 召回融合策略（`rrf`、`rsf` 或 `cascade`） | | `CPERSONA_RECALL_PREVIEW_CHARS` | `500` | 预览层：召回工具返回的最大内容字符数（`0` 禁用；`full_content=true` / `get_contents` 获取完整文本） | | `CPERSONA_RRF_K` | `60` | RRF 平滑参数 | | `CPERSONA_CONFIDENCE_ENABLED` | `false` | 结果中包含置信度元数据 | | `CPERSONA_AUTO_CALIBRATE` | `false` | 启动时自动校准 | | `CPERSONA_TASK_QUEUE_ENABLED` | `true` | 后台任务队列（基于数据库，崩溃恢复） | | `CPERSONA_RECENT_RECALL_PENALTY` | `0.7` | 最近召回记忆的惩罚 | | `CPERSONA_RECENT_RECALL_WINDOW_MIN` | `5` | 最近召回惩罚的窗口（分钟） | 通用别名 `EMBEDDING_MODE` / `EMBEDDING_HTTP_URL` / `EMBEDDING_MODEL` 也接受（`CPERSONA_` 前缀形式优先于两者设置时）。 市场目录和快速入门使用通用名称。 ### 召回融合模式 (`CPERSONA_RECALL_MODE`) - **`rrf`**（默认）— 互惠排名融合：仅按排名合并向量 + FTS 通道。稳健且无标度，但丢弃分数幅度。 - **`rsf`** — 相对分数融合：每个查询的 min-max 归一化每个通道的原始分数（向量为余弦，关键词为 bm25），然后求和，因此关键词通道的 bm25 幅度存活下来 `rrf` 扁平化 (≈ Weaviate 的 `relativeScoreFusion`; 参见 ClotoCore `RECALL_CONTAMINATION_AB_2026-06-14` 报告 §10–12)。 **建议用于主题漂移或无空间语言（例如日语）上下文**，其中该幅度是区分信号 `rrf` 扁平化。 *警告：* min-max 归一化可能会过度削减小而紧密的得分集，当启用 `autocut` 时 — `rrf` 仍然是默认项，直到该交互作用得到加强。 - **`cascade`** — 顺序通道填充（旧版）。 ## 统计 - **约 9,000 行** Python 代码，分布在专注的模块中，以及 3,300 行的 MCP 供应商快照 - **435 个测试**，分布在 35 个测试模块中（~10,000 行 — 测试代码比服务器代码多），包括结构强制门控 - **模式 v13**（自动迁移） - **MIT 许可证** ## 兼容 cpersona 是一个 MCP 服务器 — 它与任何兼容 MCP 的主机一起工作： - [Claude Desktop](https://claude.ai/download) - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) - [ClotoCore](https://github.com/Cloto-dev/ClotoCore)（AI 代理平台，cpersona 源自该平台） - 任何自定义 MCP 客户端 ## ClotoCore 组件 cpersona 是 [ClotoCore](https://github.com/Cloto-dev/ClotoCore) 的内存层，ClotoCore 是一个用 Rust 编写的开源 AI 代理平台。虽然 cpersona 完全独立（MIT 许可证），但其设计目的是为 AI 代理在 ClotoCore 生态系统中提供持久、可搜索的内存。 ## 质量保证 每个版本的发布都经过机器可验证的质量流程验证： - **审计关卡发布** — 在发布版本之前，代码库会经过全面的多代理审计轮次（每个维度独立查找，每个查找结果从多个角度进行对抗性验证）。v2.4.39 在经过三轮审计后发布 — 43 个修复，每个修复结果都在其所处的代码树上重新验证。 - **问题注册表** — 每个审计缺陷都存入 [`qa/issue-registry.json`](https://github.com/Cloto-dev/cpersona/blob/master/qa/issue-registry.json) 中，带有机器可检查的代码模式； [`scripts/verify-issues.sh`](https://github.com/Cloto-dev/cpersona/blob/master/scripts/verify-issues.sh) 验证每个修复标记仍然存在（每个已移除的缺陷保持移除），因此回归或静默撤销的修复会大声报错。 - **结构化 CI 关卡** — 无法通过普通测试表达的不变量由 pytest 套件中的 AST 和行为级关卡强制执行（在 CI 上运行，Python 版本为 3.11/3.13）：每个写入者都持有共享写入锁，代理范围的 SQL 携带其隔离谓词，身份/去重探针携带项目/通道轴，`check_health` 在持有写入锁时不执行嵌入网络 I/O。 - **发布生命周期标准** — 发布过程本身在 [`docs/RELEASE_LIFECYCLE_STANDARD.md`](https://github.com/Cloto-dev/cpersona/blob/master/docs/RELEASE_LIFECYCLE_STANDARD.md) （v1.0）中指定，在该仓库中试点作为 Cloto 家族项目的参考实现。 ## 发布渠道与支持 发布遵循三层模型 — **稳定版**（生产认证，仅限关键修复），**当前版**（最新发布线，所有修复都发布在此），以及 **实验版**（alpha/beta 预发布，，需选择加入）。当新版本被认证为稳定版时，之前的版本将继续支持 30 天，然后达到生命周期结束。当前状态：**2.4.x 是稳定版**（最新 v2.4.40）和 **2.5.x 是当前版**（最新 v2.5.1），所有修复都在此版本中发布，同时等待生产浸泡认证。 > **已知问题：** v2.4.39 及更早版本在几百行以上的语料库中低估了向量召回（bug-085；v2.4.38–v2.4.39 受影响最大 — 限制夹闭是唯一解决方法）。已在 v2.4.40 中修复；强烈建议升级。参见 [SUPPORT.md § 已知问题](https://github.com/Cloto-dev/cpersona/blob/master/SUPPORT.md#known-issues)。 完整策略： [SUPPORT.md](https://github.com/Cloto-dev/cpersona/blob/master/SUPPORT.md) · 规范： [RELEASE_LIFECYCLE_STANDARD.md](https://github.com/Cloto-dev/cpersona/blob/master/docs/RELEASE_LIFECYCLE_STANDARD.md) · 安全报告： [SECURITY.md](https://github.com/Cloto-dev/cpersona/blob/master/SECURITY.md). ### 发现了错误，或文档中未解释的内容？ 开启一个问题 — [错误报告](https://github.com/Cloto-dev/cpersona/issues/new?template=bug_report.yml) 或 [功能请求](https://github.com/Cloto-dev/cpersona/issues/new?template=feature_request.yml). 即使您不确定是否是错误，报告仍然是欢迎的。如果结果是配置问题，这仍然是有用的信号 — 这意味着文档不清晰，这本身就是一个缺陷。安全漏洞是一个例外：请通过 [SECURITY.md](https://github.com/Cloto-dev/cpersona/blob/master/SECURITY.md) 私密报告，而不是公开的问题。 ## 了解更多 - [Zenn 书（日语）](https://zenn.dev/cloto/books/claude-memory-mcp-server) — 完整的设计演练和设置指南 - [用外部内存替换 /compact（日语）](https://zenn.dev/cloto/articles/claude-code-compact-external-memory) — 会话结束 → `/clear` → `recall` 工作流的衡量令牌经济 - [内存系统设计](https://github.com/Cloto-dev/ClotoCore/blob/main/docs/CPERSONA_MEMORY_DESIGN.md) — 技术规范 - [ClotoCore](https://github.com/Cloto-dev/ClotoCore) — AI 代理平台 ## 许可证 MIT — 免费从任何 MCP 主机使用，无限制。