Vault-Agent-Memory

# 智能代理内存 [English](README.md) | [繁體中文](README.zh-Hant.md) | [简体中文](README.zh-CN.md) 为智能代理提供本地优先的内存治理。 智能代理内存为Codex、Claude Code、Hermes、OpenClaw、n8n、Coze等智能代理提供了一个可治理的共享内存库。它并不是试图成为另一个笔记应用或向量数据库。它帮助智能代理决定应该记住什么、谁可以使用它、它是否仍然当前、以及当它错误时如何回滚。 Python包和现有的安装路径仍为`vault-for-llm`。 Vault 是为已经构建或使用智能代理的人员准备的。主要的接口仍然不应该是一个长CLI手册：请智能代理安装Vault，回答几个设置问题，然后阅读每日内存报告。 新来者？从视觉演示开始： [`docs/landing/index.html`](docs/landing/index.html). ## 30秒版本 智能代理内存存在是因为智能代理内存以实用方式失败： - 新会话表现得像它在第一天加入项目一样 - 错误修复仍然隐藏在聊天记录中 - 旧笔记优先于新决策 - 私人观察泄漏到共享项目内存中 - 团队无法分辨哪些内存被审查、信任或废弃 ```mermaid flowchart TB subgraph 智能代理["🤖 您的智能代理"] C[Codex] CL[Claude Code] H[Hermes] CO[Coze] N[n8n] end subgraph Vault["🔐 Vault — 受管内存层"] direction TB Pipeline["审查流程<br/>隐私 · 重复 · 质量 · 来源"] Report["每日报告<br/>自动提升低风险 · 审查高风险"] subgraph 内存层["内存层"] L0["L0 身份"] L1["L1 规则"] L2["L2 上下文"] L3["L3 知识"] end Ledger["任务账本<br/>实时工作台 · 交接"] Storage["SQLite / Markdown<br/>本地优先 · 零依赖"] end subgraph 集成["🔌 集成"] Obs[Obsidian 同步] Sup[Supabase] GW[网关 API] end 智能代理 -->|提出| Pipeline 智能代理 -->|搜索 / 有限读取| 内存层 智能代理 -->|更新状态| 账本 Pipeline --> Report Report --> 内存层 内存层 <--> 账本 内存层 --> Storage 集成 <-->|导入 / 导出 / 同步| Vault style 智能代理 fill:#e1f5fe,stroke:#0288d1 style Vault fill:#f3e5f5,stroke:#7b1fa2 style 集成 fill:#e8f5e9,stroke:#388e3c ``` ### 为什么是Vault？ | 没有Vault | 有Vault | |---------------|------------| | 每个智能代理单独记忆，重复相同的错误 | 一个共享的内存库 — 只需学习一次，在所有地方受益 | | 旧信息与新决策冲突；智能代理不知道该信任什么 | 时间边界 + 过期 — 总是呈现最新的真相 | | 敏感信息无处不在；没有审计跟踪 | 治理元数据 — 谁看到什么，跟踪每个更改，随时回滚 | | 内存只是一个聊天记录的堆积，很难找到信号 | 候选 → 审查 → 提升 — 只有有用的内容保留 | 核心工作流程是： ```text 提出 -> 审查 -> 提升 -> 搜索 -> 有限读取 -> 回滚 -> 审计 ``` 用白话来说： > Vault 不是帮助智能代理记住所有事情。它的目的是帮助团队管理智能代理记住什么、信任什么、分享什么、忘记什么和回滚什么。 ## 你是谁？从这里开始 👇 | 角色 | 你关心什么 | 入门指南 | |------|---------------------|----------------| | 🧑‍💻 智能代理开发者 | 如何将Vault集成到我的智能代理中？ | → [MCP集成指南](docs/mcp_memory_workflow.md) | | 🤖 强大的智能代理用户 | 如何阻止Claude/Codex忘记？ | → [5分钟快速入门](docs/quickstart.md) · 复制安装提示到你的智能代理 | | 👥 团队协作 | 多个智能代理如何共享内存而不混乱？ | → [三智能代理共享内存演示](docs/demo/three-agent-shared-memory-runbook.md) | | 📝 Obsidian用户 | 智能代理如何安全地使用我的笔记？ | → [Obsidian集成](#obsidian) | | 🏗️ 架构师 / 技术负责人 | 可靠吗？架构是什么？ | → [设计决策](docs/decision_records/) · [基准测试](docs/search_qa_benchmarking.md) | ## 对于智能代理构建者：让你的智能代理安装它 将此内容复制到可以运行本地命令的智能代理中： ```text 为该项目安装智能代理内存。使用vault-for-llm[mcp]==0.7.30。 使用智能代理辅助的受管自动内存模式。 不要一开始就显示高级CLI标志。只需向我提出四个问题： 1. Vault应该使用哪种语言：繁体中文、简体中文还是英语？ 2. 这应该是一个独立的Vault还是多个智能代理的共享Vault？ 3. Vault是否应该连接到Obsidian、Supabase、两者还是两者都不？ 4. 每日内存报告应在什么时候运行？ 设置完成后，运行一次健康检查，并告诉我： - Vault位于哪里 - 我如何阅读每日内存报告 - 本地GUI或下一个操作在哪里 每日规则： 安全、低风险、来源可靠的内存可以自动保留； 不确定、敏感、冲突或战略性内存应进入每日报告供我审查。 ``` 智能代理通常会运行： ```bash python3 -m venv .venv source .venv/bin/activate pip install "vault-for-llm[mcp]==0.7.30" vault quickstart ``` 您也可以从Vault本身打印安装提示： ```bash vault guide --intent install ``` `vault quickstart`是一个小的首次运行向导。它只会询问语言、独立/共享内存、Obsidian/Supabase连接和每日报告时间。参见 [docs/quickstart.md](docs/quickstart.md) 了解5分钟的演练和FAQ。高级集成标志保留在 `vault setup-agent` 下。 智能代理辅助的快速入门默认使用`governed-auto`。在内部，这仍然是消费者设置路径，但这并不意味着Vault是一个零学习消费者应用程序。低风险、来源可靠的候选项通过隐私、重复、元数据和质量门控可能会进入活动Vault。策略、私人、敏感、冲突或低信任内存将保留在每日报告中供人类审查。没有任何内容被自动硬删除。 ## 每日使用 预期的人类界面很小： 1. 智能代理在工作时提出可重复使用的经验教训。 2. Vault检查隐私、重复、质量和来源证据。 3. 安全的低风险内存可以进入Vault。 4. 不确定的决策在每日报告中总结。 5. 用户批准、拒绝、推迟或保留冲突双方。 报告应该回答： - 今日Vault记住了什么？ - 哪些内存决策需要我的关注？ - 是否有过时、敏感、冲突或质量低下的内存需要审查？ 这就是产品形态：随着时间的推移，自动化程度越来越高，但仍然受到管辖。 ## Vault 不是什么 Vault 不是 Obsidian 的替代品。 Obsidian 非常适合人类阅读笔记。Vault 帮助智能代理安全地使用这些笔记，具有来源范围和审查边界。 Vault 不仅仅是 RAG。 RAG 通常专注于检索上下文。Vault 关注内存生命周期：谁编写了它，是否经过审查，哪些智能代理可以读取它，何时停止当前状态，以及如何回滚。 Vault 不是一个原始聊天记录的垃圾场。 它是候选优先的。智能代理可以建议内存，但长期内存应该保持来源支持、可审查和清洁。 Vault 不是一个无需设置的应用程序商店产品，适用于不使用智能代理的人。 第一个公开受众是智能代理辅助构建者：使用Codex、Claude Code、Hermes、OpenClaw、n8n、Coze或类似系统的人员，他们想要一个受管的内存层，而无需研究每个内部命令。 ## 杀手级演示：共享受管内存 运行本地演示： ```bash vault demo agent-governance --json ``` 它模拟了Codex、Claude Code和Hermes共享一个受管的Vault： 1. 一个智能代理提出一个来自错误修复的经验教训 2. 内存在被审查之前保持为候选状态 3. 审查者用来源证据提升它 4. 另一个智能代理通过搜索和有限读取找到它 5. 当内存过时时，可以将其废弃或回滚 生成的演示包还包括三个后续指南： `consumer-mode-demo.md`、`automation-mode-demo.md` 和 `multi-host-sync-demo.md`. 从这里开始： - [智能代理需要内存治理，而不仅仅是RAG](docs/articles/agents-need-memory-governance-not-just-rag.md) - [三智能代理共享内存运行手册](docs/demo/three-agent-shared-memory-runbook.md) - [演示包](docs/demo/agent-governance-demo-pack.md) - [策略文档](docs/strategy/) ## 3分钟演示（即将推出） > 🎬 *即将推出3分钟的演练GIF动画。* > > 在此期间，这里是它将显示的内容： > > 1. **安装** — `pip install vault-for-llm[mcp]` 和 `vault quickstart` > 2. **配置** — 回答4个简单问题（语言、Vault类型、集成、报告时间） > 3. **提出** — 智能代理使用 `vault_memory_propose` 建议内存 > 4. **审查** — 每日报告为人类批准提供候选项 > 5. **提升和搜索** — 批准的内存出现在 `vault_search` 中，具有有限读取权限 > > 更喜欢文本演练？ → [5分钟快速入门](docs/quickstart.md) ## 一键安装 ### macOS / Linux ```bash curl -sSL https://raw.githubusercontent.com/zycaskevin/Vault-Agent-Memory/main/scripts/install.sh | bash ``` ### Windows (PowerShell) ```powershell irm https://raw.githubusercontent.com/zycaskevin/Vault-Agent-Memory/main/scripts/install.ps1 | iex ``` 安装程序完成后，运行 `vault quickstart` 以完成设置。 这些原始的GitHub URL来自 `main` 并安装了此README使用的固定发布版本。如果您更喜欢发布标签文档，请使用包含这些安装脚本的下一个发布版本。 来源： [`scripts/install.sh`](scripts/install.sh) · [`scripts/install.ps1`](scripts/install.ps1) ## 开发者快速入门 ```bash pip install "vault-for-llm[mcp]==0.7.30" vault init ~/Vaults/demo vault add "第一个经验教训" \ --content "错误是由缺少的缓存键引起的。修复是添加提供者元数据。" \ --project-dir ~/Vaults/demo vault compile --project-dir ~/Vaults/demo --no-embed vault search "缓存键" --project-dir ~/Vaults/demo vault --project-dir ~/Vaults/demo map build vault --project-dir ~/Vaults/demo map read 1 --lines 1-20 vault --project-dir ~/Vaults/demo gui ``` `vault add` 通过 `--content` 或 `--file` 获取内容。对于有限的源读取，请使用 `vault map read <knowledge_id> --lines START-END`。 对于支持MCP的运行时： ```bash vault-mcp --project-dir ~/Vaults/demo --tool-profile core ``` 大多数智能代理都以 `core` 启动： - `vault_search` - `vault_read_range` - `vault_memory_propose` - `vault_stats` - `vault_update_status` - `vault_automation_handoff` 仅在需要时使用更大的MCP配置文件： | 配置文件 | 使用场景 | |---|---| | `core` | 每日搜索、有限读取、候选内存、状态、交接 | | `review` | 候选审查、捕获、提升、梦境审查 | | `remote` | 读取同步的远程内存视图 | | `maintenance` | 导入、更新、收敛、计划的策划 | | `full` | 受信任的本地强用户兼容性 | 详细MCP文档： - [MCP工具参考](docs/mcp_tool_reference.md) - [MCP内存工作流程](docs/mcp_memory_workflow.md) ## 内存模型 Vault使用L0-L3表示内存深度： | 层 | 目的 | |---|---| | `L0` | 身份和项目框架 | | `L1` | 稳定的事实、规则、偏好 | | `L2` | 审查的近期上下文和摘要 | | `L3` | 详细的知识、SOP、错误、决策、源笔记 | 任务账本不是L2。它是用于阻塞、下一个操作、证据链接、截止日期和交接笔记的实时工作台。只有在审查后，耐用的经验教训、决策和摘要才应该提升到L2/L3。 访问不单独由层控制。使用治理元数据： - `scope`: 私有、项目、共享、公共 - `sensitivity`: 低、中、高、受限 - `owner_agent` - `allowed_agents` - `memory_type` - `expires_at` - `valid_from` / `valid_until` - `supersedes_id` 时间事实窗口与过期分开。`expires_at` 表示“稍后将此移出正常召回”。`valid_until` 表示“此事实已停止为真，但保留用于历史和审计”。 ```bash vault memory temporal status vault memory temporal list --state past vault search "office location" --exclude-expired ``` 更多详情： [docs/memory_governance.md](docs/memory_governance.md). ## 自动化和每日报告 自动化默认优先报告。它可以对候选项进行排名，总结过时的内存，建议合并，并准备一个短的审查队列，而不会在不经审查的情况下重写长期内存。 ```bash vault daily-report --language en vault automation brief --pretty vault automation review-summary --write-summary vault automation handoff ``` 有意启用更强大的自动化： ```bash vault setup-agent \ --automation-schedule cron \ --automation-apply \ --automation-auto-promote-low-risk ``` 该路径只能提升低风险、来源可靠的候选项，这些候选项通过正常的门控，并且具有每运行一次的上限。私有、高敏感性、重复、弱或无来源的候选项仍在审查中。 自动化文档： - [自动化](docs/automation.md) - [自动化策略](docs/automation_strategy.md) ## 集成 | 系统 | 路径 | |---|---| | Codex / Claude Code / OpenCode | CLI 或本地stdio MCP | | Hermes Agent / OpenClaw | CLI、MCP、生成的智能代理安装文件 | | n8n | 生成的工作流模板和网关/Supabase适配器 | | Coze 或托管智能代理 | OpenAPI模板、网关或Supabase读取RPC | | Obsidian | 导入笔记、导出审查内存、冲突收件箱 | | 其他内存工具/聊天导出 | 候选优先迁移 | | Headroom | Vault缩小上下文后可选压缩 | 从这里开始： - [智能代理集成](docs/agent_integrations.md) - [智能代理优先使用](docs/agent_first_usage.md) - [网关/远程合约](docs/decision_records/2026-07-02-vault-remote-gateway-contract.md) ## Obsidian 导入现有的Obsidian Vault： ```bash vault import obsidian --vault ~/Documents/ObsidianVault --project-dir ~/Vaults/my-project --dry-run vault import obsidian --vault ~/Documents/ObsidianVault --project-dir ~/Vaults/my-project --compile ``` 将审查的Vault知识导出回Obsidian可读的笔记： ```bash vault export obsidian --project-dir ~/Vaults/my-project --vault ~/Documents/ObsidianVault --dry-run --json vault export obsidian --project-dir ~/Vaults/my-project --vault ~/Documents/ObsidianVault ``` 冲突收件箱使用明确的解析器选择：接受Obsidian，接受Vault，或保留两者。 ## 远程共享 本地SQLite仍然是真相的简单来源。对于远程共享，请选择适合您部署的适配器。 Supabase在托管智能代理或其他机器需要过滤读取副本时很有用： ```bash pip install "vault-for-llm[supabase]==0.7.30" vault remote status --project-dir ~/Vaults/my-project python -m scripts.sync_to_supabase --db ~/Vaults/my-project/vault.db --document-map --health ``` 网关/远程服务器在许多智能代理可以访问一个受信任的自托管端点时很有用： ```bash export VAULT_GATEWAY_TOKEN="choose-a-stable-secret" vault remote-server health --project-dir ~/Vaults/my-project --json vault remote-server openapi --project-dir ~/Vaults/my-project --json vault remote-server serve --project-dir ~/Vaults/my-project --host 0.0.0.0 ``` 远程贡献应作为审查候选项进入。这是集中式共享，而不是离线多主同步。 文档： - [Supabase设置](docs/supabase_setup.md) - [Supabase读取策略](docs/supabase_read_policy.sql) - [网关安全基础](docs/decision_records/2026-07-02-gateway-security-foundation.md) ## 内存迁移 将其他工具的内存作为候选项导入，而不是作为受信任的活动内存： ```bash vault import memory --source ~/Downloads/chatbox-export.json --format auto --dry-run vault import memory --source ~/Downloads/chatbox-export.json --write-candidates --only summaries,decisions,preferences ``` 导入的项目将经过相同的隐私、重复、元数据和质量检查。 ## 检索质量 Vault包含搜索QA，因此检索可以通过测量而不是凭直觉来评估。 ```bash vault search-qa run \ --qa-file benchmarks/search_qa/basic.en.json \ --mode keyword \ --output /tmp/vault-searchqa.json ``` 当前的公共声明应作为检索证据读取，而不是最终答案质量： - 项目启动证明运行发现28/28个任务的源支持内存 - LoCoMo检索探针显示高证据召回率，具有分层检索 - 官方回答者/裁判分数是单独的，需要模型提供者运行 更多详情： - [智能代理入职基准测试](docs/agent_onboarding_benchmark.md) - [搜索QA基准测试](docs/search_qa_benchmarking.md) ## 成熟度 | 领域 | 状态 | |---|---| | 本地SQLite，Markdown编译，关键词搜索 | 稳定 | | CLI设置，候选内存，有限读取 | 可用 | | MCP工具 | 可用，建议选择配置文件 | | 智能代理辅助设置和受管自动每日循环 | 可用，正在改进 | | Obsidian导入/导出/冲突收件箱 | 可用，同步UX仍在改进中 | | Supabase同步和网关/远程服务器 | 高级可选 | | 语义搜索，提供商，重新排序，基准测试适配器 | 正在演进 | | 配置文件/梦境/遗忘智能代理 | 指导优先，非自主删除 | Vault Agent Memory 是预1.0版本。核心本地路径有意保守。高级远程和自动化路径功能强大，但应有意启用。 ## 文档地图 - [用白话解释核心概念](docs/core-concepts.md) - [智能代理安装运行手册](docs/agent_install.md) - [CLI参考](docs/cli_reference.md) - [智能代理集成](docs/agent_integrations.md) - [本地GUI控制台](docs/gui_console.md) - [内存治理](docs/memory_governance.md) - [自动化](docs/automation.md) - [MCP工具参考](docs/mcp_tool_reference.md) - [MCP工作流程](docs/mcp_memory_workflow.md) - [LLM集成](docs/llm_integration.md) - [OKF集成](docs/okf_integration.md) - [愿景笔记](docs/vision.md) ## 开发 常见的Python路径： ```bash git clone https://github.com/zycaskevin/Vault-Agent-Memory.git cd Vault-Agent-Memory python3 -m venv .venv source .venv/bin/activate pip install -e ".[dev,mcp]" pytest -q ``` 可复制的智能代理/开发者环境： ```bash git clone https://github.com/zycaskevin/Vault-Agent-Memory.git cd Vault-Agent-Memory uv sync --extra dev --extra mcp uv run pytest -q ``` `pip install vault-for-llm` 仍然是公共用户的安装路径。uv工作流适用于源代码开发、CI健康检查和需要可靠地重建相同本地环境的智能代理。 ## 贡献 Vault 准备好接受来自智能代理构建者的小型、有界限的贡献。从 [CONTRIBUTING.md](CONTRIBUTING.md)、[好点子](docs/contributing_good_first_issues.md) 和 [行为准则](CODE_OF_CONDUCT.md) 开始。请勿在公共问题或拉取请求中包含真正的秘密、私人聊天、客户记录、医疗数据或生产Vault导出。 ## 许可证 Apache-2.0。参见 [LICENSE](LICENSE)。