ContextVault 实战教程：为 Claude Code 搭建持久化知识库
每次启动 Claude Code 新会话，你都要重新解释项目结构、重复之前的发现、重写已解决的方案——这种”失忆”不仅拖慢开发节奏，还让之前积累的经验白白浪费。ContextVault 正是为了解决这个问题而生的轻量级工具：它通过一套双层知识库系统，让 Claude Code 自动记住并复用你积累的知识，无需额外配置。
什么是 ContextVault？
ContextVault 是一个开源的（MIT 许可证）Claude Code 上下文管理系统，由开发者 Ahmad Zein 创建。它通过两级存储架构——全局知识库（~/.claude/vault/）和项目知识库（./.claude/vault/）——让 Claude Code 在不同会话之间保持记忆的一致性和连续性。
核心设计基于一个简单原则：只加载索引和一篇相关文档，每次会话最多约 200 行上下文，而不是将整个知识库全量灌入。这种”按需加载”策略在保持记忆优势的同时，大幅降低了 token 消耗。
安装：一行命令，两分钟搞定
ContextVault 的安装极其简单，支持 macOS、Linux、Windows（PowerShell/WSL/Git Bash）：
curl -sL https://ctx-vault.com/install | bash irm https://ctx-vault.com/install.ps1 | iex
安装后会自动：
- 创建
~/.claude/目录结构（含 CLAUDE.md、commands 目录、vault 目录） - 安装全局钩子（SessionStart + Stop + PostToolUse）
- 生成 23 个
/ctx-*斜杠命令 - 设置初始全局知识库索引
你还可以通过 npx 安装 MCP 服务端，让 ContextVault 兼容 Cursor、Windsurf、OpenCode、Cline 等支持 MCP 协议的工具：
npx contextvault-mcp
MCP 服务端提供了 23 个工具和 4 个资源，通过 npm 包 contextvault-mcp 分发。
初始化项目知识库
安装完成后，启动 Claude Code，用 /ctx-init 为每个项目单独初始化知识库：
/ctx-init
这个命令会：
- 创建/更新项目根目录的
CLAUDE.md，强制 Claude Code 使用 ContextVault - 建立
.claude/vault/目录和项目索引 - 安装项目级别的钩子（SessionStart + Stop）
- 添加 Git pre-commit 钩子，在提交时提醒记录文档
初始化后，运行 /ctx-status 可以检查全局和项目知识库的状态：
/ctx-status
输出会展示两个层级各自的文档数量、最后更新时间和状态。
23 个斜杠命令速览
ContextVault 提供了 23 个命令，可以按功能分为几组：
设置与状态
| 命令 | 用途 | 使用时机 |
|---|---|---|
/ctx-help | 显示所有命令及快速参考 | 忘记命令时 |
/ctx-status | 检查知识库状态 | 会话开始时 |
/ctx-init | 初始化项目知识库 | 首次进入新项目 |
/ctx-upgrade | 升级项目到最新版本 | ContextVault 更新后 |
/ctx-mode | 切换模式/配置限制 | 需要调整访问范围时 |
文档操作
| 命令 | 用途 |
|---|---|
/ctx-new [主题] | 创建新文档（自动路由到全局或项目） |
/ctx-doc | 快速记录刚完成的发现 |
/ctx-update [ID] | 更新已有文档 |
/ctx-read [ID] | 按 ID 读取文档 |
搜索与分享
| 命令 | 用途 |
|---|---|
/ctx-search [查询] | 跨所有索引搜索 |
/ctx-share [-upload] | 导出知识库为 ZIP（可上传生成分享链接） |
/ctx-import <路径> | 从 ZIP 导入知识库 |
会话与维护
| 命令 | 用途 |
|---|---|
/ctx-handoff | 生成会话交接摘要 |
/ctx-error | 捕获错误及解决方案 |
/ctx-decision | 记录架构决策及理由 |
/ctx-plan | 记录多步骤计划 |
/ctx-bootstrap | 自动扫描并记录代码库 |
/ctx-health | 诊断知识库健康问题 |
/ctx-archive | 归档过时文档 |
/ctx-review | 运行策展检查 |
实战工作流：从零开始使用
第一步：安装 + 日常使用
claude /ctx-status /ctx-search docker /ctx-doc
第二步：在项目中固化知识
假设你在做一个新的 Web 服务项目，找到了一种优雅的认证模式：
/ctx-init /ctx-new JWT 认证模式
下次在同项目启动 Claude Code 时，SessionStart 钩子会自动读取项目索引，Claude 会自动知道你的认证方案——无需你再解释。
第三步：团队分享
当团队需要共享项目知识时：
/ctx-share -all -upload
这会导出全局和项目两个层级的知识库并上传到 transfer.sh，生成一个 14 天有效的分享链接。接收方只需：
/ctx-import ./ctx_all_projectname_20260715_143022.zip
导入时如果遇到冲突，Claude 会提供四种处理选项：跳过、覆盖、合并、备份后覆盖。
三种模式与配置
/ctx-mode 命令可以切换知识库的访问模式：
- local（默认）：只访问项目知识库，适合专注的独立开发
- full：同时访问全局和项目，适合需要综合经验的任务
- global：只访问全局知识库，适合构建个人知识体系
你也可以调整各项限制：
/ctx-mode max-global 100 # 全局文档上限改为 100 /ctx-mode max-lines 150 # 单文档行数上限改为 150
自动钩子机制
ContextVault 的真正优势在于它的自动钩子（hooks）系统。安装后，Claude Code 的三个关键生命阶段会被自动拦截：
- SessionStart：会话开始时，Claude 自动读取两级知识库的索引
- PostToolUse：执行工具后，根据设置可触发非阻塞提醒（提醒记录文档）或阻断型提醒（完成大量工作但未记录时阻止继续）
- Stop：会话停止时，如果检测到有实质性的工作产出但未记录文档，会阻塞一次并提示记录
钩子有三种强制级别：light（关闭阻断）、balanced（8 次编辑后阻断）、strict（4 次编辑后阻断），通过 /ctx-mode enforcement [level] 配置。
MCP 集成
对于使用 Cursor、Windsurf、OpenCode 等 MCP 兼容工具的开发者，ContextVault 提供了独立的 MCP 服务端：
claude mcp add contextvault -- npx -y contextvault-mcp
或者手动添加到 MCP 配置中：
{
"mcpServers": {
"contextvault": {
"command": "npx",
"args": ["contextvault-mcp"]
}
}
}
MCP 版本提供了 23 个工具和 4 个资源，与 bash 安装版共享同一套 ~/.claude/vault/ 目录，零迁移成本。
小结
ContextVault 做了一件看似简单但极为实用的事情：让 Claude Code 记住它学过的东西。如果你每天多次启动 Claude Code 却反复解释同样的项目结构、工具配置和编码约定，那 ContextVault 花两分钟安装，之后每天节省的反复解释时间远比这两分钟多。
相关链接：