Avijit07x/claude-db · 上手攻略

  • 仓库：Avijit07x/claude-db
  • 链接：https://github.com/Avijit07x/claude-db
  • 分类：工具 · Claude Code 记忆增强
  • 作者：Tom
  • 更新：2026-08-22

是什么

claude-db 为 Claude Code 提供持久化记忆层，解决每次新会话都要重新解释代码库背景的痛点。它在本地记录你与 Claude 的对话历史、代码理解结论和项目决策，新会话时自动注入上下文，Claude 无需再靠"考古式 grep"自行推断。

核心思路：capture（记录）+ recall（回填）+ code graph（代码图），三轨并行运作。数据默认存在本地 SQLite（~/.claude-memory/memory.db），不上云；也支持 MongoDB / PostgreSQL 等远程数据库。

⚠️ 注意：本工具是 Claude Code 的辅助插件，不是独立 CLI 应用，必须配合 Claude Code 使用。

解决什么问题

Claude Code 每次启动都是从零开始的——昨天你花了半小时解释的架构决策、已验证过的方案、未通过的替代路径，今天 Claude 全部遗忘。claude-db 用记忆注入替代重复解释：

  • 结论记忆：某次对话中确认的"为什么用这个适配器"直接写入，下次自动携带
  • 代码图：无需每次让 Claude 扫描，claude-db scan 一次性构建 symbol 索引，四种 MCP 查询模式随开随用
  • Token 节省：官方 benchmark 实测，每次 recall 约 180 tokens，命中跳过时平均返还 597 tokens（约等于 3.3 次 recall 成本），约 28% 的 prompts 可完全跳过 recall 步骤（npm run bench:ab 可在任意项目自行验证）

快速安装

前提

  • Node.js 22.5+（唯一硬依赖，SQLite 来自 Node 内置 node:sqlite，安装时无编译步骤）
  • Claude Code 已安装并在 PATH 中

安装命令

# 全局安装
npm install -g claude-db

# 进入目标项目
cd your-project

# 注册 hooks 与 MCP server（全局模式，所有项目共享）
claude-db install

# 或仅作用域当前项目（写入 .claude/settings.local.json + .mcp.json）
claude-db install --project

⚠️ --project 模式下 .mcp.json 包含机器本地路径，建议加入 .gitignore。

重启 Claude Code 后生效——无需额外配置，capture 和 recall 以 hook 形式自动运行。

核心用法

初始化代码图（可选但推荐）

# 构建当前项目的代码索引
claude-db scan

# 强制全量重建
claude-db scan --force

# 诊断：验证完整链路
claude-db doctor --deep

支持语言：TypeScript / TSX / JavaScript / Python / Go / Rust（parser 内置，无需额外依赖）。

记忆查询（CLI）

# 搜索历史记忆
claude-db search "为什么 capture 要读 transcript"

# 手动记录一条
claude-db remember "decision: 采用三适配器架构，原因见 issue #42"

# 查看状态
claude-db status

MCP 四模式（Claude Code 内直接用）

模式 用途 说明
text 全文搜索 实时 git grep，无需 scan 也能用
usages 符号引用 哪个文件定义/调用了某 symbol
explain 解释代码 基于代码图的结构化解释
path 路径查询 按条件找文件路径 
# 用 alias cdb 也行
cdb usages closeObservations
cdb explain capture

切换数据库

# 切换到 MongoDB（需先 npm install mongodb）
claude-db use "mongodb+srv://user:pass@cluster.mongodb.net/memory"

# 切换到 PostgreSQL（需先 npm install pg）
claude-db use "postgres://user:pass@host:5432/memory"

典型适用场景

  1. 大型代码库长期维护：跨多天、多模块的架构决策无需反复解释
  2. Code Review 对话流：在某次对话确认的设计结论，后续 PR 对话自动继承
  3. 多成员 Claude 协作：配合远程数据库（MongoDB/PostgreSQL），团队成员各自记忆可共享
  4. 代码考古：快速找到"当初为什么这样写"的结论，而非重新推理

坑与注意

  1. .mcp.json 要 gitignore：--project 模式下写入机器绝对路径，不应提交
  2. 首次 scan 有成本：大仓库首次全量扫描有 I/O 开销，后续增量（hash + diff）较便宜
  3. 无网络模式最安全：默认 SQLite，数据不离本机；切远程数据库前确认网络路径可信
  4. 隐私标记：node_modules / .env / secrets/ 自动排除；<private>...</private> 包裹的文本不记录；API Key 和 Token 自动脱敏
  5. Node 版本要求：最低 22.5，低于此版本 Node 内置 node:sqlite 不存在，安装会失败
  6. 语义搜索需升级：默认零依赖 embedder（关键词搜索）；npm install @xenova/transformers 后自动启用向量语义搜索

与同类对比

claude-db context7 continue (Continue)
记忆持久化 ✅ SQLite 本地 ❌ 临时 ❌ 临时
MCP 工具 ✅ 四模式 ❌ ✅
代码图 ✅ 内置 parser ❌ ✅（依赖 tree-sitter）
远程 DB ✅ MongoDB/PG ❌ ❌
Token 节省率 ✅ ~28% prompts ❌ ❌
Claude Code 专用 ✅ ❌ 更通用 ✅
部署门槛 低（npm 装完即用） 中（需配置） 中

一句话推荐：如果你每天用 Claude Code 处理同一个代码库超过 30 分钟，claude-db 是性价比最高的记忆基础设施——安装 3 条命令，坐等上下文自动累积。

数据来源

  • GitHub README：https://github.com/Avijit07x/claude-db
  • 官方文档：https://claude-db.vercel.app/docs
  • Benchmarks 页面：https://claude-db.vercel.app/docs/benchmarks
  • CLI 参考：https://claude-db.vercel.app/docs/cli