内容
# 记忆库
[English](README.md) | [繁體中文](README.zh-Hant.md) | [简体中文](README.zh-CN.md)
面向 AI 代理的本地优先内存治理。
记忆库为 Codex、Claude Code、Hermes、OpenClaw、n8n、Coze 等代理提供一个受控的共享内存库。它不旨在成为另一款笔记应用或向量数据库。它帮助代理决定应该记住什么、谁可以使用它、它是否仍然当前、以及当它错误时如何回滚。
记忆库适用于已经构建或使用代理的人员。主要界面不应是 lengthy CLI 手册：请代理安装记忆库，回答几个设置问题，然后阅读每日内存报告。
新来者？从视觉演示开始：
[`docs/landing/index.html`](docs/landing/index.html)。
## 30 秒版本
记忆库存在是因为代理内存存在实际问题：
- 新会话表现得像它加入项目那天一样
- 错误修复仍然隐藏在聊天历史中
- 旧笔记优先于新决策
- 私人观察泄漏到共享项目内存中
- 团队无法确定哪些内存被审查、信任或弃用
核心工作流程是：
```text
提出 -> 审查 -> 提升 -> 搜索 -> 有限读取 -> 回滚 -> 审计
```
用白话来说：
> 记忆库不是帮助代理记住一切。它是帮助团队管理代理记住什么、信任什么、分享什么、忘记什么以及回滚什么。
## 代理构建者：请您的代理安装它
将此提示复制到可以运行本地命令的代理中：
```text
为该项目安装记忆库。使用 vault-for-llm[mcp]==0.7.29。
使用代理辅助的受控自动内存模式。
不要一开始显示高级 CLI 标志。只需向我提出四个问题：
1. 记忆库应该使用哪种语言：繁体中文、简体中文还是英文？
2. 这应该是一个独立的记忆库还是一个多个代理共享的记忆库？
3. 记忆库是否应该连接到 Obsidian、Supabase、两者还是两者都不？
4. 每日内存报告应该在什么时候运行？
设置完成后，运行一次烟雾测试，并告诉我：
- 记忆库位于哪里
- 我如何阅读每日内存报告
- 本地 GUI 或下一个操作在哪里
每日规则：
安全、低风险、来源可靠的记忆可以自动保留；
不确定、敏感、冲突或战略性记忆应进入每日报告供我审查。
```
代理通常会运行：
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install "vault-for-llm[mcp]==0.7.29"
vault quickstart
```
您也可以从记忆库本身打印安装提示：
```bash
vault guide --intent install
```
`vault quickstart` 是一个小型的一次性向导。它只询问语言、独立/共享内存、可选的 Obsidian/Supabase 连接和每日报告时间。参见 [docs/quickstart.md](docs/quickstart.md) 了解 5 分钟的演练和常见问题。高级集成标志保留在 `vault setup-agent` 下。
代理辅助的快速入门默认使用 `governed-auto`。在内部，这仍然是消费者设置路径，但这并不意味着记忆库是一个零学习消费者应用程序。低风险、来源可靠的候选者通过隐私、重复、元数据和质量门控后可以进入活动记忆库。策略、私人、敏感、冲突或低信任记忆应留在每日报告中供人工审查。没有任何内容被自动硬删除。
## 每日使用
预期的人类界面很小：
1. 代理在工作过程中提出可重复使用的经验教训。
2. 记忆库检查隐私、重复、质量和来源证据。
3. 安全的低风险记忆可以进入记忆库。
4. 不确定的决策会汇总在每日报告中。
5. 用户批准、拒绝、推迟或保留冲突双方。
报告应该回答：
- 今日记忆库记住了什么？
- 哪些记忆决策需要我的关注？
- 是否有需要审查的过期、敏感、冲突或低质量记忆？
这就是产品形态：随着时间的推移，自动化程度越来越高，但仍然受到控制。
## 记忆库不是什么
记忆库不是 Obsidian 的替代品。
Obsidian 适用于人类阅读笔记。记忆库帮助代理安全地使用这些笔记，具有来源范围和审查边界。
记忆库不仅仅是 RAG。
RAG 通常专注于检索上下文。记忆库专注于内存生命周期：谁编写了它、是否经过审查、哪些代理可以读取它、什么时候停止当前、以及如何回滚。
记忆库不是原始聊天历史的垃圾填埋场。
它是候选人优先的。代理可以建议记忆，但长期记忆应该有来源支持、可审查和清洁。
记忆库不是面向不使用代理的人员的零设置应用商店产品。
第一个公共受众是代理辅助构建者：使用 Codex、Claude Code、Hermes、OpenClaw、n8n、Coze 或类似系统的人员，他们想要一个受控的内存层，而无需学习每个内部命令。
## 杀手级演示：共享受控内存
运行本地演示：
```bash
vault demo agent-governance --json
```
它模拟了 Codex、Claude Code 和 Hermes 共享一个受控的记忆库：
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/)
## 开发者快速入门
```bash
pip install "vault-for-llm[mcp]==0.7.29"
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` | 导入、 freshness、 convergence、 scheduled curation |
| `full` | 受信任的本地强用户兼容性 |
详细MCP文档：
- [MCP 工具参考](docs/mcp_tool_reference.md)
- [MCP 内存工作流程](docs/mcp_memory_workflow.md)
## 内存模型
记忆库使用 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 zh-CN
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 | 生成的工作流模板和 Gateway/Supabase 适配器 |
| Coze 或托管代理 | OpenAPI 模板、Gateway 或 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 保险库：
```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
```
将审查过的知识导出回 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.29"
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
```
导入的项目通过相同的隐私、重复、元数据和质量门控。
## 检索质量
记忆库包含搜索 QA，因此检索可以通过测量而不是仅凭直觉来评估。
```bash
vault search-qa run \
--qa-file benchmarks/search_qa/basic.zh-CN.json \
--mode keyword \
--output /tmp/vault-searchqa.json
```
当前公共声明应作为检索证据读取，而不是最终答案质量：
- 项目启动证明运行发现 28/28 个任务中有源支持的内存，涵盖 28 个任务
- LoCoMo 检索探针显示高证据召回率，具有分层检索
- 官方回答者/裁判分数是单独的，需要模型提供商运行
更多详情：
- [代理入职基准](docs/agent_onboarding_benchmark.md)
- [搜索 QA 基准](docs/search_qa_benchmarking.md)
## 成熟度
| 领域 | 状态 |
|---|---|
| 本地 SQLite、Markdown 编译、关键词搜索 | 稳定 |
| CLI 设置、候选内存、有限读取 | 可用 |
| MCP 工具 | 可用，建议选择配置文件 |
| 代理辅助设置和受控自动每日循环 | 可用，正在改进 |
| Obsidian 导入/导出/冲突收件箱 | 可用，同步 UX 仍在改进 |
| Supabase 同步和网关/远程服务器 | 高级可选 |
| 语义搜索、嵌入提供者、重新排序、基准适配器 | 演进中 |
| 配置文件/梦境/遗忘代理 | 指导优先，非自主删除 |
Vault-for-LLM 处于 1.0 之前。核心本地路径故意保守。高级远程和自动化路径功能强大，但应有意启用。
## 文档地图
- [代理安装手册](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-for-LLM.git
cd Vault-for-LLM
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,mcp]"
pytest -q
```
可复制的代理/开发者环境：
```bash
git clone https://github.com/zycaskevin/Vault-for-LLM.git
cd Vault-for-LLM
uv sync --extra dev --extra mcp
uv run pytest -q
```
`pip install vault-for-llm` 仍然是公共用户安装路径。uv 工作流适用于源代码开发、CI 烟雾检查和需要可靠地重建相同本地环境的代理。
## 贡献
Vault 准备好小规模、有界的贡献，面向代理辅助构建者。从 [CONTRIBUTING.md](CONTRIBUTING.md)、[good first issue ideas](docs/contributing_good_first_issues.md) 和 [Code of Conduct](CODE_OF_CONDUCT.md) 开始。请不要在公共问题或拉取请求中包含真正的秘密、私人聊天、客户记录、医疗数据或生产环境下的保险库导出。
## 许可证
Apache-2.0。参见 [LICENSE](LICENSE)。
