MemoBranch 是一个面向 AI Agent 的生产级、本地优先长期记忆层。它把对话中的证据、候选知识和正式记忆组织成一套可人工阅读的 Markdown Wiki，并用 Git 提供版本、归因、回滚与跨机器同步。
它借鉴 OpenKnowledge 的 Git + LLM Wiki 思路并独立实现，不包含其源码。生产版采用 OpenSpec 的 proposal → specs → design → tasks → implementation → verification 工作流完成。
[!IMPORTANT]
LLM 不是数据源。即使没有模型 API，捕获、审核、Git 版本、恢复、中文/英文检索、DeepSeek Harness 与 MCP 接入仍然可以完整工作。
💡 为什么需要它
普通 Agent 记忆常常只有一个向量库：内容从哪里来、为什么可信、谁修改过、冲突如何处理，都很难回答。
MemoBranch 把记忆变成一条可治理的知识链：
flowchart LR
A[对话 / 工具结果 / 人工输入] --> B[Evidence<br/>不可变证据]
B --> C[Candidate<br/>待审核候选]
C -->|批准 / 整合| D[Wiki Memory<br/>正式记忆]
C -->|证据不足 / 冲突| E[Review Queue<br/>人工处理]
D --> F[Lexical + Semantic + Graph<br/>混合检索]
F --> G[Agent Context<br/>按权限注入上下文]
D --> H[Git History<br/>归因 / 回滚 / 同步]
| 常见问题 | 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”的本地服务。它不包含浏览器编辑器、托管控制面、多租户数据库、分布式写入共识或自动语义冲突裁决。
🚀 快速开始
环境要求
- Node.js 20 或更新版本
- 可从
PATH 调用的 Git
安装
git clone https://github.com/sens-io/memobranch.git
cd memobranch
npm ci
npm run build
npm link
60 秒创建第一条记忆
# 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
检查运行状态：
amem doctor --root ~/my-agent-memory --json
🏗️ 工作原理
系统架构
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 数据布局
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 兼容接口后，可以开启自动提炼、基于记忆问答和语义检索：
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 中配置向量模型后：
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：
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 自动撤销全部工具注册。
[!NOTE]
MemoBranch 本身支持 Node.js 20+；官方 @deepseek-ai/dsh@0.1.2-rc.1 的当前依赖链要求 Node.js 22.19+。以所安装 Harness 版本的 engines 声明为准。
从本地源码安装
先构建 MemoBranch，再把项目目录安装到一个 Harness profile：
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
发布到 npm 后，也可以直接安装：
dsh plugin --profile personal-agent add memobranch
从 GitHub 安装时建议锁定 commit：
dsh plugin --profile personal-agent add github:sens-io/memobranch#<commit-sha>
Git 安装会通过 prepare 构建 TypeScript。pnpm 10 及更新版本需要在该 profile 的 pnpm-workspace.yaml 中显式允许 memobranch 的构建脚本；这等价于允许依赖在安装阶段执行代码，只应对可信且已锁定的提交授权。
配置
身份、权限、tenant、密钥和 provider 凭据仍通过下方 AMEM_* 环境变量由启动进程注入，模型不能在工具参数中覆盖它们。vaultRoot 留空时依次使用 AMEM_VAULT 和当前工作目录。
如需覆盖插件默认值，在 profile 的 cordis.patch.yml 中覆盖同一个插件行：
- 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 声明类型化参数和规范输出。工具不声明不安全的并行执行；取消信号会中止待处理的模型请求，并等待已拥有的 vault 工作停止后再返回。建议 Agent 在需要长期上下文的任务开始前调用 memory_context。
🔌 MCP 接入
构建完成后，把以下配置加入支持 MCP 的 Agent 工具。请将路径替换为实际绝对路径：
{
"mcpServers": {
"agent-memory": {
"command": "node",
"args": [
"/absolute/path/to/memobranch/dist/mcp.js",
"/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 工具
| 类别 | 工具 |
|---|
| 写入 | 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 都会被拒绝。
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、但最后的状态刷新失败，本地会保留与远端一致的已推送提交，使重试保持幂等。
🩺 生产运维
一次性维护
amem maintenance --root ~/my-agent-memory --json
一次维护周期依次执行事务恢复、到期处理、增量索引、健康检查和可选远端同步。相同状态下重复运行不会产生无意义 Git 提交。
长期服务
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 |
完整示例见 .env.example。
故障恢复 Runbook
- 停止所有写入者和守护进程，保留完整 vault 与
.amem/ 副本。
- 运行
amem doctor --root <vault> --json，记录配置、Git、索引和事务状态。
- 运行
amem recover --root <vault> --json；writing 事务回滚，ready 事务完整重放并提交。
- 运行
amem reindex --root <vault> --json，从 Markdown 重建缺失或损坏索引。
- 运行
amem remote status --root <vault> --json；出现 divergence 时人工检查，不绕过保护强推。
- 再次运行
doctor，仅在 healthy: true 后恢复服务和自动同步。
Git 对象损坏时，同步会被禁止。应从可信远端或备份恢复 .amem/git，不要删除工作树中的 Markdown 权威数据。master key 或 wrapped key 丢失时系统会失败关闭，请从受控密钥备份恢复。
⌨️ CLI 速查
| 任务 | 命令 |
|---|
| 初始化 | amem init [path] [--name NAME] |
| 捕获 / 提炼 | amem capture <text|-> [--extract] / amem extract <evidence-id> |
| 候选 | amem propose <statement> --key KEY |
| 审核 | amem consolidate / approve / reject |
| 遗忘 / 擦除 | amem forget <id|key> / amem erase <id|key> |
| 检索 / 上下文 | amem search <query> / context / ask / get |
| 诊断 / 恢复 | amem doctor / recover / reindex / maintenance |
| 远端 | amem remote set / status / sync / remove |
| 服务 | amem serve [--host 127.0.0.1] [--port 0] |
| 信息 | amem version / config / policy / history |
所有命令都支持 --root PATH；自动化场景建议统一使用 --json。
🔁 v1 → v2 迁移
amem config migrate --root ~/my-agent-memory --json
迁移会先创建 agent-memory.json.v1.bak，再加入租户、权限、索引、远端、维护和限制配置。旧版 evidence 摘要会升级且保留原 ID、路径与引用；扩大 policy.requireEncryptionFor 后，已有明文只有在显式迁移且提供 AMEM_MASTER_KEY 时才会被重写为加密信封。
遇到未来版本配置时，doctor 仍可提供只读诊断，但所有写入都会以 CONFIG_VERSION_UNSUPPORTED 失败关闭。
🧪 开发与发布门禁
npm run check
npm pack --dry-run
npm audit --omit=dev
OPENSPEC_TELEMETRY=0 openspec validate --all --strict
| Gate | 当前状态 |
|---|
| TypeScript build | ✅ PASS |
| CLI / MCP / DeepSeek Harness / Vault tests | ✅ 63 / 63 |
| 1,000 文档索引性能门禁 | ✅ PASS |
| npm package dry-run | ✅ PASS |
| 依赖漏洞审计 | ✅ 0 known vulnerabilities |
| OpenSpec strict validation | ✅ 6 / 6 specs |
测试覆盖租户隔离、策略化加密与迁移、恢复日志和 embedding 隔离、密码学擦除、权威索引复核、完整模式与跨文档引用、符号链接拒绝、证据不可变性、推送前后失败窗口、并发锁/租约/指标、事务回滚与重放、冲突闭环、CJK 检索、provider 边界，以及维护服务端点与优雅关闭。
规格与归档记录位于 openspec/；生产审计见 production-audit-remediation、independent-audit-remediation，最终生产收口见 close-final-production-gaps。
🧱 威胁模型与边界
本实现防护： MCP 或 Harness 调用者伪造身份、越权 scope/sensitivity 访问、机密明文进入 Git/索引/日志/指标/恢复日志、外层 Git 误收运行态、托管路径符号链接、部分写入、重复执行、远端 URL 凭据落盘、常见同步冲突和模型服务不可用。
本实现不防护： 已完全控制本机或进程内存的攻击者、恶意本机管理员、已导出明文、操作系统或备份泄漏、Git/LLM 供应链失陷、流量分析，以及第三方已经持有副本的删除。
生产部署仍需配合磁盘加密、最小文件权限、进程隔离、密钥轮换、受控备份和供应链扫描。
🙏 致谢
Built for agents that should remember — without forgetting where the truth came from.
MIT License · Local-first · Git-native
