mcncarl/agent-memory-vault

Agent Memory Vault – 一个本地、Git 支持的长期记忆存储，适用于 Claude Code、Codex 及类似的 AI 编码代理

它是什么 – 一个基于 Python 的工具包，让 AI 编码代理能够在您自己的机器上维护一个持久、可审计的知识库。事实来源是一个纯文本 Markdown 目录（vault）。Git 跟踪每一次更改，SQLite 提供快速的全文搜索，可选的本地嵌入模型（EmbeddingGemma + Zvec）增加语义搜索。所有数据保持私有；公共仓库仅包含可复用的脚本和模板。

为什么重要 – 当前的 AI 编码助手（Claude Code、Codex 等）只记得当前聊天会话中说过的话。当项目跨越多个会话时，重要的事实、决策和代码片段会丢失。Agent Memory Vault 为这些代理提供了一个共享的、版本控制的记忆，它：

• 跨会话持久存在。
• 保证任何写入都经过审查、签名并记录在 Git 中。
• 允许多个代理（Codex、Claude、第三方“Ailu”）安全并发使用。
• 提供关键词和可选的向量搜索，同时保持权威的 Markdown 不变。

核心组件

组件	作用
templates/vault/	现成的 Markdown 布局，您可以复制到私有文件夹中。
scripts/bootstrap.py	创建新的 vault，初始化私有 Git 仓库，并写入初始的 INDEX.md。
scripts/memoryctl	统一的命令行界面，供代理用于搜索、检索、写入、迁移、健康检查等。
scripts/agent_memory_index.py	从 vault 构建 SQLite FTS 索引。
scripts/agent_memory_search.py	运行关键词 + 可选向量（Zvec）搜索并返回排名候选。
scripts/agent_memory_retrieve.py	重新打开选定的 Markdown 文件，验证哈希，并返回有界摘录。
scripts/agent_memory_write.py	实现 读取-准备-授权-应用 写入流程，带有围栏令牌和 Git 提交。
scripts/agent_memory_migrate.py	处理 vault 架构（v1 → v4）的升级，带有明确的备份和审计步骤。
scripts/agent_memory_closeout.py	完成写入，在 Git 中记录收据，并更新审计账本。
scripts/agent_memory_doctor.py	端到端健康检查套件，验证 vault、索引和运行时配置。

工作原理（高级流程）

1. 创建 vault – bootstrap.py 创建一个私有目录，复制 Markdown 模板，并将其提交到新的 Git 仓库。
2. 索引 – agent_memory_index.py 扫描 vault 并构建 SQLite FTS 表；可选地添加 Zvec 向量索引。
3. 搜索 – 代理调用 memoryctl --actor <agent> search "query"。CLI 合并关键词匹配，如果启用，还合并向量分数（混合 RRF），并返回 memory_id 列表。
4. 检索 – memoryctl retrieve --view section … 重新打开确切文件，检查存储的哈希是否仍与当前文件匹配，并返回安全摘录。
5. 写入 – 写入协议是：
   • write read-target → 获取当前字节和租约令牌。
   • write prepare → 提出新版本，获取单调递增的围栏令牌。
   • 授权（人工或策略）→ 批准提案。
   • write apply → CLI 验证租约、令牌、Git 基础，然后原子替换文件并记录收据。
   • closeout → 最终审计条目和 Git 提交。
6. 迁移/升级 – memoryctl --actor migration … 运行计划中的只读迁移，备份状态数据库，并且仅在明确审查后应用更改。

关键安全保证

• Git 支持的不可变性 – 每个接受的更改都是一个签名的 Git 提交；vault 可以回滚。
• 围栏令牌 – 防止过时的写入者覆盖较新的提案。
• 审计账本 – 所有读取、写入和状态转换都记录哈希、时间戳和风险分类。
• 隐私优先日志 – 搜索日志仅存储哈希和分类，从不存储原始查询或用户识别数据。
• 明确的风险类别 – 标记为 action_sensitive 的操作需要更严格的证据，并且不能降级。

安装（快速开始）

# 克隆仓库
git clone https://github.com/mcncarl/agent-memory-vault.git
cd agent-memory-vault

# 安装 POSIX 入口点（先计划然后应用）
python3 scripts/install-posix.py --plan \
  --memory-root "$HOME/agent-memory-vault" --no-host-hooks --json
python3 scripts/install-posix.py --apply \
  --memory-root "$HOME/agent-memory-vault" --no-host-hooks \
  --launchagent-backup-dir "$HOME/.config/agent-memory/backups/launchagent-NEW" \
  --json

--plan 步骤仅读取并报告将要发生的情况；--apply 执行实际的引导、Git 初始化和索引创建。

AI 代理的典型用法

# 搜索相关项目笔记
scripts/memoryctl --actor codex search "deployment boundary" --limit 5

# 安全检索特定部分
scripts/memoryctl --actor codex retrieve --view section \
  --file "项目/example.md" --project-id example-app \
  --section-id s0002 --expected-sha256 '<outline-sha256>' --json

# 提出新的决策记录（代理准备 markdown，然后请求人工批准）
scripts/memoryctl --actor codex write read-target --json <<'JSON'
{"schema_version":2,"target_relative_path":"决策/2024-10-17-deploy.md","app_id":"example-app","project_id":"example-project"}
JSON
# …人工审查提案 JSON，然后：
 scripts/memoryctl --actor codex write apply <proposal-id> --json

所有写入都经过相同的门控流程，保证 vault 永远不会包含未经审查的编辑。

可选语义搜索 – 如果您想要基于向量的检索，请安装额外的环境：

python3 -m venv .venv-vector
.venv-vector/bin/pip install -r requirements-vector.lock

向量层仅提供候选 ID；权威的 SQLite/Markdown 层仍执行最终过滤。

支持的平台 – macOS、Linux（POSIX 安装程序）和 Windows 10/11（PowerShell 安装程序）。核心代码是纯 Python 3.10+，没有外部服务；所有数据都保留在本地机器上。

成熟度 – 仓库包含完整的测试套件（scripts/run_tests_isolated.py）和“doctor”健康检查命令。该设计面向本地 AI 代理的生产级安全性，但它仍然是一个小众、自托管的工具，面向在自己的环境中运行 Claude Code、Codex 或类似代理的开发人员。

---

底线 – Agent Memory Vault 为您提供一个私有、版本控制、可搜索的知识库，多个 AI 编码代理可以安全地从中读取和写入。它弥合了短暂的聊天会话记忆与持久项目文档之间的差距，同时将数据保持在您的控制之下。