# MemoBranch ### Memory that branches with your agents. [English](README.md) · **简体中文** 让 AI Agent 拥有可审计、可检索、可迁移的长期记忆 **Markdown 是事实源 · Git 记录每次演化 · LLM 只做可选增强**

为什么 • 核心能力 • 快速开始 • Web 管理 • 工作原理 • DeepSeek Harness • MCP 接入 • 生产运维

--- MemoBranch 是一个面向 AI Agent、面向生产场景的本地优先长期记忆层。它把对话中的证据、候选知识和正式记忆组织成一套可人工阅读的 Markdown Wiki，并用 Git 提供版本、归因、回滚与跨机器同步。它借鉴 [OpenKnowledge](https://github.com/inkeep/open-knowledge) 的 Git + LLM Wiki 思路并独立实现，不包含其源码。开发采用 [OpenSpec](https://github.com/Fission-AI/OpenSpec) 的 proposal → specs → design → tasks → implementation → verification 工作流；各能力是否验收，以对应版本的验证记录为准。 > **核心设计约束：** LLM Wiki 以 [Karpathy 的方法](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)为准：持续编译和维护有来源、互相链接的知识，而不是仅做向量检索。跨来源增量编译、显式查询成果回存和语义 Lint 已通过本地功能验收与隔离独立审查；详见[核心设计](docs/design/llm-wiki-core.md)和[逐项验收记录](openspec/changes/align-karpathy-llm-wiki/verification.md)。本地验收不等于 GitHub 托管 CI、真实模型效果或生产发布验证。 > [!IMPORTANT] > LLM 不是数据源。即使没有模型 API，捕获、审核、Git 版本、恢复、中文/英文检索、DeepSeek Harness 与 MCP 接入仍然可以完整工作。从原始资料到持续维护的知识网络，见 [Ingest / Query / Lint 使用指南](docs/wiki.md)：先查看多页待审计划，再显式应用；普通问答只读，答案回存和 Lint 修复均需单独授权。模型驱动的编译、问答和语义检查需要聊天模型，结构检查及原有记忆流程不依赖模型。 ## 💡 为什么需要它普通 Agent 记忆常常只有一个向量库：内容从哪里来、为什么可信、谁修改过、冲突如何处理，都很难回答。 MemoBranch 把记忆变成一条可治理的知识链： ```mermaid flowchart LR A[对话 / 工具结果 / 人工输入] --> B[Evidence
不可变证据] B --> C[Candidate
待审核候选] C -->|批准 / 整合| D[Wiki Memory
正式记忆] C -->|证据不足 / 冲突| E[Review Queue
人工处理] D --> F[Lexical + Semantic + Graph
混合检索] F --> G[Agent Context
按权限注入上下文] D --> H[Git History
归因 / 回滚 / 同步] ``` | 常见问题 | MemoBranch 的处理方式 | | --- | --- | | “这条记忆从哪里来？” | 每条正式记忆保留证据引用和 Git 历史 | | “新信息和旧信息冲突怎么办？” | 进入审核队列，不静默覆盖 | | “Agent 能不能自己声明管理员权限？” | 不能，身份与权限由服务端配置决定 | | “秘密会不会进 Git 或向量库？” | 敏感内容信封加密，逻辑键使用不透明路径，并排除出索引与生成文件 | | “写到一半进程崩了怎么办？” | 写前事务日志支持精确回滚或完整重放 | | “模型 API 挂了还能搜索吗？” | 自动降级到确定性的中英文词法检索 | ## ✨ 核心能力 | | 能力 | 说明 | | :---: | --- | --- | | 📚 | **Git-native Wiki** | Markdown 是权威数据；每次逻辑变更都有身份归因的 Git 提交 | | 🕸️ | **跨来源知识编译** | 规则和目录引导增量维护来源、实体、概念、综合、比较与查询页面；多页变更原子提交 | | 💬 | **有来源问答与回存** | 先导航再读取页面，答案绑定实际引用版本；显式保存保留来源限制和不确定性 | | 🧭 | **结构与语义维护** | 无模型也能检查结构；模型提供有证据的维护建议，修复需独立授权 | | 🧾 | **证据驱动记忆** | `evidence → candidates → wiki`，保留来源、置信度、条件与修订链 | | 🛡️ | **服务端访问控制** | 按 permission、scope、sensitivity、tenant 在读取内容前授权 | | 🔐 | **策略化信封加密** | 策略指定的任意敏感级别使用每记录 DEK + AES-256-GCM，并支持密码学擦除 | | 🔎 | **混合检索** | CJK/英文词法检索、可选 embeddings、Wiki 链接扩展与增量索引 | | 🔄 | **远端 Git 同步** | ahead/behind/diverged 状态、快进、常规合并、冲突中止和受控推送 | | 🧯 | **崩溃恢复** | 多文件写入先 journal，再原子替换；启动后自动回滚或重放 | | 🔌 | **CLI + Agent 插件** | CLI、MCP 与 DeepSeek Harness 原生插件，共享稳定错误和最小权限契约 | | 📈 | **生产可观测性** | 单实例维护服务、`/healthz`、Prometheus `/metrics`、脱敏审计 | | 🧩 | **OpenSpec 驱动** | proposal、规格、设计、任务、验证证据与归档完整留痕 | > [!NOTE] > 当前定位是“一租户一个 vault”的本地服务。Web 界面提供结构化管理，不支持任意编辑底层文件；不包含托管控制面、多租户数据库、分布式写入共识或自动语义冲突裁决。 ## 🚀 快速开始 ### 环境要求 - Node.js 20 或更新版本 - 可从 `PATH` 调用的 Git ### 安装从 [npm](https://www.npmjs.com/package/memobranch) 安装已发布的包，无需克隆源码或构建： ```bash npm install -g memobranch memobranch --help ``` 如需固定版本，使用 `npm install -g memobranch@1.1.0`。包提供 `memobranch` 和 `memobranch-mcp` 命令，以及下方示例使用的等价别名 `amem` 和 `amem-mcp`。 #### 从源码安装（开发用途） ```bash git clone https://github.com/sens-io/memobranch.git cd memobranch npm ci npm run build npm link ``` ### 60 秒创建第一条记忆 ```bash # 1. 创建 vault amem init ~/my-agent-memory --name personal-agent --json # 2. 捕获原始证据 amem capture "请记住：默认用中文简洁回答" \ --root ~/my-agent-memory \ --scope user \ --sensitivity internal \ --json # 3. 创建一个可审核候选 amem propose "用户偏好简洁的中文回答。" \ --root ~/my-agent-memory \ --key "回答语言与风格" \ --kind preference \ --scope user \ --confidence 0.95 \ --explicit \ --json # 4. 按策略整合为正式 Wiki 记忆 amem consolidate --root ~/my-agent-memory --json # 5. 检索并生成 Agent 上下文 amem search "用户喜欢怎样的回答" --root ~/my-agent-memory --json amem context "如何回复这个用户" --root ~/my-agent-memory ``` 检查运行状态： ```bash amem doctor --root ~/my-agent-memory --json ``` ## 🏗️ 工作原理 ### 系统架构 ```mermaid flowchart TB Agent[AI Agent / Human] --> CLI[CLI] Agent --> MCP[MCP Server] Agent --> DSH[DeepSeek Harness Plugin] CLI --> Policy[Identity & Policy] MCP --> Policy DSH --> Policy Policy --> Vault[Memory Vault] Vault --> TX[Transaction Journal] Vault --> Crypto[Envelope Encryption] Vault --> Search[Hybrid Search] Vault --> Git[Shadow Git Repository] TX --> Files[(Markdown Wiki)] Crypto --> Files Search --> Index[(Derived Index)] Git --> Remote[(Optional Git Remote)] Vault --> Ops[Maintenance Service] Ops --> Health["/healthz"] Ops --> Metrics["/metrics"] Ops --> Audit[(Redacted Audit)] ``` ### Vault 数据布局 ```text vault/ ├── agent-memory.json # v2 配置 ├── AGENTS.md # Agent 使用约束 ├── .gitignore # 防止外层 Git 误收 .amem 运行态 ├── evidence/ # 不可变原始证据 ├── candidates/ # 待审核候选 ├── wiki/ # 正式记忆 ├── MEMORY.md # 非机密常驻卡片（自动生成） ├── INDEX.md # 非机密目录（自动生成） ├── log.md # 不含正文的 Git 审计摘要 └── .amem/ ├── git/ # shadow Git 元数据 ├── keys.json # wrapped data keys，不进入 Git ├── transactions/ # 写前事务日志 ├── search-index.json # 可重建词法索引，不进入 Git ├── embeddings.json # 可重建向量缓存，不进入 Git ├── audit.jsonl # 结构化脱敏审计 └── metrics.json # 有界计数器与仪表 ``` ### 记忆治理规则 - `evidence/` 只追加原始证据，稳定哈希避免重复捕获。 - `candidates/` 保存提炼后的待审核知识；冲突和低置信内容不会自动进入正式记忆。 - `wiki/` 只保存审核后的正式记忆，是检索和上下文生成的权威来源。 - `procedure` 默认至少需要两份证据。 - 所有证据引用、晋升/取代关系和托管文档 ID 都会做跨文件完整性检查。 - 同一 `scope + kind + key` 的不同内容会形成显式冲突。 - 普通检索不会返回 `conflicted` 记录；拒绝最后一个冲突候选会恢复原正式记忆。 - LLM 提炼结果继承 evidence 的 scope，且敏感级别只能提高、不能降低。 - `forget` 是保留历史的可审计撤销；`erase` 额外销毁本地 wrapped data key。 ## 🔍 搜索与 LLM 增强基础检索无需任何模型：系统会对拉丁词、中文字符和 CJK bigram 建立持久化增量索引，并保证相同 vault 的排序可重复。配置 OpenAI 兼容接口后，可以开启自动提炼、基于记忆问答和语义检索： ```bash export AMEM_LLM_API_KEY="..." export AMEM_LLM_MODEL="gpt-4.1-mini" export AMEM_LLM_BASE_URL="https://api.openai.com/v1" amem capture "请记住：默认用中文简洁回答" \ --extract \ --root ~/my-agent-memory \ --json amem ask "我应该如何回复？" --root ~/my-agent-memory --json ``` 在 `agent-memory.json` 的 `index.embeddingModel` 中配置向量模型后： ```bash amem reindex --semantic --root ~/my-agent-memory --json amem search "回答偏好" --semantic --root ~/my-agent-memory --json ``` 向量服务不可用时，请求仍会返回词法和图关系结果，并报告 `semanticStatus: "degraded"`。任何加密文档都不会发送到 embedding API，即使之后调整了加密策略。 ## 🔐 安全与机密记忆 ### 信封加密首次读写策略要求加密的记录前，提供一个 32 字节 master key；默认策略覆盖 `sensitive` 与 `secret`，也可以扩展到 `internal` 或 `public`： ```bash export AMEM_MASTER_KEY="$(openssl rand -hex 32)" amem capture "仅授权 Agent 可见的机密内容" \ --root ~/my-agent-memory \ --sensitivity secret \ --json ``` 每条机密记录使用独立数据密钥，完整逻辑元数据和正文都经过 AES-256-GCM 认证加密。Git 跟踪文件只保留最小非敏感信封，文件名使用不透明 ID，提交主题也不会包含逻辑键。 > [!WARNING] > 不要把 `AMEM_MASTER_KEY` 写进仓库、配置、远端 URL 或 shell 历史。生产环境应通过操作系统密钥链、secret manager 或安全的进程注入提供。密钥恢复注意事项： - `.amem/keys.json` 保存由 master key 包装的数据密钥，不会通过 Git 同步。 - 初始化与后续迁移会在 vault 的 `.gitignore` 中维护 `.amem/`，避免被外层 Git 仓库误收。 - 跨主机读取机密记忆时，需要单独、安全地迁移 master key 与 `.amem/keys.json`。 - 丢失任意一项都会使对应历史密文不可恢复。 - `erase` 只能保证本 vault 不再具备解密能力，不能删除外部备份、已导出明文或第三方副本。 - `erase` 的理由会规范化后保存 SHA-256 承诺值，Git 中不会出现理由明文；旧版无理由摘要的恢复记录会如实标记为未记录。 - 策略加密记录不会进入 `MEMORY.md`、`INDEX.md`、持久化索引、向量 API、审计正文或指标标签；恢复日志也按同一策略加密。 - 证据 ID 同时绑定 scope、sensitivity、来源 URI 与正文；远端只能追加证据，不能改写或删除既有证据。 ### 权限模型 MCP 主体完全由服务端环境构造，调用者不能通过工具参数伪造身份或提升权限。 | 权限 | 用途 | | --- | --- | | `read` | 检索、读取与上下文生成 | | `write` | 捕获证据、创建候选 | | `review` | 整合、批准、拒绝与撤销 | | `sync` | 远端状态与同步 | | `maintain` | 恢复、索引、健康检查与守护服务 | | `admin` | 包含全部权限，并允许密码学擦除 | 授权会同时检查 `scope`、最高 `sensitivity` 与 `tenantId`，并且发生在解密、评分、图扩展、摘要生成和 embedding 请求之前。所有非管理员主体都必须绑定 vault 配置中的 `tenantId`；仅本地隐式管理员可以省略。 ## 🐋 DeepSeek Harness 插件 MemoBranch 可以作为原生 Cordis 插件直接进入 DeepSeek Harness 的工具注册表，不需要额外启动 MCP 子进程。插件遵循 Harness 生命周期，配置变化可热替换，卸载时由 Cordis 自动撤销全部工具注册。插件已使用 `@deepseek-ai/dsh-tools@0.1.2-rc.1` 验证，兼容范围声明为 `^0.1.2-rc.1`，包含该预发布版本及后续兼容的 `0.1` 稳定版本。 > [!NOTE] > MemoBranch 本身支持 Node.js 20+；官方 `@deepseek-ai/dsh@0.1.2-rc.1` 的当前依赖链要求 Node.js 22.19+。以所安装 Harness 版本的 `engines` 声明为准。 ### 从 npm 安装在已安装 DeepSeek Harness 的环境中，将 MemoBranch 直接添加到 Harness profile，无需单独全局安装 MemoBranch： ```bash dsh plugin --profile personal-agent add memobranch dsh --profile personal-agent --dump-config dsh --profile personal-agent ``` ### 从本地源码安装先构建 MemoBranch，再把项目目录安装到一个 Harness profile： ```bash cd /absolute/path/to/memobranch npm ci npm run build dsh plugin --profile personal-agent add /absolute/path/to/memobranch dsh --profile personal-agent --dump-config dsh --profile personal-agent ``` 从 GitHub 安装时建议锁定 commit： ```bash dsh plugin --profile personal-agent add github:sens-io/memobranch# ``` Git 安装会通过 `prepare` 构建 TypeScript。pnpm 10 及更新版本需要在该 profile 的 `pnpm-workspace.yaml` 中显式允许 `memobranch` 的构建脚本；这等价于允许依赖在安装阶段执行代码，只应对可信且已锁定的提交授权。 ### 配置身份、权限、tenant、密钥和 provider 凭据仍通过下方 `AMEM_*` 环境变量由启动进程注入，模型不能在工具参数中覆盖它们。`vaultRoot` 留空时依次使用 `AMEM_VAULT` 和当前工作目录。如需覆盖插件默认值，在 profile 的 `cordis.patch.yml` 中覆盖同一个插件行： ```yaml - id: memobranch-memory name: memobranch/deepseek-harness config: vaultRoot: /absolute/path/to/memory-vault defaultScope: project defaultSensitivity: internal defaultSearchLimit: 8 defaultMaxContextCharacters: 12000 ``` 配置由 Schemastery 在加载时校验。`defaultSearchLimit` 只允许 `1..50`，`defaultMaxContextCharacters` 只允许 `500..50000`；错误配置不会注册任何工具。 ### 最小权限工具集插件根据 `AMEM_PERMISSIONS` 收缩模型可见的工具，而 `MemoryVault` 在执行时再次授权： | 权限 | 可见工具 | | --- | --- | | `read` | `memory_context`, `memory_search`, `memory_get`, `memory_version`, `memory_config`, `memory_policy`, `memory_history` | | `write` | `memory_capture`, `memory_propose` | | `review` | `memory_consolidate`, `memory_review`, `memory_forget` | | `admin` | 全部工具，包括 `memory_erase` | | `maintain` | `memory_doctor`, `memory_recover`, `memory_reindex`, `memory_maintenance` | | `sync` | `memory_remote_status`, `memory_remote_sync` | 所有工具都通过官方 `defineTool` API 声明类型化参数和规范输出。`write`、`review`、`maintain`、`sync` 可以单独授予：操作所需的内部读取使用对应权限，但不会因此开放 `memory_get` 或 `memory_search`。作用域、敏感等级与 tenant 检查保持有效。启用维护自动同步时还需授予 `sync`。取消按调用隔离，不会中止其他会话的模型请求。等待锁或尚未进入提交阶段的写入会停止并回滚；已经进入提交阶段的事务、恢复和密码学擦除会安全收尾，然后返回 `OPERATION_CANCELLED`。若已产生提交，错误的 `details.committed` 会列出操作与提交号；取消后不会再启动提炼或后续写入。插件卸载会取消并等待其拥有的调用完成清理。 Git 命令默认最多运行 30 秒，可通过 `AMEM_GIT_TIMEOUT_MS` 调整（`1..300000` 毫秒），取消或超时会终止所属传输进程。已确认成功的推送不会被本地回滚；若推送在确认前被中断，远端结果可能不确定，应先检查远端状态再重试。建议 Agent 在需要长期上下文的任务开始前调用 `memory_context`。 ## 🖥 Web 管理界面本机管理台提供总览、授权记忆与证据浏览、捕获和候选审核、Wiki 工作流、配置、健康检查及 Git 历史。 > [!NOTE] > 自 npm `1.1.0` 起提供。安装或升级后即可启动： ```bash npm install -g memobranch@1.1.0 memobranch web --root /absolute/path/to/memory-vault --port 0 ``` 如尚未初始化 vault，先运行 `memobranch init /absolute/path/to/memory-vault`。打开终端显示的 `http://127.0.0.1:` 地址，再输入单独显示的 token。`--port 0` 自动选择空闲端口，也可指定 `--port 3210` 等固定端口；按 Ctrl+C 停止。维护者：[一键 npm 发布与失败恢复指南](docs/releasing.md)。 - **记忆管理：** 筛选与分页、查看来源、捕获证据、提出候选、批准／拒绝及撤回记忆。 - **LLM Wiki：** 浏览页面、生成摄取计划、只读问答、明确生成答案回存计划、结构／语义 Lint，以及单独批准计划；目的与规则编辑带版本检查。 - **配置：** 管理员可修改不含秘密的运行参数，过期页面无法覆盖较新的配置；身份、租户、凭据、加密策略和远端 URL 不在网页中管理。 - **运维：** 健康检查、历史、词法索引重建、事务恢复，以及显式同步已配置的 Git 远端。Web 模式不会启动后台维护调度器。中文界面随包提供，不依赖 CDN。服务仅监听 `127.0.0.1`，校验访问令牌及精确 Host/Origin，并继承启动进程的 `AMEM_*` 身份与权限限制。请保管好令牌；它仅留在页面内存，刷新页面需重新输入，重启服务会轮换。不要通过公共代理暴露此管理台。Web 工作流不提供不可逆密钥擦除，请使用可信终端操作。 ## 🔌 MCP 接入执行 `npm install -g memobranch` 后，把以下配置加入支持 MCP 的 Agent 工具。请先初始化 vault（见快速开始），将其路径替换为实际绝对路径，并将 `agent-memory.json` 中的 `tenantId` 填入 `AMEM_TENANT_ID`： ```json { "mcpServers": { "agent-memory": { "command": "memobranch-mcp", "args": [ "/absolute/path/to/memory-vault" ], "env": { "AMEM_ACTOR_ID": "workspace-agent", "AMEM_ACTOR_NAME": "Workspace Agent", "AMEM_PERMISSIONS": "read,write,review", "AMEM_ALLOWED_SCOPES": "user,project", "AMEM_MAX_SENSITIVITY": "internal", "AMEM_TENANT_ID": "copy-from-agent-memory-json" } } } } ``` MCP 客户端必须能从 `PATH` 找到 Node.js、Git 和 `memobranch-mcp`。桌面客户端可能不会继承终端的 `PATH`，必要时请显式配置。可用 `command -v memobranch-mcp`（Windows：`where memobranch-mcp`）查询已安装命令的位置。如使用源码安装，构建后保留相同的 `env` 设置，改用 `"command": "node"` 和 `"args": ["/absolute/path/to/memobranch/dist/mcp.js", "/absolute/path/to/memory-vault"]`。 ### MCP 工具 | 类别 | 工具 | | --- | --- | | 写入 | `memory_capture`, `memory_propose` | | 检索 | `memory_search`, `memory_context`, `memory_get` | | 审核 | `memory_consolidate`, `memory_review`, `memory_forget`, `memory_erase` | | 运维 | `memory_doctor`, `memory_recover`, `memory_reindex`, `memory_maintenance` | | Git | `memory_history`, `memory_remote_status`, `memory_remote_sync` | | 信息 | `memory_version`, `memory_config`, `memory_policy` | 所有 MCP 错误都使用稳定错误码和 `isError: true` 返回，不暴露堆栈或秘密，也不会终止服务器。建议 Agent 在处理依赖长期上下文的任务前调用 `memory_context`。 ## 🌐 远端 Git 同步远端认证完全委托给 Git credential helper 或 SSH agent。CLI 和 MCP 不接受 token 参数；带 userinfo、query、fragment 或非 `git` SCP 用户名的 URL 都会被拒绝。 ```bash amem remote set git@github.com:org/memory-vault.git \ --root ~/my-agent-memory \ --name origin \ --branch main \ --json amem remote status --root ~/my-agent-memory --json amem remote sync --root ~/my-agent-memory --push --json ``` 同步顺序：恢复未完成事务 → 检查工作树 → fetch → 计算 ahead/behind → 快进或常规 merge → 证据只追加校验 → 重建派生状态 → 模式、引用、符号链接、机密编码与健康校验 → 可选 push。在 push 成功前发生内容冲突、后置校验或传输失败时，系统会恢复同步前的本地 HEAD、受管工作树和同步状态，不会自动强推。如果远端已成功接受 push、但最后的状态刷新失败，本地会保留与远端一致的已推送提交，使重试保持幂等。 ## 🩺 生产运维 ### 一次性维护 ```bash amem maintenance --root ~/my-agent-memory --json ``` 一次维护周期依次执行事务恢复、到期处理、增量索引、健康检查和可选远端同步。相同状态下重复运行不会产生无意义 Git 提交。 ### 长期服务 ```bash amem serve \ --root ~/my-agent-memory \ --host 127.0.0.1 \ --port 9464 curl http://127.0.0.1:9464/healthz curl http://127.0.0.1:9464/metrics ``` - HTTP 服务只接受回环地址。 - `.amem/service.json` 维护单实例租约，存活进程不会被抢占。 - 租约包含实例所有权令牌；只有持有者能更新或释放，启动末端失败会清理监听器、端口与自有租约。 - 受管目录变更会防抖后触发增量索引；原生文件监听不可用时自动降级为有界轮询。 - `SIGTERM` / `SIGINT` 会等待正在执行的事务安全结束。 - 最近一次 `doctor` 不健康或维护周期失败时，`/healthz` 返回 HTTP 503 和 `status: "unavailable"`。 - 指标采用固定名称和有界标签，不包含正文、密钥、凭据或源 URI。建议使用 systemd、launchd 或容器编排器管理进程，并通过安全环境注入配置。

