cavemem 是一款专为 AI 编程助手打造的跨 IDE 持久记忆工具。它让 Claude Code、Codex、Cursor 等编码助手在会话结束后仍能"记住"上下文，配合本快速上手教程，5 分钟即可完成 cavemem 安装与配置。全程本地运行、无需云端，是新手友好的 AI 编程记忆解决方案。

一、cavemem 是什么？给 AI 编程助手装上持久记忆 🪨

AI 编程助手有个通病：会话一结束，记忆就清零。cavemem 解决的正是这个问题——"why agent forget when agent can remember"。

它的工作原理非常直接：

session event → redact <private> → compress → SQLite + FTS5 ↑ MCP queries on demand

核心亮点一览：

• 跨会话持久记忆：Hooks 在会话边界自动捕获发生了什么，本地 SQLite 负责长期保存
• 压缩存储：确定性的 "caveman grammar" 将散文压缩约75% token，代码、路径、版本号逐字节保留
• 混合检索：SQLite FTS5 关键词 + 本地向量索引，配合可调权重排序
• 本地优先：默认零网络调用、零云端依赖，隐私可控
• Web 查看器：http://localhost:37777提供只读界面，用人类可读的方式浏览记忆

压缩效果直观示例（来自 README.md）：

Input: "The auth middleware throws a 401 when the session token expires; we should add a refresh path." Stored: "auth mw throws 401 @ session token expires. add refresh path." Viewed: "The auth middleware throws a 401 when session token expires. Add refresh path."

⚠️ 状态提示：cavemem 目前处于frozen（冻结维护）状态，一切功能仍可正常安装运行，但不再新增特性；其压缩记忆核心已并入后继项目 caveman。想深入了解压缩规格可看 docs/compression.md，整体架构见 docs/architecture.md。

二、一键安装步骤：最快 5 分钟完成配置 🚀

步骤 1：准备环境

只需满足两个前置条件：

• Node.js≥ 20
• 包管理器 npm（或 pnpm）

步骤 2：全局安装 CLI

npm install -g cavemem

步骤 3：为 IDE 注册 Hooks 与 MCP

cavemem install # 默认接入 Claude Code cavemem install --ide cursor # 支持 cursor | gemini-cli | opencode | codex | copilot | augment | antigravity | bob

一条命令即可，无需手动编辑任何配置文件。各 IDE 能力对照：

💡 用--ide参数为不同 IDE 分别安装；Cursor 等没有 Hooks 机制的 IDE 走 query-only 模式，详见 README.md 的能力矩阵。

步骤 4：验证安装状态

cavemem status

它会一次性展示：IDE 接线情况、数据库记录数、embedding 回填进度、worker 进程状态。query-only 的 IDE 会被明确标注(query-only)，避免"数据库永远是空的"的困惑。

步骤 5：打开记忆查看器

cavemem viewer

浏览器自动打开http://127.0.0.1:37777，以人类可读形式浏览所有会话记忆。首次打开无需任何配置——worker 会自动生成本地 token 注入页面。

三、核心功能体验：让 AI 检索自己的记忆 🔍

终端直接搜索

cavemem search "auth middleware" --limit 10

混合排序（BM25 + 向量余弦重排），默认返回 10 条。

AI 助手通过 MCP 查询

cavemem 以"渐进式披露"设计暴露 MCP 工具：先拿紧凑索引，再按需取全文，比一次性拉取全文省约10 倍 token。

推荐工作流：search拿索引 → 审阅 ID →get_observations取正文。完整契约见 docs/mcp.md，MCP 服务源码位于 apps/mcp-server/src/server.ts。

四、常用命令与配置速查 ⚙️

高频命令清单

关键配置项

配置文件位于~/.cavemem/settings.json（可用CAVEMEM_HOME环境变量重定向），完整示例见 examples/settings.example.json：

配置修改示例：

cavemem config set compression.intensity ultra

🔒 隐私设计：<private>...</private>内容在写入前被剥离；worker 只绑定127.0.0.1，/api/*需要本地 bearer token。

五、进阶技巧与 FAQ 💬

Q：如何把记忆迁移到另一台机器？

cavemem export backup.jsonl # 机器 A 导出 # 拷贝文件到机器 B： cavemem stop && cavemem import backup.jsonl && cavemem start

已存在的记录自动跳过，重复导入无副作用，详见 apps/cli/CHANGELOG.md。

Q：Windows 上 Claude Code 捕获不到记忆？

Claude Code 在 Windows 上也通过sh -c执行 Hooks。若Git\bin不在用户Path中，sh无法解析，捕获会静默失败。将C:\Program Files\Git\bin加入Path后用where.exe sh验证；cavemem doctor和cavemem install都会主动检查并给出警告。

Q：数据存在哪里？会上云吗？

全部在本地~/.cavemem（或CAVEMEM_HOME指定目录），无网络调用；仅当手动开启enrich.enabled并显式调用时才会产生外部请求。

Q：想彻底卸载？

cavemem uninstall --ide claude-code

Q：hooks 脚本长什么样？

每个生命周期事件对应一个极简 stub，位于 hooks-scripts/ 目录，例如 hooks-scripts/session-start.sh 只做一件事：exec cavemem hook run session-start。

总结

cavemem 是 AI 编程助手持久记忆的"小而美"方案：npm 一条命令安装、cavemem install一键接线、cavemem status即查状态——5 分钟即可让 Claude Code 等助手跨会话记住你的项目上下文。本地 SQLite + FTS5 + 向量混合检索，压缩存储省 75% token，完全离线运行。现在就去试试，让你的 AI 编程助手从此"过目不忘"吧！ 🪨