llm-vault

# llm-vault > 一个基于源代码的MCP内存运行时和兼容Obsidian的保险库模板，适用于LLM代理。 > > `llm-vault`帮助代理在不无声覆盖不确定性的情况下保存长期运行的项目内存：不可变的原始源、源摘要、决策记录、矛盾跟踪、置信度感知的检索和人工审查队列是系统的首要部分。 [](LICENSE) [](https://www.python.org/) 请先阅读：[中文](#什么是本项目) · [韩语](#韩语概述) ## 什么是本项目？ `llm-vault`结合了兼容Obsidian的Markdown保险库、基于源代码的存档规则、决策记录、矛盾保留和基于DuckDB、BM25、可选Ollama嵌入和图扩展的MCP内存运行时。 核心假设很简单：**LLM输出默认可能错误**。因此，原始证据、引用、不确定性标签、保留的矛盾和人工审查队列不是可选的额外功能。它们是操作系统。 诸如Claude、Cursor、Antigravity和Codex等代理应在使用保险库前阅读[AGENTS.md](AGENTS.md)。完整的思维模型位于[00_System/Second Brain Operating Model.md](00_System/Second%20Brain%20Operating%20Model.md)。 ## 从干净的私有保险库开始 该存储库是一个框架骨架加上种子/示例知识。如果您将其转换为自己的私有第二大脑，请保留框架文件并删除现有的种子文档，然后再添加个人记忆。 保留以下内容： - `00_System/`、`90_Engine/`、`docs/`、`scripts/` - 根目录文档，例如`README.md`、`SETUP.md`、`AGENTS.md`、`LICENSE` - `.mcp.json.example`、`requirements.txt`、`gitignore` - 层`README.md`文件和`.gitkeep`占位符（如果存在） 删除知识层中的种子/用户特定内容： ```bash find 10_MOC 20_Concepts 30_Projects 40_Decisions \ 50_Source_Summaries 60_Open_Questions 70_Contradictions 80_Reviews \ -type f -name '*.md' ! -name 'README.md' -delete find 05_Inbox 06_Raw \ -type f ! -name 'README.md' ! -name '.gitkeep' -delete ``` 然后重建本地缓存： ```bash python3 90_Engine/indexer.py --force --embed --report ``` 如果Ollama尚未运行，请省略`--embed`以进行仅限BM25的首次传递。 有关MCP客户端设置和私有/公共分割，请参见[SETUP.md](SETUP.md)。有关从源到决策的微型演示，请参见[examples/mini-vault](examples/mini-vault)。 > **此存储库是一个框架模板。** 引擎 (`90_Engine/`) + 策略 (`00_System/`) + 文档/脚本 + 空保险库骨架 + 演示 [`examples/mini-vault/`](examples/mini-vault/)。它不包含实际的个人知识。要将其用作您的第二大脑，请复制此模板，创建您自己的**私有实例**，并仅在那里积累实际知识。请参阅 [SETUP.md](SETUP.md) §8 获取边界和操作指南。 ## 韩语概述 `llm-vault`是一个结合了Obsidian兼容的Markdown保险库、源代码基础存档规则、决策记录、矛盾跟踪和基于MCP的内存运行时的**LLM原生第二大脑**。 核心前提是 **“LLM可能默认错误”**。因此，在此系统中，原始源、引用、不确定性标签、矛盾保留和人工审查队列不是可选的，而是必不可少的。涵盖AI研究笔记、调试日志、长期项目决策、理论演变、行政记录、截图、聊天日志和个人工作流记录。 代理（Claude、Cursor、Antigravity等）在工作前请先阅读[AGENTS.md](AGENTS.md)，并遵循整个思维模型[00_System/Second Brain Operating Model.md](00_System/Second%20Brain%20Operating%20Model.md)。 ## 层 | 层 | 路径 | 角色 | |------|------|------| | **存档** | `05_Inbox/`、`06_Raw/` | 未处理的输入（05_Inbox，不索引）→ 不变的原始数据（06_Raw，仅限全文搜索·图谱除外） | | **维基/知识** | `20_Concepts/`、`50_Source_Summaries/`、`10_MOC/` | 原始数据摘要和持久性概念知识、导航地图 | | **项目** | `30_Projects/` | 活跃的工作台 | | **决策** | `40_Decisions/` | 重要选择和理由。现有决策不可更改（采用替换方式） | | **审查** | `60_Open_Questions/`、`70_Contradictions/`、`80_Reviews/` | 开放性问题、矛盾保留、人工验证队列 | | **运行时** | `90_Engine/` | DuckDB索引、混合搜索、MCP服务器 | 数据流：`05_Inbox/` → `06_Raw/`（不变）→ `50_Source_Summaries/` → 解释层更新 → 审查/矛盾/问题路由 → `90_Engine/`重新索引。详细图表请参见[Second Brain Operating Model](00_System/Second%20Brain%20Operating%20Model.md)。 ## 架构 **Markdown是真实来源；DuckDB是派生、可再生缓存。** 客户端通过MCP工具写入Markdown，索引器将其编译为DuckDB图缓存，检索器为客户端提供基于层/置信度的混合搜索。缓存（`ltm_cache.db`）被gitignore并在每台机器上重新生成 - 只有Markdown跨设备同步。 **Markdown是真实来源，DuckDB是派生和可重建的缓存。** 客户端使用MCP工具编写Markdown，索引器将其编译成DuckDB图缓存，检索器使用层/置信度感知的混合搜索返回给客户端。缓存（`ltm_cache.db`）被gitignore，因此每个机器都会重新生成，只有Markdown在设备之间同步。 ```mermaid flowchart LR CLI["LLM客户端<br/>Claude · Codex · Antigravity"] MD["Markdown保险库<br/>真实来源 · 9谓词链接"] IDX["indexer.py<br/>增量编译 · MD5 · 孤儿修剪"] DB[("DuckDB缓存 · ltm_cache.db<br/>节点 · 边 · 嵌入")] RET["retriever.py<br/>BM25 + 密集 + 图扩展"] MCP["mcp_server.py<br/>MCP工具"] OLL["Ollama · bge-m3"] GIT["git远程<br/>跨机器同步"] CLI -->|"创建/更新/删除"| MD MD <-->|"拉取/推送"| GIT MD --> IDX OLL -.->|"嵌入"| IDX IDX --> DB DB --> RET OLL -.->|"查询嵌入"| RET RET --> MCP MCP --> CLI ``` > 并发性和进程拓扑（处理多个MCP客户端的并发访问）正在演变为单个所有者守护进程 - 设计参见[docs/DAEMON_DESIGN.md](docs/DAEMON_DESIGN.md)。 ## 入门指南 - 安装、初始索引、MCP客户端连接：[SETUP.md](SETUP.md) - MCP工具规范和AI内存写入流程：[docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) - Antigravity专用连接指南：[docs/ANTIGRAVITY.md](docs/ANTIGRAVITY.md) - 为什么需要此结构：[docs/WHY_LLM_VAULT.md](docs/WHY_LLM_VAULT.md) - 小型演示保险库：[examples/mini-vault](examples/mini-vault) - 设备间git同步和可选自动同步：[SETUP.md](SETUP.md#自动同步-选择) 最小流程如下： 1. 安装Python依赖项 2. 准备Ollama和`bge-m3`模型 3. 使用`90_Engine/indexer.py`将Markdown编译为DuckDB缓存 4. 在MCP客户端设置中注册`90_Engine/mcp_server.py` 有关详细命令和OS特定设置的示例，请参阅[SETUP.md](SETUP.md)。 ## 文件结构 ```text llm-vault/ ├── README.md ├── AGENTS.md # LLM代理操作指南 ├── SETUP.md ├── docs/ │ ├── ANTIGRAVITY.md │ ├── MCP_TOOLS.md │ └── WHY_LLM_VAULT.md ├── examples/ │ └── mini-vault/ # 小型可运行的源→摘要→决策示例 ├── 00_System/ # 本体 + 第二大脑策略 │ ├── Ontology Specification.md │ ├── Second Brain Operating Model.md │ ├── Source Policy.md │ ├── Ingest Policy.md │ ├── Review Policy.md │ └── Naming Convention.md ├── 05_Inbox/ # 未处理的输入（不索引） ├── 06_Raw/ # 不变的原始数据 = 真实来源（全文搜索专用，图谱除外） ├── 10_MOC/ # 导航地图（Map of Content） ├── 20_Concepts/ # 持久性概念知识 ├── 30_Projects/ # 活跃的工作台 ├── 40_Decisions/ # 决策记录 ├── 50_Source_Summaries/ # 原始数据压缩理解 ├── 60_Open_Questions/ # 未解决的问题 ├── 70_Contradictions/ # 矛盾和过时假设的保留 ├── 80_Reviews/ # 人工验证队列 └── 90_Engine/ # 运行时/索引/MCP ├── indexer.py ├── retriever.py ├── mcp_server.py └── ltm_cache.db # 本地生成的缓存，被git忽略 ``` 数字前缀用于Obsidian的自然排序和阅读顺序。核心规则是`00_System/Ontology Specification.md`中的9个谓词宪法和`00_System/`中的第二大脑策略文档。 ## 每日工作流程 节点可以由人直接用Markdown编写，也可以使用MCP写入工具创建。输入的标准程序遵循[Ingest Policy](00_System/Ingest%20Policy.md)。 - 人编辑后，通过`sync_vault()`或运行索引器更新缓存。 - 代理保存内存时，使用`list_notes()`确认现有标题，然后使用`create_note()`、`update_note()`、`upsert_edge()`。 - 如果出现悬空边，自动修复或立即使用`reconcile_graph()`清理。 - **并非所有源都转换为概念节点。** 默认目标是`50_Source_Summaries/`，只有持久性知识才会升级到`20_Concepts/`。 - 搜索是**分层和置信度感知的**。`06_Raw/`仅用于全文搜索，优先级较低，低置信度或过时项目也会降低优先级和标记，审查层（`60/70/80`）默认不包含在搜索中（使用`retrieve_knowledge(..., include_reviews=true)`包含）。审查队列检查使用`review_queue()`。理由：[[2026-06-18-layer-and-confidence-aware-retrieval]]。 节点编写时，边谓词仅限以下9种： `requires` · `utilizes` · `implemented_by` · `extends` · `abstracts` · `causes` · `contradicts` · `replaces` · `defines` ## 了解更多 - 代理指南：[AGENTS.md](AGENTS.md) - 设计原因：[docs/WHY_LLM_VAULT.md](docs/WHY_LLM_VAULT.md) - 操作模型：[00_System/Second Brain Operating Model.md](00_System/Second%20Brain%20Operating%20Model.md) - 策略：[Source Policy](00_System/Source%20Policy.md) · [Ingest Policy](00_System/Ingest%20Policy.md) · [Review Policy](00_System/Review%20Policy.md) · [Naming Convention](00_System/Naming%20Convention.md) - 本体宪法：[00_System/Ontology Specification.md](00_System/Ontology%20Specification.md) - 初始语料库（LLM思维模型）：[10_MOC/Karpathy LLM Framework MOC.md](10_MOC/Karpathy%20LLM%20Framework%20MOC.md) - 安装和操作：[SETUP.md](SETUP.md) · MCP工具：[docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) ## 许可证 MIT许可证。详情请参阅[LICENSE](LICENSE)。 ## 来源 - [Andrej Karpathy](https://karpathy.ai) - [Intro to Large Language Models](https://www.youtube.com/watch?v=zjkBMFhNj_g) - [Let's build the GPT Tokenizer](https://www.youtube.com/watch?v=zduSFxRajkE) - [Software 2.0 Essay](https://karpathy.medium.com/software-2-0-a64152b37c35) - [llm.c GitHub](https://github.com/karpathy/llm.c) - [nanoGPT GitHub](https://github.com/karpathy/nanoGPT)