# context-vault - Doramagic AI Context Pack

> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。

## 充分原则

- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。
- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。

## 给宿主 AI 的使用方式

你正在读取 Doramagic 为 context-vault 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。

## Claim 消费规则

- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。
- **事实最低状态**：`supported`
- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。
- `weak`：只能作为低置信度线索，必须要求用户继续核实。
- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。
- `unverified`：不得作为事实使用，应明确说证据不足。
- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。

## 它最适合谁

- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86

## 它能做什么

- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`packages/local/assets/skills/compile-context/skill.md`, `packages/local/assets/skills/vault-setup/skill.md` Claim：`clm_0001` supported 0.86
- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `packages/local/README.md`, `packages/sdk/README.md` Claim：`clm_0002` supported 0.86

## 怎么开始

- `curl -fsSL https://raw.githubusercontent.com/fellanH/context-vault/main/install.sh | sh` 证据：`README.md` Claim：`clm_0004` supported 0.86
- `git clone https://github.com/fellanH/context-vault.git` 证据：`README.md` Claim：`clm_0005` supported 0.86
- `npm install -g context-vault` 证据：`packages/local/README.md` Claim：`clm_0006` supported 0.86
- `npm install @context-vault/sdk` 证据：`packages/sdk/README.md` Claim：`clm_0007` supported 0.86

## 继续前判断卡

- **当前建议**：仅建议沙盒试装
- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。

### 30 秒判断

- **现在怎么做**：仅建议沙盒试装
- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装
- **先别相信**：真实输出质量不能在安装前相信。
- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件

### 现在可以相信

- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86
- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`packages/local/assets/skills/compile-context/skill.md`, `packages/local/assets/skills/vault-setup/skill.md` Claim：`clm_0001` supported 0.86
- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `packages/local/README.md`, `packages/sdk/README.md` Claim：`clm_0002` supported 0.86
- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0004` supported 0.86

### 现在还不能相信

- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。
- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。
- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`packages/local/assets/skills/compile-context/skill.md`, `packages/local/assets/skills/vault-setup/skill.md`
- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。
- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。
- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。
- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`

### 继续会触碰什么

- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `packages/local/README.md`, `packages/sdk/README.md`
- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`packages/local/assets/skills/compile-context/skill.md`, `packages/local/assets/skills/vault-setup/skill.md`
- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `packages/local/README.md`, `packages/sdk/README.md`
- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。

### 最小安全下一步

- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）
- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）
- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）
- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）

### 退出方式

- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。
- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。
- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。
- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。

## 哪些只能预览

- 解释项目适合谁和能做什么
- 基于项目文档演示典型对话流程
- 帮助用户判断是否值得安装或继续研究

## 哪些必须安装后验证

- 真实安装 Skill、插件或 CLI
- 执行脚本、修改本地文件或访问外部服务
- 验证真实输出质量、性能和兼容性

## 边界与风险判断卡

- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0008` inferred 0.45
- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `packages/local/README.md`, `packages/sdk/README.md` Claim：`clm_0009` supported 0.86
- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。
- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。
- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。

## 开工前工作上下文

### 加载顺序

- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。
- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。
- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。
- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。
- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。

### 任务路由

- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`packages/local/assets/skills/compile-context/skill.md`, `packages/local/assets/skills/vault-setup/skill.md` Claim：`clm_0001` supported 0.86
- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `packages/local/README.md`, `packages/sdk/README.md` Claim：`clm_0002` supported 0.86

### 上下文规模

- 文件总数：218
- 重要文件覆盖：40/218
- 证据索引条目：80
- 角色 / Skill 条目：2

### 证据不足时的处理

- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。
- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。
- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。
- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。

## Prompt Recipes

### 适配判断

- 目标：判断这个项目是否适合用户当前任务。
- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。

```text
请基于 context-vault 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。
```

### 安装前体验

- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。
- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。

```text
请把 context-vault 当作安装前体验资产，而不是已安装工具或真实运行环境。

请严格输出四段：
1. 先问我 3 个必要问题。
2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。
3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。
4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。

硬性边界：
- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。
- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。
- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。
- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。
- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。
- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。

