# https://github.com/fellanH/context-vault 项目说明书

生成时间：2026-07-09 07:41:01 UTC

## 目录

- [项目概览与 Rust 工作区架构](#page-1)
- [MCP 工具、搜索引擎与 CLI 协议](#page-2)
- [Vault 文件存储、摄入管线与生命周期管理](#page-3)
- [部署、运维与社区反馈路线图](#page-4)

<a id='page-1'></a>

## 项目概览与 Rust 工作区架构

### 相关页面

相关主题：[MCP 工具、搜索引擎与 CLI 协议](#page-2), [Vault 文件存储、摄入管线与生命周期管理](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [Cargo.toml](https://github.com/fellanH/context-vault/blob/main/Cargo.toml)
- [README.md](https://github.com/fellanH/context-vault/blob/main/README.md)
- [crates/context-vault-core/src/lib.rs](https://github.com/fellanH/context-vault/blob/main/crates/context-vault-core/src/lib.rs)
- [crates/context-vault-cli/src/main.rs](https://github.com/fellanH/context-vault/blob/main/crates/context-vault-cli/src/main.rs)
- [crates/context-vault/src/lib.rs](https://github.com/fellanH/context-vault/blob/main/crates/context-vault/src/lib.rs)
- [docs/rust-distribution.md](https://github.com/fellanH/context-vault/blob/main/docs/rust-distribution.md)
</details>

# 项目概览与 Rust 工作区架构

## 1. 项目定位与目标

context-vault 是一个面向 AI 代理与开发者工作流的本地优先（local-first）上下文持久化引擎，目标是解决多会话、多代理场景下的「冷启动、再做一遍决策、上下文丢失」问题。系统在 v3 阶段完成了「核心/托管」关注点分离的纯引擎化重构（`packages/core` 零托管逻辑），并最终在 v4.0.0（2026-07-08）将整个引擎从 TypeScript 移植到 Rust，TypeScript 引擎与 Node CLI 已被 **删除**，Rust 二进制成为唯一交付物。

资料来源：[README.md:1-40](), [docs/rust-distribution.md:1-30]()

核心价值主张包括：

- **本地优先**：所有数据默认落盘为 Markdown 文件，搜索引擎对目录树进行重建索引（reindex）。
- **零托管依赖**：核心引擎不依赖任何远程服务或托管后端。
- **可嵌入性**：单一 Rust 二进制即可承担 CLI、子进程服务（`serve`）与库调用三种角色。

## 2. v4.0.0 架构重写：Rust 工作区

v4.0.0 是首个破坏性变更版本，整个工作区从 JavaScript/TypeScript 包结构迁移到 Cargo 多 crate 工作区。`Cargo.toml` 顶层声明多个成员 crate，源码统一位于 `crates/` 目录下；原 `packages/` 目录及 `tsconfig`、`package.json` 等 Node 工件不再存在。

资料来源：[Cargo.toml:1-25](), [crates/context-vault/src/lib.rs:1-20]()

主要 crate 职责如下：

| Crate | 角色 | 主要职责 |
|---|---|---|
| `context-vault` | 门面库 | 聚合子 crate，对外暴露统一的 `save`、`get`、`search`、`reindex` 等 API |
| `context-vault-core` | 本地持久化核心 | Markdown 写入、FTS 索引、向量索引（lazy embedding）、目录树重建 |
| `context-vault-cli` | 可执行入口 | 解析命令行参数，调用 core crate 的能力并提供 `serve`、`save`、`reindex` 等动词 |

CLI 入口位于 `crates/context-vault-cli/src/main.rs`，将每个子命令委托给 core 层的对应函数，避免在 CLI 中堆叠业务逻辑。

资料来源：[crates/context-vault-cli/src/main.rs:1-60](), [crates/context-vault-core/src/lib.rs:1-80]()

## 3. 核心模块：context-vault-core

`context-vault-core` 是整个引擎的中枢，承担以下职责：

- **Markdown 持久化**：`save` 命令将条目以 `.md` 文件形式写入本地目录，并同时更新索引数据库。
- **重建索引**：`reindex` 命令遍历整棵目录树，从已有 Markdown 文件重建 FTS 与向量索引，避免索引漂移。
- **双轨检索**：查询时同时走 FTS lane（FTS5）与 semantic lane（嵌入向量），二者结果合并排序输出。语义通道在首次搜索时按需懒加载嵌入模型。

社区中已知的具体行为细节包括：`save_context` 当前仅当传入 `id` 时才执行更新，`identity_key` 仍作为可搜索属性而非 upsert 键（见 issue #198）；`get_context` 中 `identity_key` 未命中时会静默回退到 semantic search（见 issue #197）；事件类条目（sessions、harness events、feedback、inbox、user-prompts）目前缺少自动 `expires_at`（见 issue #194）。这些既是从 TypeScript 时代继承下来的契约，也将是 v4.x 后续小版本的演进点。

资料来源：[crates/context-vault-core/src/lib.rs:80-160](), [README.md:60-120]()

## 4. 数据流与请求路径

一个典型的 `serve` + `search` 请求生命周期如下：

```mermaid
sequenceDiagram
    participant Client as MCP / CLI 客户端
    participant CLI as context-vault-cli
    participant Core as context-vault-core
    participant FS as 本地 Markdown 目录
    participant DB as FTS + 向量索引

    Client->>CLI: search(query)
    CLI->>Core: 调用 search()
    Core->>DB: FTS5 全文检索
    Core->>DB: 懒加载嵌入模型 + 向量检索
    DB-->>Core: 双轨结果
    Core-->>CLI: 合并排序后的命中列表
    CLI-->>Client: JSON 响应

    Note over Core,FS: save() 时同步写入 .md 并更新 DB
    Note over Core,DB: reindex() 时遍历 FS 并重建 DB
```

CLI 层只做参数解析与 I/O 转发，所有读取、合并、TTL 计算等业务规则都集中在 core，确保单二进制可被嵌入到多种宿主（CLI、MCP server、未来可能的 FFI）中。

资料来源：[crates/context-vault-cli/src/main.rs:40-120](), [crates/context-vault-core/src/lib.rs:120-200]()

## 5. 演进路径与社区关注点

从 v3 → v4 的迁移路径在社区语境中较为清晰：v3 已通过 `packages/core` 实现了「核心/托管」的关注点分离，并验证了核心搜索、捕获、索引能力；v4.0.0 把这套纯引擎蓝图用 Rust 重新实现，以获得更小的分发体积、更低的启动延迟和更可靠的并发模型。社区当前关注的功能痛点（按 issue 活跃度）包括：

- **Claude Code 插件集成**（#92）：期望通过 hooks 把 save/recall 自动接入 Claude Code。
- **search semantic lane 异常**（#202）：首搜时懒加载嵌入失败 `ctx.insertVec is not a function`，导致向量结果缺失。
- **save_context 的 upsert-by-identity_key**（#198）与 **identity_key miss 静默回退**（#197）：都涉及 `get_context`/`save_context` 的语义清晰度。
- **body_limit 可配置**（#196）：当前 `body.slice(0, 300)` 在多处硬编码。
- **事件条目 TTL**（#194）、**热/冷分层存储**（#190）、**prompt-history 批处理**（#145）等。

这些议题同时存在于 Rust 重写后的版本中，意味着 v4.x 后续小版本会以「保持 core API 稳定 + 修复语义缺陷 + 增加可配置旋钮」为主线演进。

资料来源：[docs/rust-distribution.md:30-80](), [crates/context-vault-core/src/lib.rs:200-260]()

---

## 速查

- **仓库主入口**：`crates/context-vault-cli/src/main.rs`
- **核心库入口**：`crates/context-vault-core/src/lib.rs`
- **工作区声明**：`Cargo.toml`
- **当前版本**：v4.0.0（2026-07-08，BREAKING：Rust 重写，TS 引擎删除）
- **关键命令**：`serve`、`save`、`get`、`search`、`reindex`、`buckets`、`dupes`、`stats counts`

---

<a id='page-2'></a>

## MCP 工具、搜索引擎与 CLI 协议

### 相关页面

相关主题：[项目概览与 Rust 工作区架构](#page-1), [Vault 文件存储、摄入管线与生命周期管理](#page-3), [部署、运维与社区反馈路线图](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [crates/context-vault-core/src/mcp/mod.rs](https://github.com/fellanH/context-vault/blob/main/crates/context-vault-core/src/mcp/mod.rs)
- [crates/context-vault-core/src/mcp/handlers_read.rs](https://github.com/fellanH/context-vault/blob/main/crates/context-vault-core/src/mcp/handlers_read.rs)
- [crates/context-vault-core/src/mcp/handlers_write.rs](https://github.com/fellanH/context-vault/blob/main/crates/context-vault-core/src/mcp/handlers_write.rs)
- [crates/context-vault-core/src/mcp/tool_schemas/mod.rs](https://github.com/fellanH/context-vault/blob/main/crates/context-vault-core/src/mcp/tool_schemas/mod.rs)
- [crates/cv-engine/src/search.rs](https://github.com/fellanH/context-vault/blob/main/crates/cv-engine/src/search.rs)
- [crates/cv-backends/src/queries.rs](https://github.com/fellanH/context-vault/blob/main/crates/cv-backends/src/queries.rs)
</details>

# MCP 工具、搜索引擎与 CLI 协议

`context-vault` 在 v4.0.0 重写为 Rust 后，将原本分散在 TypeScript 中的 MCP 服务器、内存搜索引擎和 CLI 命令统一收敛到三个 crate 中：`context-vault-core` 暴露面向外部 Agent 的 MCP 工具表层，`cv-engine` 提供检索与相似度计算，`cv-backends` 负责底层 SQLite/向量存储查询。本页围绕这三层展开，说明工具如何声明、如何路由到搜索与读写后端，以及 CLI 如何复用同一套协议。

## 一、MCP 服务器与工具注册

`context-vault-core/src/mcp/mod.rs` 是 MCP stdio 服务的入口，负责注册工具表、初始化 embedding 模型懒加载，并把 JSON-RPC 请求分派到 `handlers_read` / `handlers_write`。所有可用工具的 JSON Schema 由 `tool_schemas/mod.rs` 集中生成，意图是让 schema 与实现保持单一来源（issue #191 评估过改用 Python FastMCP，但当前 v4.0.0 仍以 Rust 原生 stdio 实现为主）。

```
资料来源：[crates/context-vault-core/src/mcp/mod.rs:1-120]()
资料来源：[crates/context-vault-core/src/mcp/tool_schemas/mod.rs:1-90]()
```

当前内置工具与典型职责如下：

| 工具 | 类别 | 主要职责 |
| --- | --- | --- |
| `get_context` | 读 | identity_key 精确匹配 → 语义兜底；issue #197 指出未命中时会静默回退 |
| `search` | 读 | FTS + 语义双通道，结果按相似度合并 |
| `save_context` | 写 | upsert 持久化；issue #198 提议按 identity_key 直接 upsert |
| `delete_context` | 写 | 按 id 删除条目 |
| `vault_stats` | 读 | 桶、数量、健康度摘要 |

## 二、读路径：identity_key、语义兜底与 body 切片

`handlers_read.rs` 中的 `get_context` 实现体现了“先精确、再相似”的检索策略。当调用方携带 `identity_key` 时，会先在 `cv-backends/src/queries.rs` 中执行索引查找；若未命中，则按 issue #197 的描述回退到 `cv-engine/src/search.rs` 的语义检索通道。语义通道需要 embedding 模型懒加载，issue #202 报告了在 `context-vault serve` 启动后首次搜索时 `ctx.insertVec is not a function` 的崩溃，导致 25k 条 embedding 永不落库。

```
资料来源：[crates/context-vault-core/src/mcp/handlers_read.rs:420-470]()
资料来源：[crates/cv-engine/src/search.rs:1-160]()
```

`get_context` 返回的正文目前在三处硬编码切片：`handlers_read.rs:431` 的实体匹配、`handlers_read.rs:659` 的非骨架语义结果，以及 `handlers_read.rs:712` 的 `follow_links` 链路结果（更短的 200 字符）。issue #196 提议将这些常量替换为可配置 `body_limit` 参数，以避免长实体被截断后丢失关键上下文。

## 三、写路径：save_context 与事件 TTL

`handlers_write.rs` 中的 `save_context` 负责把内存条目落盘为本地 Markdown（`context-vault-core` 的 `save` 写入 `.md` 并触发增量索引，详见 v4.0.0 release notes）。当前实现仅在调用方显式传入 `id` 时执行 update，否则一律 insert；issue #198 建议把 `identity_key` 作为天然的 upsert 主键，从而省去“先 `get_context` 取 id、再 `save_context`”的两步操作。

事件类条目（session、harness、feedback、user-prompts 等）目前缺少自动 TTL，issue #194 提出在 `save_context` 内部按 `kind` 注入默认 `expires_at`，让 vault 健康检查从“告警”变成“自动清理”。

```
资料来源：[crates/context-vault-core/src/mcp/handlers_write.rs:1-200]()
资料来源：[crates/cv-backends/src/queries.rs:1-180]()
```

## 四、CLI 协议与 MCP 的复用

`context-vault` 的 CLI（`omni vault <verb>`、`omni memory <verb>`）在 v3.20.0 起被裁剪为对 MCP 工具的薄包装：`get`、`buckets`、`dupes`、`stats counts` 等动词直接调用与 MCP 共享的实现。CLI 既可以走本地直连，避免 stdio 序列化的开销；也可以作为 MCP 客户端连接 `context-vault serve`，从而让“mcp 工具 ↔ 搜索引擎 ↔ CLI”三个表面共享同一套语义、同一份 schema、同一组读写后端参数。

```
资料来源：[crates/context-vault-core/src/mcp/tool_schemas/mod.rs:30-120]()
```

整体请求流如下：

```mermaid
flowchart LR
  A[MCP Client / CLI] -->|JSON-RPC 或 argv| B(context-vault-core mcp/mod.rs)
  B --> C{handlers_read / handlers_write}
  C --> D[cv-engine search.rs]
  C --> E[cv-backends queries.rs]
  D --> F[(SQLite + 向量索引)]
  E --> F
```

这种收敛使得 CLI 与 Agent 客户端在协议层面保持一致：当 `identity_key`、语义兜底、`body_limit`、upsert 行为或 TTL 策略在未来被调整时，CLI 行为也会同步变化，无需在两套入口分别维护。

---

<a id='page-3'></a>

## Vault 文件存储、摄入管线与生命周期管理

### 相关页面

相关主题：[MCP 工具、搜索引擎与 CLI 协议](#page-2), [部署、运维与社区反馈路线图](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [crates/cv-vault/src/lib.rs](https://github.com/fellanH/context-vault/blob/main/crates/cv-vault/src/lib.rs)
- [crates/cv-vault/src/frontmatter.rs](https://github.com/fellanH/context-vault/src/frontmatter.rs)
- [crates/cv-vault/src/entry_file.rs](https://github.com/fellanH/context-vault/blob/main/crates/cv-vault/src/entry_file.rs)
- [crates/cv-schema/src/indexing.rs](https://github.com/fellanH/context-vault/blob/main/crates/cv-schema/src/indexing.rs)
- [crates/cv-schema/src/vaults.rs](https://github.com/fellanH/context-vault/blob/main/crates/cv-schema/src/vaults.rs)
- [crates/cv-ingest/src/lib.rs](https://github.com/fellanH/context-vault/blob/main/crates/cv-ingest/src/lib.rs)
</details>

# Vault 文件存储、摄入管线与生命周期管理

## 概述

自 **v4.0.0** 起，context-vault 完成了从 TypeScript 到 **Rust** 的引擎重写，整个产品被收敛到单一二进制中，仓库根目录下以 `crates/` 组织多个职责清晰的 crate。`cv-vault` 负责条目（entry）的本地持久化与读写、frontmatter 解析与 entry 文件 I/O；`cv-schema` 提供索引与 vault 的核心数据结构；`cv-ingest` 则定义了外部来源进入 vault 的摄入管线。本页面向希望理解"数据写入磁盘后发生了什么的开发者，从 `.md` 文件生成到索引、双轨检索（FTS / 向量）以及 TTL / 归档等生命周期机制都涵盖在内。

资料来源：[crates/cv-vault/src/lib.rs:1-1]()、[crates/cv-ingest/src/lib.rs:1-1]()

## 1. 文件存储格式：Markdown + Frontmatter

vault 的存储模型刻意保持"本地优先、人类可读"：每条 entry 以一份带 YAML frontmatter 的 Markdown 文件落地，前置元数据包含主键（ULID）、`identity_key`、`kind`、`tags` 等可索引字段，正文则为 body。`cv-vault/src/frontmatter.rs` 负责把 Rust 中的结构化表示序列化为 frontmatter、并把读回的字符串解析为内存对象；`cv-vault/src/entry_file.rs` 则封装了 `.md` 文件的路径解析、写入、幂等读取等底层 I/O。这种"结构化元数据 + 自由正文"的取舍，使得 `reindex` 可以像遍历目录一样重建索引，而不必依赖单一数据库文件。

资料来源：[crates/cv-vault/src/frontmatter.rs:1-1]()、[crates/cv-vault/src/entry_file.rs:1-1]()

## 2. 摄入管线：从外部事件到 Entry

`cv-ingest/src/lib.rs` 是所有写入路径的入口。它接收来自 MCP 工具调用、CLI、或者会话钩子（如 prompt-history、harness events）的原始负载，做规范化、生成 ULID、按 `kind` 分类后再交给 `cv-vault::save`。对于同类事件型 entry（sessions、feedback、inbox、user-prompts），摄入阶段会按可配置默认值自动写入 `expires_at`（参见 issue #194），让 TTL 在写入时而不是查询时被计算。

```mermaid
flowchart LR
  A[外部事件<br/>MCP / CLI / Hook] --> B[cv-ingest::ingest]
  B --> C{分类 kind}
  C -->|curated| D[生成 ULID + identity_key]
  C -->|event| E[自动设置 expires_at]
  D --> F[cv-vault::save]
  E --> F
  F --> G[frontmatter 序列化]
  G --> H[写入 .md 文件]
  F --> I[触发索引构建]
```

资料来源：[crates/cv-ingest/src/lib.rs:1-1]()、[crates/cv-vault/src/lib.rs:1-1]()

## 3. 索引、双轨检索与生命周期

写入 entry 后，`cv-schema` 子系统会同步更新两类索引：FTS5（全文）用于关键字精确匹配，向量索引用于语义检索。`cv-schema/src/indexing.rs` 暴露了 `index_entry` / `reindex_tree` 等原语，`cv-schema/src/vaults.rs` 维护着"vault 是若干索引的组合"这一抽象。检索时 `get_context` 会按 `identity_key` 精确匹配，命中则直接走实体通道；未命中时按当前实现会 **静默回退** 到语义检索（issue #197 指出该行为容易掩盖 typo），结果会按硬编码 `body.slice(0, 300)` 截断后返回（issue #196）。

| 生命周期阶段 | 触发点 | 负责组件 |
| --- | --- | --- |
| 写入 / 更新 | `save_context` / `upsert` (提案 #198) | `cv-ingest` → `cv-vault` |
| 索引同步 | 每次 `save`、`reindex` 遍历目录 | `cv-schema::indexing` |
| TTL 评估 | 启动时 + 周期性扫描 | `cv-schema::vaults` |
| 归档 / 分层 | 提案 #190：hot/cold 分库 | `cv-vault` + `cv-schema` |

issue #190 进一步提议把单一 vault 拆为 hot（精选 + embedding）和 cold（归档 + 仅 FTS），这属于索引层与生命周期层的联合演进方向。

资料来源：[crates/cv-schema/src/indexing.rs:1-1]()、[crates/cv-schema/src/vaults.rs:1-1]()

## 4. 已知问题与演进方向

社区证据揭示了几条与该模块直接相关的痛点，可作为改进 checklist：

- **语义通道初始化失败**（#202）：`ctx.insertVec is not a function`，导致 25k 条 embedding 永远没落盘——属于摄入到索引阶段的静默失败。
- **upsert 缺位**（#198）：目前必须先 `get` 拿 `id` 再 `save`，`identity_key` 应被提升为一等 upsert 键。
- **`identity_key` miss 静默回退**（#197）：搜索结果容易掩盖拼写错误。
- **事件膨胀**（#145）：prompt-history 1:1 写入会让 vault 在一周内堆积 500+ entry，长期看需要批处理 / 摘要。
- **TTL 缺省**（#194）：事件型 entry 缺乏 `expires_at`，待摄入管线落地后由默认值统一填补。

资料来源：[crates/cv-ingest/src/lib.rs:1-1]()、[crates/cv-vault/src/lib.rs:1-1]()

---

<a id='page-4'></a>

## 部署、运维与社区反馈路线图

### 相关页面

相关主题：[项目概览与 Rust 工作区架构](#page-1), [MCP 工具、搜索引擎与 CLI 协议](#page-2), [Vault 文件存储、摄入管线与生命周期管理](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [install.sh](https://github.com/fellanH/context-vault/blob/main/install.sh)
- [install.ps1](https://github.com/fellanH/context-vault/blob/main/install.ps1)
- [crates/context-vault-gateway/src/main.rs](https://github.com/fellanH/context-vault/blob/main/crates/context-vault-gateway/src/main.rs)
- [crates/context-vault-gateway/src/handlers.rs](https://github.com/fellanH/context-vault/blob/main/crates/context-vault-gateway/src/handlers.rs)
- [crates/context-vault-cli/src/cmd_setup.rs](https://github.com/fellanH/context-vault/blob/main/crates/context-vault-cli/src/cmd_setup.rs)
- [crates/context-vault-cli/src/cmd_lifecycle.rs](https://github.com/fellanH/context-vault/blob/main/crates/context-vault-cli/src/cmd_lifecycle.rs)
</details>

# 部署、运维与社区反馈路线图

## 1. 部署形态概览

context-vault 在 v4.0.0 完成了一次破坏性重写：引擎从 TypeScript 迁移到 Rust，TS 引擎与 Node CLI 已被删除，整个产品收敛为一个 Rust 二进制（`crates/`）。这一变化直接简化了部署拓扑——`context-vault serve` 在启动后承担 lazy embedding 加载、search 服务与 MCP 桥接的全部职责。

平台无关的安装入口由两条脚本覆盖：

- `install.sh`：Unix/macOS 路径，负责下载预编译二进制并写入 PATH
- `install.ps1`：Windows 路径，使用 PowerShell 完成等价的安装动作

两条脚本共享一致的「下载 → 校验 → 放置 → 提示重启 shell」流水线，使得本地优先（local-first）的安装体验与平台解耦。资料来源：[install.sh]()、[install.ps1]()。

## 2. 运行与生命周期运维

部署完成后，运维动作主要由 CLI 子命令与 Gateway 二进制承担：

- `cmd_setup.rs` 负责首运行配置：初始化 vault 目录、生成 config、注册 MCP 客户端
- `cmd_lifecycle.rs` 暴露 `serve / stop / status / reindex` 等动词，承载进程级生命周期管理
- `context-vault-gateway/src/main.rs` 是 HTTP/MCP 入口，绑定端口、装配路由并加载 embedding 模型
- `handlers.rs` 实现 `save / get / search` 等核心请求处理，配合 FTS 与 semantic 两条 lane

启动时日志会输出 `[context-vault] Loading embedding model (threads=...)`，随后 `search` 第一次被调用时触发 lazy embedding。资料来源：[crates/context-vault-cli/src/cmd_setup.rs]()、[crates/context-vault-cli/src/cmd_lifecycle.rs]()、[crates/context-vault-gateway/src/main.rs:1-120]()。

## 3. 社区反馈驱动的已知运维痛点

仓库的 Issue 区是当前运维痛点的最直接信号源，以下几项已被多名用户反复触发：

| Issue | 运维症状 | 受影响路径 |
|-------|---------|-----------|
| #202 | `ctx.insertVec is not a function` 导致 25k embeddings 永不写入 | search semantic lane 启动期 |
| #197 | `identity_key` miss 时静默回退到全量语义搜索 | `get_context` 行 435 |
| #198 | `save_context` 不支持 `identity_key` upsert，迫使两步调用 | 写入路径 |
| #196 | `body.slice(0, 300)` 在三处硬编码，无法覆盖 | `get_context` 行 431/659/712 |
| #194 | 事件类条目缺少 `expires_at`，触发 vault health 告警 | 事件摄取路径 |
| #190 | 单库混合 curated + bulk，分层存储尚未落地 | 存储层 |

这些痛点共同描绘出 v4.x 阶段的运维画像：**功能性可用、语义 lane 偶发抖动、可配置性与一致性需要补强**。资料来源：[issues/202]()、[issues/197]()、[issues/198]()、[issues/196]()。

## 4. 路线图与社区牵引的演进方向

社区反馈已转化为清晰的演进队列，可分为三档：

**短期修复（与 v4.x 同步）**
- 修复 #202 中 `insertVec` 路径断裂，恢复 semantic lane 写入
- 为 `get_context` 引入可配置 `body_limit`（#196）
- 让 `identity_key` miss 在 #197 中显式报错而非静默 fallback
- 在 #198 中实现 `save_context(identity_key, …)` 一键 upsert

**中期重构（v5 候选）**
- #190 的分层存储：hot/cold 双库，冷库 FTS-only，hot 库带 embedding
- #194 的事件 TTL：`expires_at` 按 kind 自动写入并驱动过期回收
- #145 的 prompt-history 批处理/汇总，缓解 75% 的 vault 体积膨胀
- #191 探索以 FastMCP 重写 MCP 层，统一 stdio 协议描述

**长期愿景（与 v3 / v4 架构对齐）**
- #185 的三层分离：纯本地 engine core 与 hosted 关注点解耦
- #92 的 ClaudeCode 官方插件：把 vault 作为 recall memory 的默认后端
- #167 的「自改进 Agent OS」叙事，将上下文管理作为长期产品定位

```mermaid
flowchart LR
  A[安装 install.sh / install.ps1] --> B[cmd_setup 初始化]
  B --> C[cmd_lifecycle serve]
  C --> D{Gateway main.rs}
  D --> E[FTS lane]
  D --> F[Semantic lane + lazy embedding]
  E & F --> G[handlers.rs save/get/search]
  G --> H[社区反馈回路<br/>#202 #197 #198 #196 #190]
  H --> I[路线图 v4.x → v5]
```

资料来源：[issues/202]()、[issues/190]()、[issues/185]()。

## 5. 运维建议小结

对一个负责部署与日常运维的工程师而言，推荐节奏是：

1. 用 `install.sh` 或 `install.ps1` 完成安装，依赖 Rust 二进制而非 Node 运行时
2. 通过 `cmd_lifecycle` 的 `status / reindex` 做周期性健康检查
3. 关注 `vault health` 告警，特别是事件条目 >500 且缺 `expires_at` 的情况（#194）
4. 跟踪 semantic lane 日志，识别 #202 类 lazy embedding 失败
5. 在社区 Issue 中反馈新场景，使路线图与真实使用同步

这套闭环使运维不再只是被动救火，而是与社区驱动的演进保持同频。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：fellanH/context-vault

摘要：发现 31 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: Explore FastMCP (Python) rewrite for MCP server。

## 1. 安装坑 · 失败模式：installation: Explore FastMCP (Python) rewrite for MCP server

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Explore FastMCP (Python) rewrite for MCP server
- 对用户的影响：Developers may fail before the first successful local run: Explore FastMCP (Python) rewrite for MCP server
- 证据：failure_mode_cluster:github_issue | https://github.com/fellanH/context-vault/issues/191 | Explore FastMCP (Python) rewrite for MCP server

## 2. 安装坑 · 失败模式：installation: v3.12.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v3.12.0
- 对用户的影响：Upgrade or migration may change expected behavior: v3.12.0
- 证据：failure_mode_cluster:github_release | https://github.com/fellanH/context-vault/releases/tag/v3.12.0 | v3.12.0

## 3. 安装坑 · 失败模式：installation: v3.13.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v3.13.0
- 对用户的影响：Upgrade or migration may change expected behavior: v3.13.0
- 证据：failure_mode_cluster:github_release | https://github.com/fellanH/context-vault/releases/tag/v3.13.0 | v3.13.0

## 4. 安装坑 · 失败模式：installation: v3.16.1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v3.16.1
- 对用户的影响：Upgrade or migration may change expected behavior: v3.16.1
- 证据：failure_mode_cluster:github_release | https://github.com/fellanH/context-vault/releases/tag/v3.16.1 | v3.16.1

## 5. 安装坑 · 失败模式：installation: v3: Clean local/hosted separation — pure engine core

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v3: Clean local/hosted separation — pure engine core
- 对用户的影响：Developers may fail before the first successful local run: v3: Clean local/hosted separation — pure engine core
- 证据：failure_mode_cluster:github_issue | https://github.com/fellanH/context-vault/issues/185 | v3: Clean local/hosted separation — pure engine core

## 6. 安装坑 · 失败模式：installation: v4.0.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v4.0.0
- 对用户的影响：Upgrade or migration may change expected behavior: v4.0.0
- 证据：failure_mode_cluster:github_release | https://github.com/fellanH/context-vault/releases/tag/v4.0.0 | v4.0.0

## 7. 安装坑 · 来源证据：Blog post: Building a Self-Improving Agent OS

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Blog post: Building a Self-Improving Agent OS
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/fellanH/context-vault/issues/167 | 来源类型 github_issue 暴露的待验证使用条件。

## 8. 安装坑 · 来源证据：Explore FastMCP (Python) rewrite for MCP server

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Explore FastMCP (Python) rewrite for MCP server
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/fellanH/context-vault/issues/191 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 9. 安装坑 · 来源证据：Search semantic lane fails: insertVec is not a function (25k embeddings never materialize)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Search semantic lane fails: insertVec is not a function (25k embeddings never materialize)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/fellanH/context-vault/issues/202 | 来源类型 github_issue 暴露的待验证使用条件。

## 10. 安装坑 · 来源证据：Tiered storage: separate hot/cold databases for curated vs bulk data

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Tiered storage: separate hot/cold databases for curated vs bulk data
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/fellanH/context-vault/issues/190 | 来源类型 github_issue 暴露的待验证使用条件。

## 11. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/fellanH/context-vault | host_targets=mcp_host, claude_code, claude, cursor

## 12. 配置坑 · 失败模式：configuration: Add configurable body_limit parameter to get_context

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Add configurable body_limit parameter to get_context
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Add configurable body_limit parameter to get_context
- 证据：failure_mode_cluster:github_issue | https://github.com/fellanH/context-vault/issues/196 | Add configurable body_limit parameter to get_context

## 13. 配置坑 · 失败模式：configuration: Auto-set expires_at on event category entries

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Auto-set expires_at on event category entries
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Auto-set expires_at on event category entries
- 证据：failure_mode_cluster:github_issue | https://github.com/fellanH/context-vault/issues/194 | Auto-set expires_at on event category entries

## 14. 配置坑 · 失败模式：configuration: Blog post: Building a Self-Improving Agent OS

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Blog post: Building a Self-Improving Agent OS
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Blog post: Building a Self-Improving Agent OS
- 证据：failure_mode_cluster:github_issue | https://github.com/fellanH/context-vault/issues/167 | Blog post: Building a Self-Improving Agent OS

## 15. 配置坑 · 失败模式：configuration: Prompt-history event consolidation: batch or summarize instead of 1:1 capture

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Prompt-history event consolidation: batch or summarize instead of 1:1 capture
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Prompt-history event consolidation: batch or summarize instead of 1:1 capture
- 证据：failure_mode_cluster:github_issue | https://github.com/fellanH/context-vault/issues/145 | Prompt-history event consolidation: batch or summarize instead of 1:1 capture

## 16. 配置坑 · 失败模式：configuration: Tiered storage: separate hot/cold databases for curated vs bulk data

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Tiered storage: separate hot/cold databases for curated vs bulk data
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Tiered storage: separate hot/cold databases for curated vs bulk data
- 证据：failure_mode_cluster:github_issue | https://github.com/fellanH/context-vault/issues/190 | Tiered storage: separate hot/cold databases for curated vs bulk data

## 17. 配置坑 · 失败模式：configuration: v3.11.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v3.11.0
- 对用户的影响：Upgrade or migration may change expected behavior: v3.11.0
- 证据：failure_mode_cluster:github_release | https://github.com/fellanH/context-vault/releases/tag/v3.11.0 | v3.11.0

## 18. 配置坑 · 失败模式：configuration: v3.16.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v3.16.0
- 对用户的影响：Upgrade or migration may change expected behavior: v3.16.0
- 证据：failure_mode_cluster:github_release | https://github.com/fellanH/context-vault/releases/tag/v3.16.0 | v3.16.0

## 19. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/fellanH/context-vault | README/documentation is current enough for a first validation pass.

## 20. 维护坑 · 失败模式：migration: v3.19.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v3.19.0
- 对用户的影响：Upgrade or migration may change expected behavior: v3.19.0
- 证据：failure_mode_cluster:github_release | https://github.com/fellanH/context-vault/releases/tag/v3.19.0 | v3.19.0

## 21. 维护坑 · 来源证据：Support upsert-by-identity_key in save_context

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Support upsert-by-identity_key in save_context
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/fellanH/context-vault/issues/198 | 来源类型 github_issue 暴露的待验证使用条件。

## 22. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/fellanH/context-vault | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/fellanH/context-vault | no_demo; severity=medium

## 24. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/fellanH/context-vault | no_demo; severity=medium

## 25. 安全/权限坑 · 来源证据：Add configurable body_limit parameter to get_context

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add configurable body_limit parameter to get_context
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/fellanH/context-vault/issues/196 | 来源类型 github_issue 暴露的待验证使用条件。

## 26. 安全/权限坑 · 来源证据：identity_key miss silently falls through to semantic search

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：identity_key miss silently falls through to semantic search
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/fellanH/context-vault/issues/197 | 来源类型 github_issue 暴露的待验证使用条件。

## 27. 安全/权限坑 · 来源证据：v3: Clean local/hosted separation — pure engine core

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3: Clean local/hosted separation — pure engine core
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/fellanH/context-vault/issues/185 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 28. 能力坑 · 失败模式：capability: Search semantic lane fails: insertVec is not a function (25k embeddings never materialize)

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Search semantic lane fails: insertVec is not a function (25k embeddings never materialize)
- 对用户的影响：Developers may hit a documented source-backed failure mode: Search semantic lane fails: insertVec is not a function (25k embeddings never materialize)
- 证据：failure_mode_cluster:github_issue | https://github.com/fellanH/context-vault/issues/202 | Search semantic lane fails: insertVec is not a function (25k embeddings never materialize)

## 29. 能力坑 · 失败模式：capability: identity_key miss silently falls through to semantic search

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: identity_key miss silently falls through to semantic search
- 对用户的影响：Developers may hit a documented source-backed failure mode: identity_key miss silently falls through to semantic search
- 证据：failure_mode_cluster:github_issue | https://github.com/fellanH/context-vault/issues/197 | identity_key miss silently falls through to semantic search

## 30. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/fellanH/context-vault | issue_or_pr_quality=unknown

## 31. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/fellanH/context-vault | release_recency=unknown

<!-- canonical_name: fellanH/context-vault; human_manual_source: deepwiki_human_wiki -->