环境变量参考

| 变量 | 含义 | 默认值 | | --- | --- | --- | | `AMEM_VAULT` | MCP / DeepSeek Harness vault 路径 | 当前目录 | | `AMEM_ACTOR_ID` | Git 与审计主体 ID | `agent` | | `AMEM_ACTOR_NAME` | Git 与审计主体名称 | 主体 ID | | `AMEM_ACTOR_EMAIL` | 可选 Git 邮箱 | 空 | | `AMEM_PERMISSIONS` | 权限列表 | MCP 默认为 `read` | | `AMEM_ALLOWED_SCOPES` | 允许的 scope 列表 | 全部 | | `AMEM_MAX_SENSITIVITY` | 最高敏感级别 | `internal` | | `AMEM_TENANT_ID` | 非管理员必填；复制 vault 配置中的 `tenantId` | 无，缺失时拒绝访问 | | `AMEM_MASTER_KEY` | 信封加密 master key | 空，机密操作失败关闭 | | `AMEM_LLM_API_KEY` | OpenAI 兼容 API 凭据 | 空 | | `OPENAI_API_KEY` | `AMEM_LLM_API_KEY` 的兼容来源 | 空 | | `AMEM_LLM_MODEL` | 提炼与问答模型 | `gpt-4.1-mini` | | `AMEM_LLM_BASE_URL` | OpenAI 兼容 API 根地址 | `https://api.openai.com/v1` | | `AMEM_EMBEDDING_MODEL` | 可选向量模型 | 空，仅词法检索 | | `AMEM_LLM_TIMEOUT_MS` | 单次 provider 请求总超时 | `30000` | | `AMEM_LLM_MAX_RESPONSE_BYTES` | provider 最大响应字节数 | `2000000` | | `AMEM_LLM_MAX_RETRIES` | 429/5xx/网络失败的有限重试次数 | `1` | | `AMEM_GIT_TIMEOUT_MS` | 单条 Git 命令及传输进程的超时（1–300000 毫秒） | `30000` | 完整示例见 [`.env.example`](./.env.example)。