```

### 角色 / Skill 选择

- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。
- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。

```text
请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。
```

### 风险预检

- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。
- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。

```text
请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。
```

### 宿主 AI 开工指令

- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。
- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。

```text
请基于 context-vault 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。
```

## 角色 / Skill 索引

- 共索引 2 个角色 / Skill / 项目文档条目。

- **compile-context**（skill）： 激活提示：当用户任务与“compile-context”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/local/assets/skills/compile-context/skill.md`
- **vault-setup**（skill）： 激活提示：当用户任务与“vault-setup”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/local/assets/skills/vault-setup/skill.md`

## 证据索引

- 共索引 80 条证据。

- **context-vault**（documentation）：! npm version https://img.shields.io/npm/v/context-vault https://www.npmjs.com/package/context-vault ! license https://img.shields.io/npm/l/context-vault ./LICENSE ! node https://img.shields.io/node/v/context-vault https://nodejs.org 证据：`README.md`
- **context-vault**（documentation）：! npm version https://img.shields.io/npm/v/context-vault https://www.npmjs.com/package/context-vault ! npm downloads https://img.shields.io/npm/dm/context-vault https://www.npmjs.com/package/context-vault ! license https://img.shields.io/npm/l/context-vault ./LICENSE ! node https://img.shields.io/node/v/context-vault https://nodejs.org 证据：`packages/local/README.md`
- **@context-vault/sdk**（documentation）：Context lifecycle SDK for AI agents. Save, search, and manage persistent context with freshness scoring. 证据：`packages/sdk/README.md`
- **Rust binary distribution**（documentation）：See specs/rust-core.md for engine design and docs/npm-rust-migration.md for the migration stages. This file covers the binary packaging and release mechanics only. 证据：`docs/rust-distribution.md`
- **Package**（package_manifest）：{ "name": "context-vault-monorepo", "private": true, "version": "4.0.0", "type": "module", "workspaces": "packages/local", "packages/sdk" , "scripts": { "build": "cargo build --release --workspace", "cli": "node packages/local/bin/cli.js", "test": "cargo test --workspace", "release": "node scripts/release.mjs" }, "engines": { "node": " =18" }, "devDependencies": { "typescript": "^5.7.0" } } 证据：`package.json`
- **Package**（package_manifest）：{ "name": "context-vault", "version": "4.0.0", "type": "module", "description": "Persistent memory for AI agents — saves and searches knowledge across sessions", "bin": { "context-vault": "bin/cli.js", "context-mcp": "bin/cli.js", "memory": "bin/cli.js" }, "exports": { "./cli": "./bin/cli.js" }, "scripts": {}, "files": "assets/", "bin/", ".mcp.json", "README.md", "LICENSE" , "license": "MIT", "engines": { "node": " =18" }, "author": "Felix Hellstrom", "repository": { "type": "git", "url": "git+https://github.com/fellanH/context-vault.git" }, "homepage": "https://github.com/fellanH/context-vault", "bugs": { "url": "https://github.com/fellanH/context-vault/issues" }, "keywords": "mcp", "model… 证据：`packages/local/package.json`
- **Package**（package_manifest）：{ "name": "@context-vault/sdk", "version": "0.1.0", "description": "Context lifecycle SDK for AI agents. Save, search, and manage persistent context with freshness scoring.", "type": "module", "main": "dist/index.js", "types": "dist/index.d.ts", "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }, "./hosted": { "types": "./dist/hosted.d.ts", "import": "./dist/hosted.js" } }, "files": "dist" , "license": "Apache-2.0", "keywords": "context", "ai", "agents", "memory", "mcp", "lifecycle" , "devDependencies": { "@types/node": "^22.0.0", "typescript": "^5.5.0" } } 证据：`packages/sdk/package.json`
- **compile-context skill**（skill_instruction）：When the user asks to compile context or create a brief for a topic, call create snapshot to synthesize a context brief from the vault. 证据：`packages/local/assets/skills/compile-context/skill.md`
- **vault-setup skill**（skill_instruction）：Agent-assisted setup that customizes the context-vault installation for the user's workflow. Always show what you plan to do before doing it. Never modify existing rules without permission. 证据：`packages/local/assets/skills/vault-setup/skill.md`
- **License**（source_file）：This repository uses a dual-license model: 证据：`LICENSE`
- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the "Software" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`packages/local/LICENSE`
- **--vault-db FTS probe**（documentation）：Rust context-vault bench --vault-db runs read-only probes. FTS token selection is not the fixture hybrid path; see timings.sqlite.fts user probe in JSON output. 证据：`docs/bench-vault-fts.md`
- **Claude Code Plugin**（documentation）：Context Vault integrates with Claude Code via a UserPromptSubmit hook. On every prompt, it searches your vault for relevant entries and injects them as a XML block that Claude receives alongside your message. 证据：`docs/claude-code-plugin.md`
- **Development Workflow**（documentation）：How to make changes to context-vault, release them, and verify they work as a real user would experience. 证据：`docs/development-workflow.md`
- **npm → Rust CLI migration**（documentation）：Archived 2026-07-03. The actual cutover skipped the staged Stage-1-IPC approach below and went straight to deleting the TS engine 2026-07-02 . Current status lives in project-management/docs/rust-cutover-runbook.md . Kept for historical context. 证据：`docs/archive/npm-rust-migration.md`
- **sqlite-vec hooks**（documentation）：Archived 2026-07-03. Resolved — sqlite-vec does load via rusqlite 's bundled feature; it's wired into crates/cv-backends/src/sqlite.rs and sqlite ops.rs . Kept for historical context on the original open question. 证据：`docs/archive/rust-sqlite-vec-hooks.md`
- **Connect in 2 Minutes Hosted**（documentation）：Use Context Vault in the cloud — no local install, no Node.js. Works across devices. Sign up at app.context-vault.com https://app.context-vault.com , get an API key, then add the MCP endpoint to your AI tool. 证据：`docs/distribution/connect-in-2-minutes.md`
- **Hosted-Omni Migration Prototype Campaign 2026-06-17**（documentation）：Hosted-Omni Migration Prototype Campaign 2026-06-17 证据：`project-management/docs/2026-06-17-hosted-omni-prototype-campaign.md`
- **Rust cutover runbook — Phase 7**（documentation）：Status updated 2026-07-03 : Engine migration Phases 0–6 and Phase 7's TS deletion are COMPLETE, committed, and pushed to origin/main . The session-end parity gap below is closed. This dev machine's global context-vault is now the native Rust binary , installed directly via cargo install --path crates/context-vault-cli no Node in the loop at all — the old npm package was uninstalled . The outward-facing public npm publish is a separate, NOT-yet-executed step — it ships to a live npm product via a cross-compile path that has never actually run, and needs human sign-off see "Remaining: the actual release" below . 证据：`project-management/docs/rust-cutover-runbook.md`
- **Shared dependency versions. Members opt in via .workspace = true .**（source_file）：workspace resolver = "2" members = "crates/cv-engine", "crates/cv-vault", "crates/cv-schema", "crates/cv-lifecycle", "crates/cv-ingest", "crates/cv-backends", "crates/context-vault-core", "crates/context-vault-cli", "crates/context-vault-mcp", "crates/context-vault-gateway", 证据：`Cargo.toml`
- **Install the native context-vault binary on Windows — no Node, no npm.**（source_file）：Install the native context-vault binary on Windows — no Node, no npm. irm https://raw.githubusercontent.com/fellanH/context-vault/main/install.ps1 iex Env overrides: $env:CONTEXT VAULT VERSION release tag to install, e.g. v4.0.0 default: latest $env:CONTEXT VAULT INSTALL DIR install directory default: %LOCALAPPDATA%\context-vault\bin 证据：`install.ps1`
- **Install**（source_file）：set -euo pipefail REPO="fellanH/context-vault" INSTALL DIR="${CONTEXT VAULT INSTALL DIR:-$HOME/.local/bin}" info { printf '%s\n' "$ " &2; } die { printf 'context-vault: %s\n' "$ " &2 exit 1 } detect target { os="$ uname -s " arch="$ uname -m " case "$os" in Darwin case "$arch" in arm64 echo "aarch64-apple-darwin" ;; x86 64 echo "x86 64-apple-darwin" ;; die "unsupported macOS architecture: $arch" ;; esac ;; Linux case "$arch" in aarch64 arm64 echo "aarch64-unknown-linux-gnu" ;; x86 64 echo "x86 64-unknown-linux-gnu" ;; die "unsupported Linux architecture: $arch" ;; esac ;; MINGW MSYS CYGWIN die "use install.ps1 on Windows: https://raw.githubusercontent.com/$REPO/main/install.ps1" ;; die "uns… 证据：`install.sh`
- **bench + invoke are maintainer/debug tooling, not part of the shipped command surface —**（source_file）：package name = "context-vault-cli" version = "4.0.0" edition.workspace = true license.workspace = true description = "Context Vault CLI — engine subcommands mcp, save/get/search/list/delete, lifecycle . Ships the context-vault binary." 证据：`crates/context-vault-cli/Cargo.toml`
- **Cmd Lifecycle**（source_file）：use std::collections::HashMap; ⋮---- use anyhow::Result; use context vault core::engine::VaultEngine; ⋮---- use crate::engine cmd; ⋮---- pub async fn run archive days: Option - Result { ⋮---- let days = days.unwrap or 365 as i64; ⋮---- config.insert tier.to string , Some days ; ⋮---- let db = engine.raw db ; let vault dir = engine.vault dir path ; ⋮---- let conn = db.lock .unwrap ; candidates = find archive candidates &conn, &config ?; result = archive entries &conn, &vault dir, &candidates ?; ⋮---- println! "archived {} entries {} days untouched ", result.count, days ; ⋮---- println! " {} — {}", c.id, c.title.as deref .unwrap or " untitled " ; ⋮---- Ok ⋮---- pub async fn run restore id: &s… 证据：`crates/context-vault-cli/src/cmd_lifecycle.rs`
- **Cmd Setup**（source_file）：use std::path::PathBuf; ⋮---- pub struct ClientConfig { ⋮---- pub struct SetupOpts { ⋮---- impl ClientConfig { fn detect &self - bool { self.config path.parent .is some and p p.exists ⋮---- pub fn get all clients - Vec { let home = dirs::home dir .expect "home dir" ; ⋮---- vec! ⋮---- pub crate fn get server entry - Value { json! { ⋮---- pub crate fn merge config mut existing: Value, new entry: Value - Value { ⋮---- if let Some servers = obj.get mut "mcpServers" { ⋮---- srv.insert "context-vault".to string , new entry ; ⋮---- obj.insert "mcpServers".to string , json! { "context-vault": new entry } , ⋮---- fn select target clients ⋮---- return Ok all clients.iter .filter c c.detect .collect ;… 证据：`crates/context-vault-cli/src/cmd_setup.rs`
- **Main**（source_file）：mod engine cmd; mod cmd read; mod cmd write; mod cmd lifecycle; mod cmd ingest; mod cmd setup; mod cmd schema; mod cmd move; mod cmd session end; mod client paths; mod setup register; mod cli; ⋮---- mod ipc invoke; ⋮---- use clap::Parser; ⋮---- use std::path::PathBuf; ⋮---- use anyhow::anyhow; ⋮---- use context vault core::bench harness; ⋮---- use anyhow::Result; ⋮---- async fn main - Result { ⋮---- println! ⋮---- Ok ⋮---- Some cmd = dispatch cmd .await, ⋮---- async fn dispatch cmd: Commands - Result { ⋮---- } = run bench ⋮---- Commands::PostToolCall = Ok , ⋮---- fn run bench ⋮---- return Err anyhow! "only --format json is supported in this slice" ; ⋮---- let mut stdout = stdout.lock ; ⋮---… 证据：`crates/context-vault-cli/src/main.rs`
- **async-trait, tempfile, and rusqlite bundled are normal deps above and cover the test targets too.**（source_file）：package name = "context-vault-core" version = "0.2.2" edition.workspace = true license.workspace = true description = "Context Vault engine: SQLite storage, hybrid FTS+vector search, embeddings, and the markdown vault Rust core library ." 证据：`crates/context-vault-core/Cargo.toml`
- **Mod**（source_file）：mod corpus; pub mod fts token; pub crate mod sqlite lane; ⋮---- use std::fs; use std::path::PathBuf; use std::time::Instant; ⋮---- use serde::Serialize; ⋮---- pub use fts token::FtsPickResult; pub use sqlite lane::SqliteLane; ⋮---- pub enum DiskMode { ⋮---- pub enum WorkloadMix { ⋮---- pub struct BenchArgs { ⋮---- pub struct BenchOutput { ⋮---- pub struct BenchMeta { ⋮---- pub struct Timings { ⋮---- pub struct DiskModesDoc { ⋮---- pub struct WorkloadMixesDoc { ⋮---- pub fn run bench args: BenchArgs - anyhow::Result { ⋮---- let corpus = generate corpus args.corpus root.clone , ⋮---- let corpus generation ms = t0.elapsed .as secs f64 1000.0; ⋮---- sqlite lane::run fixture probes &conn, args.w… 证据：`crates/context-vault-core/src/bench_harness/mod.rs`
- **Lib**（source_file）：pub mod bench harness; ⋮---- pub use cv schema::indexing; ⋮---- pub mod mcp; pub mod paths; 证据：`crates/context-vault-core/src/lib.rs`
- **Handlers Read**（source_file）：use std::sync::Arc; use serde json::Value; use crate::engine::VaultEngine; ⋮---- pub async fn handle get context ⋮---- let query = args.get "query" .and then v v.as str ; ⋮---- .get "limit" .and then v v.as u64 .unwrap or 10 as usize; ⋮---- .hybrid search query.unwrap or "" , opts ⋮---- .map err e e.to string ?; ⋮---- if results.is empty { return Ok format! "No results found{}", ⋮---- let mut lines = vec! format! " Results {} matches \n", results.len ; ⋮---- let title = e.title.as deref .unwrap or " untitled " ; lines.push format! ⋮---- if let Some body = &e.body.lines .next { lines.push format! " {}", body ; ⋮---- Ok lines.join "\n" ⋮---- pub async fn handle list context ⋮---- let kind = a… 证据：`crates/context-vault-core/src/mcp/handlers_read.rs`
- **Handlers Write**（source_file）：use std::sync::Arc; use serde json::Value; ⋮---- pub async fn handle save context ⋮---- .get "kind" .and then v v.as str .ok or "Required: kind" ? .to string ; ⋮---- .get "body" ⋮---- .ok or "Required: body" ? ⋮---- let title = args.get "title" .and then v v.as str .map s s.to string ; let id = args.get "id" .and then v v.as str .map s s.to string ; ⋮---- let tags = args.get "tags" .and then v v.as array .map arr { arr.iter .filter map v v.as str .map s s.to string .collect ⋮---- meta: args.get "meta" .cloned , source: args.get "source" .and then v v.as str .map s s.to string , identity key: args.get "identity key" .and then v v.as str .map s s.to string , tier: args.get "tier" .and then v… 证据：`crates/context-vault-core/src/mcp/handlers_write.rs`
- **Mod**（source_file）：pub mod stdio; pub mod tools; ⋮---- pub super mod tool schemas; pub super mod handlers read; pub super mod handlers write; pub super mod handlers ingest; ⋮---- pub use stdio::run; ⋮---- use std::sync::Arc; ⋮---- use crate::engine::VaultEngine; ⋮---- pub async fn recall 证据：`crates/context-vault-core/src/mcp/mod.rs`
- **Mod**（source_file）：mod core; mod extra; 证据：`crates/context-vault-core/src/mcp/tool_schemas/mod.rs`
- **Cargo**（source_file）：package name = "context-vault-gateway" version = "0.2.2" edition.workspace = true license.workspace = true description = "Context Vault self-hosted HTTP gateway: a thin axum server exposing the Rust engine over a bearer-authenticated REST API." 证据：`crates/context-vault-gateway/Cargo.toml`
- **Handlers**（source_file）：use std::sync::Arc; ⋮---- use serde::Deserialize; use serde json::json; ⋮---- use crate::AppState; ⋮---- pub crate async fn auth State state : State , req: axum::extract::Request, next: Next - Response { ⋮---- .headers .get AUTHORIZATION .and then h h.to str .ok .and then h h.strip prefix "Bearer " ; if presented == Some state.api key.as str { return next.run req .await; ⋮---- StatusCode::UNAUTHORIZED, Json json! { "error": "Invalid or missing API key" } .into response ⋮---- pub crate async fn health handler - Response { StatusCode::OK, Json json! { "ok": true } .into response ⋮---- pub crate async fn status handler State state : State - Response { match state.engine.stats .await { ⋮---- Js… 证据：`crates/context-vault-gateway/src/handlers.rs`
- **Main**（source_file）：mod handlers; ⋮---- use std::sync::Arc; ⋮---- pub crate struct AppState { ⋮---- async fn main - Result { ⋮---- .context "GATEWAY API KEY is required bearer token for the gateway " ?; let host = std::env::var "GATEWAY HOST" .unwrap or else "127.0.0.1".to string ; let port = std::env::var "GATEWAY PORT" .unwrap or else "8787".to string ; ⋮---- let engine = build engine .await?; ⋮---- .route "/api/vault/status", get handlers::status handler .route "/api/vault/entries", post handlers::save handler .route "/api/vault/entries/{id}", get handlers::get handler .delete handlers::delete handler .route "/api/vault/search", get handlers::search handler .route layer from fn with state state.clone , hand… 证据：`crates/context-vault-gateway/src/main.rs`
- **Cargo**（source_file）：package name = "context-vault-mcp" version = "0.2.2" edition.workspace = true license.workspace = true description = "Context Vault MCP stdio server — thin binary over context-vault-core." 证据：`crates/context-vault-mcp/Cargo.toml`
- **Main**（source_file）：use anyhow::Result; ⋮---- async fn main - Result { 证据：`crates/context-vault-mcp/src/main.rs`
- **Cargo**（source_file）：package name = "cv-backends" version = "0.2.2" edition.workspace = true license.workspace = true description = "Context Vault SQLite backend: storage, FTS+vec search, embeddings." 证据：`crates/cv-backends/Cargo.toml`
- **Lib**（source_file）：pub mod embedder; pub mod queries; pub mod row map; pub mod sqlite; pub mod sqlite ops; ⋮---- pub use sqlite::SqliteBackend; 证据：`crates/cv-backends/src/lib.rs`
- **Queries**（source_file）：pub use super::row map::entry from row; ⋮---- use anyhow::Result; ⋮---- use std::collections::HashMap; use zerocopy::AsBytes; ⋮---- fn filter clause opts: &SearchOptions - String { let esc = s: &str s.replace '\'', "''" ; ⋮---- c.push str &format! " AND v.kind = '{}'", esc kind ; ⋮---- c.push str &format! " AND v.category = '{}'", esc category ; ⋮---- c.push str &format! " AND v.tier = '{}'", esc tier ; ⋮---- c.push str &format! " AND v.created at = '{}'", esc since ; ⋮---- c.push str &format! " AND v.created at String - String { tags.iter .map t format! " AND v.tags LIKE '%\"{}\"%'", esc t .collect ⋮---- pub fn get entry conn: &Connection, id: &str - Result { ⋮---- .query row ⋮---- params!… 证据：`crates/cv-backends/src/queries.rs`
- **Cargo**（source_file）：package name = "cv-engine" version = "0.2.2" edition.workspace = true license.workspace = true description = "Context Vault engine contract: VaultEngine/Embedder traits, data types, and pure RRF search scoring." 证据：`crates/cv-engine/Cargo.toml`
- **Lib**（source_file）：use async trait::async trait; ⋮---- use serde json::Value; ⋮---- pub mod search; ⋮---- pub struct Entry { ⋮---- pub struct SaveInput { ⋮---- pub struct SaveOutput { ⋮---- pub struct SearchOptions { ⋮---- pub struct ScoredEntry { ⋮---- pub struct ListOptions { ⋮---- pub struct ReindexOptions { ⋮---- pub struct ReindexSummary { ⋮---- pub struct VaultStats { ⋮---- pub struct HealthStatus { ⋮---- pub trait Embedder: Send + Sync { ⋮---- pub trait VaultEngine: Send + Sync { 证据：`crates/cv-engine/src/lib.rs`
- **Search**（source_file）：use chrono::DateTime; use std::collections::HashMap; ⋮---- pub fn rrf fuse ⋮---- for idx, entry, rank in fts results.iter .enumerate { ⋮---- .entry entry.id.clone .or insert with ScoreComponents { entry: entry.clone , fts score: Some fts score , ⋮---- fts rank: Some rank , ⋮---- for idx, entry, rank in vec results.iter .enumerate { ⋮---- vec score: Some vec score , ⋮---- vec rank: Some rank , ⋮---- .vec score = Some vec score ; scores.get mut &entry.id .unwrap .vec rank = Some rank ; ⋮---- .into values .map components { let fused = components.fts score.unwrap or 0.0 + components.vec score.unwrap or 0.0 ⋮---- .get &components.entry.tier .copied .unwrap or 1.0 ; ⋮---- .as ref .and then h heat… 证据：`crates/cv-engine/src/search.rs`
- **Cargo**（source_file）：package name = "cv-ingest" version = "0.2.2" edition.workspace = true license.workspace = true description = "Context Vault ingest URL/project and file watcher." 证据：`crates/cv-ingest/Cargo.toml`
- **Mod**（source_file）：pub mod url convert; pub mod url; pub mod project; mod session signal extract; pub mod session transcript; pub mod session insights; 证据：`crates/cv-ingest/src/ingest/mod.rs`
- **Lib**（source_file）：pub mod ingest; pub mod watch; 证据：`crates/cv-ingest/src/lib.rs`
- **Mod**（source_file）：pub mod watcher; 证据：`crates/cv-ingest/src/watch/mod.rs`
- **Mod**（source_file）：use anyhow::Result; ⋮---- use std::time::SystemTime; ⋮---- mod lock; mod self write; ⋮---- use lock::WatcherLock; use self write::SelfWriteTracker; ⋮---- fn current time ms - u64 { ⋮---- .duration since SystemTime::UNIX EPOCH .map d d.as millis as u64 .unwrap or 0 ⋮---- fn is excluded rel path: &str - bool { if rel path.starts with '.' { ⋮---- .split '/' .any part part.starts with '.' excluded dirs.contains &part ⋮---- pub struct VaultWatcher { ⋮---- impl VaultWatcher { pub fn mark self write &self, file path: String { if let Ok mut tracker = self.self writes.lock { tracker.mark file path ; ⋮---- pub fn should process event &self, rel path: &str - bool { if is excluded rel path { ⋮---- if t… 证据：`crates/cv-ingest/src/watch/watcher/mod.rs`
- **Cargo**（source_file）：package name = "cv-lifecycle" version = "0.2.2" edition.workspace = true license.workspace = true description = "Context Vault lifecycle: summarize, compact, archive, assemble, consolidation, tier analysis." 证据：`crates/cv-lifecycle/Cargo.toml`
- **Lib**（source_file）：pub mod summarize; pub mod compact; pub mod archive; pub mod assemble; pub mod consolidation; pub mod tier analysis; 证据：`crates/cv-lifecycle/src/lib.rs`
- **Cargo**（source_file）：package name = "cv-schema" version = "0.2.2" edition.workspace = true license.workspace = true description = "Context Vault schema + multi-vault registry + indexing policy." 证据：`crates/cv-schema/Cargo.toml`
- **Indexing**（source_file）：pub struct IndexingConfig { ⋮---- impl Default for IndexingConfig { fn default - Self { ⋮---- exclude kinds: vec! , exclude categories: vec! , ⋮---- pub fn should index ⋮---- let c = config.unwrap or &default ; ⋮---- if !c.exclude kinds.is empty && c.exclude kinds.contains &kind.to string { ⋮---- if !c.exclude categories.is empty && c.exclude categories.contains &category.to string { ⋮---- mod tests; ⋮---- mod more tests; 证据：`crates/cv-schema/src/indexing.rs`
- **Lib**（source_file）：pub mod vaults; ⋮---- pub mod indexing; 证据：`crates/cv-schema/src/lib.rs`
- **Vaults**（source_file）：use std::collections::BTreeMap; ⋮---- use anyhow::Result; ⋮---- pub struct VaultEntry { ⋮---- pub struct VaultRegistry { ⋮---- pub fn registry path - PathBuf { ⋮---- .or else std::env::var "CONTEXT VAULT DATA DIR" .unwrap or else { ⋮---- .unwrap or else PathBuf::from "." .join ".context-mcp" .to string lossy .to string ⋮---- Path::new &data dir .join "vaults.json" ⋮---- pub fn load registry - Result { let path = registry path ; ⋮---- if !path.exists { return Ok VaultRegistry { active vault: "default".to string , ⋮---- Ok registry ⋮---- pub fn save registry registry: &VaultRegistry - Result { ⋮---- std::fs::create dir all path.parent .unwrap ?; ⋮---- Ok ⋮---- pub fn resolve active vault regi… 证据：`crates/cv-schema/src/vaults.rs`
- **Cargo**（source_file）：package name = "cv-vault" version = "0.2.2" edition.workspace = true license.workspace = true description = "Context Vault markdown persistence: frontmatter, formatters, file layout, and entry capture." 证据：`crates/cv-vault/Cargo.toml`
- **Entry File**（source_file）：use std::fs; use std::path::PathBuf; use anyhow::Result; ⋮---- use crate::capture::WriteEntryParams; ⋮---- fn short id lower id: &str - String { let start = id.len .saturating sub 8 ; id start.. .to lowercase ⋮---- fn resolve folder folder: &Option , meta: &Option - String { if let Some f = folder.as ref .filter s !s.is empty { return f.clone ; ⋮---- folder from meta meta .unwrap or default ⋮---- fn folder from meta meta: &Option - Option { let map = meta.as ref ?.as ref ?; let f = map.get "folder" ?.as str ?; if f.is empty { ⋮---- Some f.to string ⋮---- fn compute filename ⋮---- if is identity && identity key.as ref .map k !k.is empty .unwrap or false { let identity key = identity key.as r… 证据：`crates/cv-vault/src/entry_file.rs`
- **Frontmatter**（source_file）：use serde json::Value; ⋮---- pub fn format frontmatter fields: & String, Value - String { let mut lines = vec! "---".to string ; ⋮---- if let Some line = format fm field k, v { lines.push line ; ⋮---- lines.push "---".to string ; lines.join "\n" ⋮---- fn format fm field key: &str, value: &Value - Option { if value.is null { ⋮---- Some format! "{}: {}", key, format fm value value ⋮---- fn format fm value value: &Value - String { if let Some arr = value.as array { ⋮---- .iter .map item serde json::to string item .unwrap or else "null".to string .collect ; return format! " {} ", items.join ", " ; ⋮---- if let Some s = value.as str { if needs quoting s { return serde json::to string s .unwrap o… 证据：`crates/cv-vault/src/frontmatter.rs`
- **Lib**（source_file）：pub mod taxonomy; pub mod reorg; pub mod relocate; pub mod frontmatter; pub mod fm parse; pub mod md extract; pub mod formatters; pub mod files; pub mod entry file; pub mod capture; ⋮---- pub use frontmatter::format frontmatter; ⋮---- pub use md extract::parse entry from markdown; pub use formatters::format body; ⋮---- pub use entry file::write entry file; 证据：`crates/cv-vault/src/lib.rs`
- **Changelog**（documentation）：All notable changes to context-vault are documented here. 证据：`CHANGELOG.md`
- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。

## 宿主 AI 必须遵守的规则

- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `packages/local/README.md`, `packages/sdk/README.md`
- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `packages/local/README.md`, `packages/sdk/README.md`

## 用户开工前应该回答的问题

- 你准备在哪个宿主 AI 或本地环境中使用它？
- 你只是想先体验工作流，还是准备真实安装？
- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？

## 验收标准

- 所有能力声明都能回指到 evidence_refs 中的文件路径。
- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。
- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。

---

## Doramagic Context Augmentation

下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。

## Human Manual 骨架

使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。

宿主 AI 硬性规则：
- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。
- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。
- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。

- **项目概览与 Rust 工作区架构**：importance `high`
  - source_paths: Cargo.toml, README.md, crates/context-vault-core/src/lib.rs, crates/context-vault-cli/src/main.rs, docs/rust-distribution.md
- **MCP 工具、搜索引擎与 CLI 协议**：importance `high`
  - source_paths: crates/context-vault-core/src/mcp/mod.rs, crates/context-vault-core/src/mcp/handlers_read.rs, crates/context-vault-core/src/mcp/handlers_write.rs, crates/context-vault-core/src/mcp/tool_schemas/mod.rs, crates/cv-engine/src/search.rs
- **Vault 文件存储、摄入管线与生命周期管理**：importance `high`
  - source_paths: crates/cv-vault/src/lib.rs, crates/cv-vault/src/frontmatter.rs, crates/cv-vault/src/entry_file.rs, crates/cv-schema/src/indexing.rs, crates/cv-schema/src/vaults.rs
- **部署、运维与社区反馈路线图**：importance `high`
  - source_paths: install.sh, install.ps1, crates/context-vault-gateway/src/main.rs, crates/context-vault-gateway/src/handlers.rs, crates/context-vault-cli/src/cmd_setup.rs

## Repo Inspection Evidence / 源码检查证据

- repo_clone_verified: true
- repo_inspection_verified: true
- repo_commit: `8e8eb3ea5730681642b2406ca5d136ed8132ff59`
- inspected_files: `README.md`, `package.json`, `docs/archive/npm-rust-migration.md`, `docs/archive/rust-sqlite-vec-hooks.md`, `docs/bench-vault-fts.md`, `docs/claude-code-plugin.md`, `docs/development-workflow.md`, `docs/distribution/connect-in-2-minutes.md`, `docs/rust-distribution.md`, `packages/local/.mcp.json`, `packages/local/README.md`, `packages/local/assets/agent-rules.md`, `packages/local/assets/setup-prompt.md`, `packages/local/assets/skills/compile-context/skill.md`, `packages/local/assets/skills/vault-setup/skill.md`, `packages/local/bin/cli.js`, `packages/local/package.json`, `packages/sdk/README.md`, `packages/sdk/package.json`, `packages/sdk/src/hosted.ts`

宿主 AI 硬性规则：
- 没有 repo_clone_verified=true 时，不得声称已经读过源码。
- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。
- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。

## Doramagic Pitfall Constraints / 踩坑约束

这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。

### Constraint 1: 失败模式：installation: Explore FastMCP (Python) rewrite for MCP server

- Trigger: Developers should check this installation risk before relying on the project: Explore FastMCP (Python) rewrite for MCP server
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Explore FastMCP (Python) rewrite for MCP server. Context: Observed when using node, python
- Why it matters: Developers may fail before the first successful local run: Explore FastMCP (Python) rewrite for MCP server
- Evidence: failure_mode_cluster:github_issue | https://github.com/fellanH/context-vault/issues/191 | Explore FastMCP (Python) rewrite for MCP server
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 2: 失败模式：installation: v3.12.0

- Trigger: Developers should check this installation risk before relying on the project: v3.12.0
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v3.12.0. Context: Observed when using node
- Why it matters: Upgrade or migration may change expected behavior: v3.12.0
- Evidence: failure_mode_cluster:github_release | https://github.com/fellanH/context-vault/releases/tag/v3.12.0 | v3.12.0
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 3: 失败模式：installation: v3.13.0

- Trigger: Developers should check this installation risk before relying on the project: v3.13.0
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v3.13.0. Context: Observed when using node
- Why it matters: Upgrade or migration may change expected behavior: v3.13.0
- Evidence: failure_mode_cluster:github_release | https://github.com/fellanH/context-vault/releases/tag/v3.13.0 | v3.13.0
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 4: 失败模式：installation: v3.16.1

- Trigger: Developers should check this installation risk before relying on the project: v3.16.1
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v3.16.1. Context: Observed during installation or first-run setup.
- Why it matters: Upgrade or migration may change expected behavior: v3.16.1
- Evidence: failure_mode_cluster:github_release | https://github.com/fellanH/context-vault/releases/tag/v3.16.1 | v3.16.1
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 5: 失败模式：installation: v3: Clean local/hosted separation — pure engine core

- Trigger: Developers should check this installation risk before relying on the project: v3: Clean local/hosted separation — pure engine core
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v3: Clean local/hosted separation — pure engine core. Context: Observed when using node
- Why it matters: Developers may fail before the first successful local run: v3: Clean local/hosted separation — pure engine core
- Evidence: failure_mode_cluster:github_issue | https://github.com/fellanH/context-vault/issues/185 | v3: Clean local/hosted separation — pure engine core
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 6: 失败模式：installation: v4.0.0

- Trigger: Developers should check this installation risk before relying on the project: v4.0.0
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v4.0.0. Context: Observed when using node, windows
- Why it matters: Upgrade or migration may change expected behavior: v4.0.0
- Evidence: failure_mode_cluster:github_release | https://github.com/fellanH/context-vault/releases/tag/v4.0.0 | v4.0.0
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 7: 来源证据：Blog post: Building a Self-Improving Agent OS

- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Blog post: Building a Self-Improving Agent OS
- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Why it matters: 可能阻塞安装或首次运行。
- Evidence: community_evidence:github | https://github.com/fellanH/context-vault/issues/167 | 来源类型 github_issue 暴露的待验证使用条件。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 8: 来源证据：Explore FastMCP (Python) rewrite for MCP server

- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Explore FastMCP (Python) rewrite for MCP server
- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Why it matters: 可能阻塞安装或首次运行。
- Evidence: community_evidence:github | https://github.com/fellanH/context-vault/issues/191 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

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

- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Search semantic lane fails: insertVec is not a function (25k embeddings never materialize)
- Why it matters: 可能增加新用户试用和生产接入成本。
- Evidence: community_evidence:github | https://github.com/fellanH/context-vault/issues/202 | 来源类型 github_issue 暴露的待验证使用条件。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 10: 来源证据：Tiered storage: separate hot/cold databases for curated vs bulk data

- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Tiered storage: separate hot/cold databases for curated vs bulk data
- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Why it matters: 可能影响升级、迁移或版本选择。
- Evidence: community_evidence:github | https://github.com/fellanH/context-vault/issues/190 | 来源类型 github_issue 暴露的待验证使用条件。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。