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 职责如下：

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 请求生命周期如下：

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

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]()

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

二、读路径：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]()

整体请求流如下：

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 行为也会同步变化，无需在两套入口分别维护。

概述

自 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 在写入时而不是查询时被计算。

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）。

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

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 区是当前运维痛点的最直接信号源，以下几项已被多名用户反复触发：

这些痛点共同描绘出 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」叙事，将上下文管理作为长期产品定位

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 中反馈新场景，使路线图与真实使用同步

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

Pitfall Log / 踩坑日志

项目：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