故障恢复 Runbook

1. 停止所有写入者和守护进程，保留完整 vault 与 `.amem/` 副本。 2. 运行 `amem doctor --root --json`，记录配置、Git、索引和事务状态。 3. 运行 `amem recover --root --json`；先恢复未完成的同步快照，再回滚 `writing` 事务或重放 `ready` 事务。恢复未成功前，后续写入会被阻止。 4. 运行 `amem reindex --root --json`，从 Markdown 重建缺失或损坏索引。 5. 运行 `amem remote status --root --json`；出现 divergence 时人工检查，不绕过保护强推。 6. 再次运行 `doctor`，仅在 `healthy: true` 后恢复服务和自动同步。 Git 对象损坏时，同步会被禁止。应从可信远端或备份恢复 `.amem/git`，不要删除工作树中的 Markdown 权威数据。master key 或 wrapped key 丢失时系统会失败关闭，请从受控密钥备份恢复。同步明确失败时会恢复原 HEAD、受管文件和同步状态；重置或清理失败会保留 `.amem/sync-intent.json`，排除占用或文件系统故障后可重试恢复。远端已接收的推送不回滚。如果传输中断导致结果未知，恢复还需 `sync` 权限来确认远端包含该提交；仅有 `maintain` 权限不会访问远端。未能确认时保持阻塞，请检查远端和备份，不要直接删除恢复记录或强推。为保证这一边界，一次同步只支持一个推送目的地。

