dna-memory

<div align="center"> # DNA Memory **面向 Codex、Claude Code、Claude Desktop、Hermes 与 Obsidian 的本地优先统一记忆层** [](https://github.com/AIPMAndy/dna-memory/stargazers) [](https://github.com/AIPMAndy/dna-memory) [](https://www.python.org/) [English](./README_EN.md) | 简体中文 | [快速上手](./QUICKSTART.md) </div> **想给 Claude Code、Codex 加长期记忆？** DNA Memory 是一个本地优先的 AI Agent 记忆 MCP。一个 Markdown / Obsidian 目录当长期记忆，Codex、Claude Code、Claude Desktop、Hermes 通过同一个 MCP 服务读写，不用每个工具各记一套。 *English: a local-first memory MCP server that gives Claude Code, Codex, Claude Desktop and Hermes one shared long-term memory in Markdown.* > **适合谁**：同时用 Codex、Claude Code、Claude Desktop 或 Hermes，受够了每个工具各记一套、互相打架的人。 > 一个 Markdown / Obsidian 目录当长期记忆，所有客户端通过同一个 MCP 服务读写。[快速上手 →](./QUICKSTART.md) DNA Memory 把一个 Markdown/Obsidian 目录作为长期记忆真源，把 SQLite 作为可删除、可重建的索引。多个 AI 客户端通过同一个 MCP 服务召回、写入和反馈， 不再各自维护互相冲突的长期记忆副本。 它不会把“保存所有聊天记录”等同于“形成记忆”。完整会话仍由原客户端保管； DNA Memory 只保存有界来源指针、经过审查的提案，以及验证后的关键结论。 ## 核心理念：从对话数据到可复用认知 > **DNA Memory 不把“保存对话”视为“形成记忆”。** 它受人类大脑记忆形成 > 机制启发，把跨客户端的大量对话视为原始感知输入，通过信号提取、重要性与 > 置信度加权、认知分型、验证结晶、召回反馈和新旧认知替代，持续把数据抽象为 > 可复用认知。 它不是另一个无限增长的聊天数据库。原始会话只是形成认知的材料；只有经过筛选、 验证并值得在未来任务中复用的结论，才会进入长期记忆真源。 ## 核心策略：先处理记忆，再存储记忆 DNA Memory 的核心不是把更多对话塞进数据库，而是给 Agent 一套接近人类记忆 形成过程的处理策略。Agent 把对话当作原始感知输入，只有经过策略闸门的内容， 才可能成为可复用的长期认知： 1. **感知边界**：只读取有界来源和必要的生命周期元数据，不把完整 transcript 当作长期记忆。 2. **信号筛选**：过滤操作话术、临时状态、凭证和无法复用的噪声。 3. **加权判断**：结合重要性、置信度、来源和后续使用反馈，判断一条信息是否值得保留。 4. **认知分型**：把信号分为偏好、事实、洞察、决策、项目状态、开放事项、工作流和错误教训。 5. **验证结晶**：只有安全、短小、可追溯且经过验证的结论，才写入 Markdown 真源。 6. **召回与反馈**：在新任务开始前按关键词召回；只有真正影响任务的结果才反馈 `useful` 或 `misleading`。 7. **演化与遗忘**：重复认知被精确去重，失效认知通过显式 `supersedes` 替代， 原始来源指针和过期候选按保留策略清理。 这是一种受仿生学启发的工程策略，不声称复制人脑。它的目标是让 Agent 具备 “筛选—加权—抽象—验证—召回—修正”的记忆行为，而不是拥有一个不断膨胀的聊天 存档库。DNA Memory 的质量应看高质量认知是否被正确复用，而不是看保存了多少文本。 ```text 大量原始对话 -> 有界采集与信号提取 -> 重要性、置信度与使用反馈加权 -> 认知分型 -> 验证后结晶为长期认知 -> 按当前任务召回 -> useful / misleading 反馈与 supersedes 演化 ``` 当前工程实现将长期认知分为四组、八种类型： | 认知模型 | 记忆类型 | 用途 | |---|---|---| | 个体倾向 | `preference` | 稳定偏好与协作习惯 | | 事实与洞察 | `fact`, `insight` | 已验证事实与从事实中抽象出的认识 | | 决策与状态 | `decision`, `project_state`, `open_loop` | 决策理由、当前状态和待闭环事项 | | 程序与经验 | `workflow`, `error_lesson` | 可复用流程和经过验证的失败经验 | 这里的仿生学是设计启发，不是对人脑的完整复刻。DNA Memory 的价值不取决于 保存了多少对话，而取决于形成了多少高质量认知，以及这些认知是否在后续决策中 被准确召回和有效复用。 ## 核心边界 - Markdown 是长期真源，SQLite 是索引和遥测层。 - `memory_remember` 写入的是短小、可复用结论，不是 transcript。 - 自动导入默认只保存 session ID、路径、哈希、偏移和计数。 - 自动提炼每个会话最多产生 3 条候选，每条最多 800 字符。 - 凭证、私钥、常见 token 和疑似敏感内容会被拒绝。 - 普通 Claude Desktop 云端聊天没有稳定本地正文来源时，只能显式 MCP 写回。 - 任何客户端的记忆故障都不应阻塞主任务。 ## 架构 ```text Codex / Claude / Hermes | | stdio MCP v memory_recall / remember / feedback | +--> Markdown vault <- durable source of truth | +--> SQLite index <- rebuildable search + telemetry | +--> bounded candidates <- pointers and reviewable proposals Native client histories remain in their original stores. ``` ## 安装 ```bash git clone https://github.com/AIPMAndy/dna-memory.git \ "$HOME/.local/share/dna-memory/app" cd "$HOME/.local/share/dna-memory/app" python3 -m venv "$HOME/.local/share/dna-memory/mcp-venv" "$HOME/.local/share/dna-memory/mcp-venv/bin/pip" install \ -r requirements-mcp.txt mkdir -p "$HOME/.config/dna-memory" "$HOME/Documents/DNA-Memory-Vault/Memory" cp docs/profiles/profile.example.json \ "$HOME/.config/dna-memory/profile.json" ``` 按需编辑仓库外的 profile： ```json { "knowledge_root": "~/Documents/DNA-Memory-Vault", "database_path": "~/.local/share/dna-memory/memory.db", "managed_memory_dir": "Memory", "skill_root": "~/.agents/skills", "skill_registry": "~/.config/dna-memory/skills.json", "platform_skill_roots": { "codex": "~/.codex/skills", "claude": "~/.claude/skills", "hermes": "~/.hermes/skills" } } ``` ```bash export DNA_MEMORY_PROFILE="$HOME/.config/dna-memory/profile.json" python3 dna.py memory status --json python3 dna.py memory reindex --json ``` ## 接入三个客户端 以下命令让 Codex、Claude Code 和 Hermes 指向同一个 profile 与 MCP 服务： ```bash ROOT="$HOME/.local/share/dna-memory/app" PYTHON="$HOME/.local/share/dna-memory/mcp-venv/bin/python" PROFILE="$HOME/.config/dna-memory/profile.json" codex mcp add dna-memory \ --env "DNA_MEMORY_PROFILE=$PROFILE" \ -- "$PYTHON" "$ROOT/scripts/memory_mcp.py" claude mcp add --scope user dna-memory \ -e "DNA_MEMORY_PROFILE=$PROFILE" \ -- "$PYTHON" "$ROOT/scripts/memory_mcp.py" hermes mcp add dna-memory \ --command "$PYTHON" \ --env "DNA_MEMORY_PROFILE=$PROFILE" \ --args "$ROOT/scripts/memory_mcp.py" ``` 验收时不要只看配置文件： ```bash codex mcp get dna-memory claude mcp get dna-memory hermes mcp test dna-memory ``` Claude Desktop 使用 `mcpServers` 配置，且 JSON 中必须是绝对路径。安全迁移、 备份和回滚见 [客户端接入文档](docs/mcp-and-client-adapters.md)。 ## MCP 工具 | 工具 | 用途 | |---|---| | `memory_recall` | 用 1 至 4 个独立关键词召回活跃记忆 | | `memory_get` | 按稳定 ID 获取单条记忆和替代关系 | | `memory_remember` | 写入验证后的长期结论 | | `memory_feedback` | 标记召回结果 `useful` 或 `misleading` | | `memory_close_session` | 保存有界会话来源指针 | | `memory_status` | 查看真源和索引状态 | | `memory_reindex` | 从 Markdown 重建 SQLite 索引 | 推荐将 [dna-memory-loop](skills/dna-memory-loop/SKILL.md) 分发到各客户端。 它规定了同一套行为：任务前召回、确实使用后反馈、验证后才写回。 ## 日常操作 ```bash # 真源、容量与索引状态 python3 dna.py memory status --json # 客户端来源、自动捕获和 MCP 边界 python3 dna.py memory coverage --json # 召回、命中、反馈、写回和积压指标 python3 dna.py memory value --json # 从 Markdown 重建索引 python3 dna.py memory reindex --json # 结晶安全提案、清理候选、备份、完整性检查 python3 dna.py memory maintain daily --json python3 dna.py memory maintain weekly --json python3 dna.py memory maintain monthly --json ``` `memory value` 将真正待审的 `backlog.reviewable_proposals` 与来源指针、 生命周期事件分开统计。`backlog.pending` 只是 `total_pending` 的兼容别名， 不能解释为待审记忆数量。`clients` 中的 `recall_hits` 和 `recall_share` 用于 观察 Codex、Claude、Hermes 的主动召回采用情况；占比不代表召回质量。 daily 维护结果中的 `crystallized` 表示新建长期认知，`deduplicated` 表示候选 已命中同类型、同规范化摘要的 active 记忆。重复候选不会创建第二份 Markdown； 其新的来源和客户端会合并到既有记忆的 provenance 字段中。系统只做精确文本去重， 不使用模糊相似度自动合并不同结论。 当新证据明确使旧结论失效时，调用 `memory_remember` 并显式传入旧 ID： ```json { "type": "project_state", "summary": "客户端接入已经通过真实召回与写回验收。", "supersedes": ["mem_old_unverified"] } ``` 旧 Markdown 会保留并改为 `superseded`；默认召回只返回 active 结论。 系统不会仅按项目或类型猜测冲突。 ## 自动导入与提炼 可按需要运行： ```bash python3 scripts/import_codex_rollouts.py python3 scripts/import_claudian_sessions.py python3 scripts/import_claude_desktop_sessions.py python3 scripts/import_hermes_sessions.py python3 scripts/import_native_history.py ``` 导入器使用检查点和幂等事件 ID。普通事件只保存指针；只有显式 `DNA_MEMORY_PROPOSAL {JSON}` 或通过有界信号提取的短结论才进入候选队列， 并且仍需经过 daily 维护的类型、敏感信息、容量和去重检查。 规则升级时先在独立临时数据库回测最近 7 天，再做有界生产重提取。导入器只输出 聚合计数；自动结果仍进入 `memory_proposal`，不会绕过人工检查和 daily 安全结晶： ```bash python3 -m scripts.import_native_history --backtest-days 7 \ --backtest-db /tmp/dna-memory-backtest.db python3 -m scripts.import_native_history --reextract-days 7 ``` 只有人工抽查误采集率不高于 10% 且敏感泄露为 0 时才运行生产重提取。完整操作与 回滚边界见 [`docs/mcp-and-client-adapters.md`](docs/mcp-and-client-adapters.md)。 这意味着“扫描到了会话”不等于“已经形成长期认知”。衡量系统价值时应同时看： 1. 自动捕获覆盖率。 2. 长期记忆写入数量。 3. 召回命中率与 `useful` 反馈。 4. 是否减少重复说明和重复错误。 ## 跨客户端 Skill 管理 共享 Skill 真源与记忆真源分开管理。注册表只声明 DNA Memory 有权分发的 Skill，注册表外的客户端专属目录不会被删除或覆盖。 ```bash cp assets/skills.example.json "$HOME/.config/dna-memory/skills.json" python3 dna.py skills inventory --json python3 dna.py skills doctor --json python3 dna.py skills sync --json python3 dna.py skills sync --apply --json ``` `sync` 默认 dry-run，`--apply` 只创建缺失符号链接。详见 [Skill 管理](docs/skill-management.md)。 ## 隐私与公开安全 仓库不包含真实 profile、数据库、会话、记忆 JSON、个人 Skill 或内部部署记录。 发布前运行： ```bash python3 scripts/check_public_safety.py ``` 本地 profile、备份、SQLite 和 Markdown vault 不应位于 Git 仓库内。 如果曾误提交凭证，仅删除文件不够，还必须撤销凭证并清理 Git 历史。 ## 开发验证 ```bash python3 -m pytest -q python3 -m compileall -q dna.py dna scripts tests python3 scripts/check_public_safety.py git diff --check ``` ## 常见问题 FAQ ### Claude Code 怎么加长期记忆？ 按上面的步骤装好 DNA Memory，再用 `claude mcp add --scope user dna-memory` 把它接成 MCP 服务，最后用 `claude mcp get dna-memory` 检查是否接好。记忆存在你自己的 Markdown / Obsidian 目录里。 ### 它和其他 AI Agent 记忆 MCP 有什么不同？ Codex、Claude Code、Hermes 共用同一个 MCP 服务和同一份 Markdown 记忆。它只写入短小、验证过的结论，完整会话仍然留在原来的客户端里。 ### 记忆存在哪里，会上传吗？ Markdown 目录是长期真源，SQLite 只是可以删除、可以重建的索引，都放在你自己的电脑上。 ### 会不会把密钥写进记忆？ 不会。凭证、私钥、常见 token 和疑似敏感内容会被拒绝写入。 ### 支持哪些客户端？ Codex、Claude Code、Claude Desktop 和 Hermes，记忆目录可以直接用 Obsidian 打开。Claude Desktop 用 `mcpServers` 配置，JSON 里必须写绝对路径。 ### 有哪些 MCP 工具？ `memory_recall`、`memory_get`、`memory_remember`、`memory_feedback`、`memory_close_session`、`memory_status`、`memory_reindex`，一共 7 个，用途见上面的 [MCP 工具](#mcp-工具) 表。 <!-- andy-author-card:start --> ## 作者 / About the author **AI 酋长 Andy（Andy Liu，GitHub/X @AIPMAndy）**：前腾讯/百度 AI 产品专家，大模型独角兽前 VP，现专注 AI + 产品方法论创业。 可以找我聊求职咨询、AI 增长和副业陪跑，服务范围和费用先沟通确认。 微信 `AIPMAndy`（备注「DNA Memory」）· [X @AIPMAndy](https://x.com/AIPMAndy) · [Telegram @AIPMAndy](https://t.me/AIPMAndy) · [个人官网 metaver.vip](https://metaver.vip/) · [Grok Bot 中文攻略](https://aipmandy.github.io/grok-bot-handbook/) *AI Chief Andy (Andy Liu, @AIPMAndy on GitHub and X) is a former Tencent and Baidu AI product expert and former VP at an LLM unicorn, now a serial entrepreneur focused on AI and product methodology.* ### 作者的其他项目 - [AndySoul](https://github.com/AIPMAndy/AndySoul)：CLAUDE.md / AGENTS.md 规则模板，让 Claude Code、Codex、Cursor 少犯错 - [goskill](https://github.com/AIPMAndy/goskill)：长任务执行助手：先定成功标准，再按标准验收 - [Grok Bot 中文攻略](https://github.com/AIPMAndy/grok-bot-handbook)：Grok Bot / AI Agent 中文教程，26 章加 40 套任务指令 - [OpenClaw Skills 中文精选](https://github.com/AIPMAndy/awesome-openclaw-skills-CN)：2868 个 OpenClaw Skills 分类整理，附国产模型接入指南 - [FreeToken](https://github.com/AIPMAndy/FreeToken)：免费 AI API、免费大模型 API 额度合集 <!-- andy-author-card:end --> ## License [Apache-2.0](LICENSE)