Claude-Mem 实战指南跨会话持久化记忆系统的安装、原理与配置附印尼语 README 全解析【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-memClaude-Mem 是一套为 Claude Code 等 AI 编码代理构建的持久化记忆压缩系统它自动捕获会话中的工具使用观察observations、用 AI 生成语义摘要并在后续会话中把相关上下文重新注入让代理在项目知识上保持跨会话连续性。本文基于仓库中的印尼语版官方文档 docs/i18n/README.id.md 与主 README.md 编写覆盖全部安装方式、三大 MCP 搜索工具的两层工作流、settings.json与模式/语言配置并结合 plugin/hooks/hooks.json、src/storage/sqlite/schema.ts、src/servers/mcp-server.ts 等源码印证其底层实现。读完本文你将能够独立完成 Claude-Mem 的安装与配置理解其 Hook 生命周期与记忆检索的 token 优化机制。快速开始三种安装方式文档给出的标准安装命令只有一个npx claude-mem install此外还支持为不同 IDE/平台安装# 为 OpenCode 安装 npx claude-mem install --ide opencode # 为 Antigravity CLI 安装 npx claude-mem install --ide antigravity # 或在 Claude Code 的插件市场中安装 /plugin marketplace add thedotmack/claude-mem /plugin install claude-mem安装完成后重启 Claude Code之前会话的上下文会自动出现在新会话中。文档中有一条非常关键、容易被忽视的警告Claude-Mem 虽然也发布在 npm 上但npm install -g claude-mem只安装SDK/库本身—— 它不会注册插件 hooks也不会配置 worker 服务。始终通过npx claude-mem install或上面的/plugin命令安装。这条警告可以直接在仓库源码中得到印证plugin/目录才是真正被 Claude Code 加载的插件载体其中 plugin/hooks/hooks.json 定义了全部生命周期 Hookplugin/scripts/ 下的bun-runner.js、worker-service.cjs等脚本才是运行时真正执行的文件而 npm 全局安装只会带来库代码不带这些注册逻辑。OpenClaw Gateway 安装文档还提供了面向 OpenClaw 网关的一键安装curl -fsSL https://install.cmem.ai/openclaw.sh | bash该安装器负责处理依赖、插件配置、AI 提供商配置、worker 启动以及向 Telegram、Discord、Slack 等的可选实时观察流推送。仓库中的 openclaw/ 目录包含了对应的插件实现openclaw.plugin.json、install.shclaude-mem-cursor/ 与 claude-mem-grok-bot/ 则分别是面向 Cursor 和 Grok Bot 的适配包均附带mcp.json与技能定义。文档列出的核心特性包括持久化记忆—— 上下文跨会话保留渐进式披露Progressive Disclosure—— 带 token 成本可见性的分层记忆检索基于技能Skill的搜索—— 用 mem-search 技能以自然语言查询项目历史Web Viewer UI—— 在启动时打印的 worker URL 上实时查看记忆流隐私控制—— 用private标签将敏感内容排除在存储之外上下文配置—— 精细控制注入哪些上下文自动化运行—— 无需人工干预引用Citations—— 通过 worker API 用 ID 引用过去的观察或在 Web Viewer 中查看全部系统工作原理六个核心组件文档How It Works一节列出的核心组件如下5 个生命周期 Hook—— SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd共 6 个 hook 脚本Smart Install—— 带缓存的依赖检查器pre-hook 脚本不是生命周期 HookWorker Service—— 由 Bun 管理的本地 HTTP API带 Web Viewer UI 和搜索端点SQLite 数据库—— 存储会话、观察、摘要mem-search Skill—— 支持渐进式披露的自然语言查询Chroma 向量数据库—— 语义 关键词混合搜索用于智能上下文检索这些组件在源码中的落点可以逐一确认plugin/hooks/hooks.json 中确实注册了Setup、SessionStart、UserPromptSubmit、PostToolUse、PreToolUse、Stop等事件。其中SessionStartmatcher 为startup|clear|compact依次执行worker-service.cjs start拉起 worker和worker-service.cjs hook claude-code context注入上下文PostToolUsematcher 为*即任意工具异步执行hook claude-code observation捕获工具使用观察Stop异步执行hook claude-code summarize在会话结束时生成摘要。每个 hook 命令还内嵌了一段 shell 逻辑用于在插件缓存目录~/.claude/plugins/cache/thedotmack/claude-mem/中按版本号排序挑选最新插件副本并跳过带.orphaned_at标记的孤儿副本在 Windows Git Bash 下还会经cygpath -w转换路径——这正是文档中 Smart Install 所说的带缓存的依赖检查在 pre-hook 阶段的工作方式。plugin/scripts/worker-service.cjs 是 worker 服务的启动入口通过bun-runner.js在 Bun 下运行与文档Worker Service 由 Bun 管理的描述一致。SQLite 存储层位于 src/storage/sqlite/schema.ts、index.ts、memory-items.ts等。在 src/storage/sqlite/schema.ts 中可以看到CREATE VIRTUAL TABLE ... memory_items_fts USING fts5(...)印证了文档SQLite 存储会话、观察、摘要以及使用 FTS5 全文索引的说明。向量检索部分文档提到 Chroma 向量数据库用于混合搜索src/services/worker/ 下包含 worker 的搜索管理实现且系统要求一节明确uvPython 包管理器是为向量搜索而自动安装的依赖与 Chroma 的运行前提吻合。MCP 搜索工具3 层 token 高效工作流Claude-Mem 通过4 个 MCP 工具提供智能记忆搜索worker 模式下的三件套 server 运行时的observation_search遵循3 层 token 高效工作流search—— 获取带 ID 的紧凑索引约 50-100 token/条timeline—— 获取有趣结果周围的时间线上下文get_observations—— 仅对已筛选的 ID 拉取完整详情约 500-1000 token/条工作方式是先用search拿到结果索引 → 用timeline查看特定观察前后发生了什么 → 用get_observations批量拉取相关 ID 的完整详情。文档给出的量化收益是先筛选后取详情约 10 倍 token 节省。文档给出的示例用法// 步骤 1搜索获取索引 search(queryauthentication bug, typebugfix, limit10) // 步骤 2审阅索引识别相关 ID如 #123、#456 // 步骤 3拉取完整详情 get_observations(ids[123, 456])源码侧可以验证这套约定。src/servers/mcp-server.ts 中注册了search、timeline、get_observations等工具工具描述里直接写明1. search(query) → Get index with IDs (~50-100 tokens/result) 2. timeline(anchorID) → Get context around interesting results 3. get_observations([IDs]) → Fetch full details ONLY for filtered IDs并强制提示对 2 个及以上 ID ALWAYS batch必须批量。search请求最终调用 worker 的/api/search端点timeline调用/api/timeline另外源码中还定义了observation_searchserver 运行时专用走 PG 的 GIN tsvector 索引与smart_searchtree-sitter AST 符号搜索两个附加工具对应插件包 plugin/package.json 中大量tree-sitter-*语言解析依赖。配置settings.json 与模式/语言设置基础配置文档说明配置统一管理在~/.claude-mem/settings.json首次运行自动创建并填充默认值可配置项包括 AI 模型、worker 端口、数据目录、日志级别、上下文注入设置等。模式与语言配置CLAUDE_MEM_MODEClaude-Mem 通过CLAUDE_MEM_MODE设置支持多种工作流模式和语言。该选项同时控制两件事工作流行为如 code、chill、investigation生成观察observations时使用的语言配置方法是编辑~/.claude-mem/settings.json{ CLAUDE_MEM_MODE: code--zh }模式定义在plugin/modes/目录中。要在本地查看所有可用模式ls ~/.claude/plugins/marketplaces/thedotmack/plugin/modes/文档列出的模式模式说明code默认英文模式code--zh简体中文模式code--ja日文模式语言模式遵循code--[lang]命名模式[lang]为 ISO 639-1 语言代码如zh中文、ja日文、es西班牙文。文档特别注明code--zh已内置无需额外安装或更新插件。修改模式后需重启 Claude Code 才能生效。这一点在仓库中可以直接验证plugin/modes/ 目录下存在code.json以及code--zh.json、code--ja.json、code--es.json、code--ar.json等 30 余个模式文件还有code--chill.json、email-investigation.json、law-study.json等工作流变体。以 plugin/modes/code.json 为例其中定义了observation_typesbugfix、feature、refactor、change、discovery、decision、security_alert、security_note等每个类型带有 id、标签、描述和 emoji——这正是 MCPsearch工具按typebugfix过滤时所用的类型体系。系统要求与平台注意事项文档列出的系统要求Node.js20.0.0 或更高版本Claude Code支持插件的最新版本BunJavaScript 运行时与进程管理器缺失时自动安装uv用于向量搜索的 Python 包管理器缺失时自动安装SQLite 3持久化存储已捆绑仓库 plugin/package.json 的engines字段给出了更严格的插件运行时要求node 20.12.0、bun 1.0.0可以作为精确的适用前提参考。Windows 配置注意事项如果看到类似下面的错误npm : The term npm is not recognized as the name of a cmdlet请确认已安装 Node.js 和 npm 并将其加入 PATH。从 Node.js 官网下载最新安装器安装安装后重启终端。分支策略、开发与问题排查发布分支文档Release Branches一节说明稳定版从main分支发布并推送到 npmcore-dev与community-edge是从源码运行的分支分别用于早期可靠性修复和社区集成。Claude-Mem 从三个分支出货main稳定版、core-dev、community-edge只有main会发布到 npm其余从源码运行。仓库中 plans/2026-07-05-three-release-branches.md 记录了该策略的规划背景。开发与贡献贡献流程为Fork 仓库 → 创建功能分支 → 带测试地修改代码 → 更新文档 → 提交 Pull Request。仓库自带完善的测试体系例如 tests/ 下覆盖 hooks 生命周期tests/hook-lifecycle.test.ts、SQLite 存储tests/sqlite/、MCP 工具可见性tests/servers/mcp-tool-schemas.test.ts、worker 服务tests/services/等与上述架构各组件一一对应。问题排查与 Bug 报告文档建议遇到问题时直接向 Claude 描述troubleshoot 技能会自动诊断并给出修复方案。仓库还内置了自动 bug 报告生成器cd ~/.claude/plugins/marketplaces/thedotmack npm run bug-report对应实现位于 scripts/bug-report/cli.ts、collector.ts。许可与支持Claude-Mem 采用 Apache License 2.0。文档解释了选择 Apache-2.0 的原因持久化的代理记忆应易于嵌入开发工具、本地代理、MCP 服务器、企业系统、机器人技术栈和生产级 agent 框架。完整条款见 LICENSE许可范围与开放/商业边界见 docs/license.md 和 docs/ip-boundary.md。关于 Ragtime 的说明ragtime/目录同样采用 Apache License 2.0详见 ragtime/LICENSE。支持渠道方面文档指向仓库内 docs/ 文档目录、官方 Issues、官方 X 账号 Claude_Memory 与官方 Discord文档作者为 Alex Newmanthedotmack。小结Claude-Mem 的核心价值链路是Hook 捕获 → AI 压缩 → SQLite/Chroma 双存储 → 三层 MCP 检索 → 上下文回注。docs/i18n/README.id.md 作为官方印尼语版 README 完整覆盖了安装、原理、搜索工具、配置与许可这些主干内容本文在此骨架上补充了 plugin/hooks/hooks.json 中各 Hook 的实际触发时机与子命令、src/servers/mcp-server.ts 中 MCP 工具的真实实现约定、plugin/modes/ 的模式文件结构以及 src/storage/sqlite/schema.ts 中的 FTS5 索引证据帮助读者从会安装进阶到看得懂实现。【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考