## ⌨️ CLI 速查 | 任务 | 命令 | | --- | --- | | 初始化 | `amem init [path] [--name NAME]` | | 捕获 / 提炼 | `amem capture [--extract]` / `amem extract ` | | 候选 | `amem propose --key KEY` | | 审核 | `amem consolidate` / `approve` / `reject` | | 遗忘 / 擦除 | `amem forget ` / `amem erase ` | | 检索 / 上下文 | `amem search ` / `context` / `ask` / `get` | | 诊断 / 恢复 | `amem doctor` / `recover` / `reindex` / `maintenance` | | 远端 | `amem remote set` / `status` / `sync` / `remove` | | 服务 | `amem serve [--host 127.0.0.1] [--port 0]` | | Web 管理（源码构建） | `amem web --root PATH [--port 0]` | | 信息 | `amem version` / `config` / `policy` / `history` | | Wiki 编译 / 审核 | `amem wiki ingest ` / `wiki apply --file PLAN.json` | | Wiki 导航 / 回存 | `amem wiki catalog` / `wiki query ` / `wiki file --file ANSWER.json --title TITLE` | | Wiki 规则 / 维护 | `amem wiki rules` / `set-rules` / `migrate` / `lint [--semantic]` / `revoke` | 所有命令都支持 `--root PATH`；自动化场景建议统一使用 `--json`。 ## 🔁 v1 → v2 迁移 ```bash amem config migrate --root ~/my-agent-memory --json ``` 迁移会先创建 `agent-memory.json.v1.bak`，再加入租户、权限、索引、远端、维护和限制配置。旧版 evidence 摘要会升级且保留原 ID、路径与引用；扩大 `policy.requireEncryptionFor` 后，已有明文只有在显式迁移且提供 `AMEM_MASTER_KEY` 时才会被重写为加密信封。遇到未来版本配置时，`doctor` 仍可提供只读诊断，但所有写入都会以 `CONFIG_VERSION_UNSUPPORTED` 失败关闭。 ## 🧪 开发与发布门禁 ```bash npm run check npm pack --dry-run npm run test:package npm audit --omit=dev OPENSPEC_TELEMETRY=0 openspec validate --all --strict ``` | Gate | 验证要求 | | --- | --- | | TypeScript build | 严格编译通过 | | CLI / MCP / DeepSeek Harness / Vault tests | 目标提交完整套件通过；覆盖 `main` / `master` 默认分支 | | 1,000 文档索引性能门禁 | 索引与检索符合测试预算 | | 安装包 | 打包后安装到独立消费者，验证导出、Bundle 和真实 Harness 调用 | | 依赖漏洞审计 | 发布时重新运行生产依赖审计 | | OpenSpec strict validation | 规格、变更与验收记录保持一致 | 结果绑定具体提交与环境，不能用这里的静态表格代替最新 [GitHub CI](https://github.com/sens-io/memobranch/actions) 或独立审查。测试覆盖租户隔离、策略化加密与迁移、恢复日志和 embedding 隔离、密码学擦除、权威索引复核、完整模式与跨文档引用、符号链接拒绝、证据不可变性、推送前后失败窗口、并发锁/租约/指标、事务回滚与重放、冲突闭环、CJK 检索、provider 边界，以及维护服务端点与优雅关闭。规格与归档记录位于 [`openspec/`](./openspec)；生产审计见 [`production-audit-remediation`](./openspec/changes/archive/2026-09-03-production-audit-remediation)、[`independent-audit-remediation`](./openspec/changes/archive/2026-09-03-independent-audit-remediation)，最终生产收口见 [`close-final-production-gaps`](./openspec/changes/archive/2026-09-04-close-final-production-gaps)。 ## 🧱 威胁模型与边界 **本实现防护：** MCP 或 Harness 调用者伪造身份、越权 scope/sensitivity 访问、机密明文进入 Git/索引/日志/指标/恢复日志、外层 Git 误收运行态、托管路径符号链接、部分写入、重复执行、远端 URL 凭据落盘、常见同步冲突和模型服务不可用。 **本实现不防护：** 已完全控制本机或进程内存的攻击者、恶意本机管理员、已导出明文、操作系统或备份泄漏、Git/LLM 供应链失陷、流量分析，以及第三方已经持有副本的删除。生产部署仍需配合磁盘加密、最小文件权限、进程隔离、密钥轮换、受控备份和供应链扫描。 ## 🙏 致谢 - [Karpathy — LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)：持久增量知识编译与 Ingest / Query / Lint 核心方法。 - [nashsu/llm_wiki](https://github.com/nashsu/llm_wiki)：Wiki 工作流与验收方法的实现参考；未复制其源码。 - [OpenKnowledge](https://github.com/inkeep/open-knowledge)：Git 驱动的本地 Markdown / LLM Wiki 架构灵感。 - [OpenSpec](https://github.com/Fission-AI/OpenSpec)：规格驱动的生产开发与归档流程。 - [Model Context Protocol](https://modelcontextprotocol.io/)：Agent 与记忆服务之间的标准工具接口。 - [DeepSeek Harness](https://deepseek-harness.github.io/deepseek-harness/develop/basic/)：原生 Cordis 插件、配置和类型化工具接口。 ---

**Built for agents that should remember — without forgetting where the truth came from.** MIT License · Local-first · Git-native