跳转至

开始使用 Claude-Mem

自动运行

Claude-Mem 安装后即可自动运行。无需手动干预！

完整流程

  1. 启动 Claude Code - 最近 10 个会话的上下文会自动出现
  2. 正常工作 - 每一次工具执行都会被捕获
  3. Claude 完成响应 - Stop hook 自动生成并保存摘要
  4. 下一次会话 - 之前的工作会出现在上下文中

捕获内容

每次 Claude 使用工具时，claude-mem 都会捕获它：

  • Read - 文件读取与内容访问
  • Write - 新建文件
  • Edit - 文件修改
  • Bash - 命令执行
  • Glob - 文件模式搜索
  • Grep - 内容搜索
  • 以及所有其他 Claude Code 工具

处理内容

Worker Service 处理工具观测记录并提取：

  • Title - 所发生事件的简要描述
  • Subtitle - 附加上下文
  • Narrative - 详细说明
  • Facts - 关键经验（以要点形式）
  • Concepts - 相关标签和分类
  • Type - 分类（decision、bugfix、feature 等）
  • Files - 读取或修改了哪些文件

会话摘要

当 Claude 完成响应（触发 Stop hook）时，会自动生成摘要，包含：

  • Request - 你的请求内容
  • Investigated - Claude 探索的内容
  • Learned - 关键发现与洞察
  • Completed - 已完成的工作
  • Next Steps - 后续步骤
  • Notes - 其他值得保留的内容

上下文注入

当你启动新的 Claude Code 会话时，SessionStart hook：

  1. 查询数据库中你项目里的近期观测记录（默认：50 条）
  2. 获取近期的会话摘要作为上下文
  3. 在带有会话标记的时间线上按时间顺序显示观测记录
  4. 仅当摘要是在最后一条观测记录之后生成时，才显示完整的摘要详情（Investigated、Learned、Completed、Next Steps、Notes）
  5. 将格式化后的上下文注入 Claude 的初始上下文

摘要显示逻辑：

最近一次摘要的完整详情会在上下文显示末尾出现，仅当该摘要在最近一条观测记录之后生成时才如此。这可以确保当摘要代表项目的最新状态时你能看到详情，但如果自上次摘要以来又捕获了新的观测记录，则不会显示。

例如：

  • ✅ 显示摘要：最后一条观测记录于下午 2:00，摘要于 2:05 生成 → 显示摘要详情
  • ❌ 隐藏摘要：摘要于下午 2:00 生成，新的观测记录于 2:05 → 隐藏摘要详情（已过期）

这样可以避免在新工作已被捕获但尚未汇总时显示过时的摘要。

这意味着 Claude 会“记住”之前会话中发生的事情！

手动命令（可选）

Worker 管理

Worker 会在首次触发 SessionStart hook 时自动启动，因此你通常不需要这些命令。它们用于诊断时很方便。

# Start worker service (optional - auto-starts automatically)
npm run worker:start

# Stop worker service
npm run worker:stop

# Restart worker service
npm run worker:restart

# View worker logs
npm run worker:logs

# Check worker status
npm run worker:status

测试

# Run all tests
npm test

# Test context injection
npm run test:context

# Verbose context test
npm run test:context:verbose

开发

# Build hooks and worker
npm run build

# Build only hooks
npm run build:hooks

# Publish to NPM (maintainers only)
npm run publish:npm

查看已存储的上下文

上下文存储在 SQLite 数据库中，位置为 ~/.claude-mem/claude-mem.db。

直接查询数据库：

# Open database
sqlite3 ~/.claude-mem/claude-mem.db

# View recent sessions
SELECT session_id, project, created_at, status
FROM sdk_sessions
ORDER BY created_at DESC
LIMIT 10;

# View session summaries
SELECT session_id, request, completed, learned
FROM session_summaries
ORDER BY created_at DESC
LIMIT 5;

# View observations for a session
SELECT tool_name, created_at
FROM observations
WHERE session_id = 'YOUR_SESSION_ID';

理解渐进式披露

上下文注入采用渐进式披露来高效使用 token：

第 1 层：索引显示（会话开始）

  • 显示观测记录标题及 token 成本估算
  • 在时间线上按时间顺序显示会话标记
  • 按文件对观测记录进行分组，以保持视觉清晰
  • 仅当摘要是在最后一条观测记录之后生成时，才显示完整摘要详情
  • 索引视图的 token 成本：约 50-200 tokens

第 2 层：按需详情（MCP 工具）

  • 自然提问：“我们修复了哪些 bug？”或“我们是如何实现 X 的？”
  • Claude 自动调用 MCP 搜索工具获取完整详情
  • 按概念、文件、类型或关键词搜索
  • 围绕特定观测记录的时间线上下文
  • 每条观测记录的获取成本：约 100-500 tokens
  • 使用三层工作流：search → timeline → get_observations

第 3 层：完美回忆（代码访问）

  • 需要时直接读取源代码文件
  • 访问原始记录和原始数据
  • 按需提供完整上下文

这确保了高效的 token 使用，同时在需要时仍能访问完整的历史记录。

多 Prompt 会话与 /clear 行为

Claude-Mem 支持跨越多个用户 Prompt 的会话：

  • prompt_counter：跟踪会话中的 Prompt 总数
  • prompt_number：标识会话中的特定 Prompt
  • 会话连续性：观测记录和摘要跨越多个 Prompt 进行关联

关于 /clear 的重要说明

当你使用 /clear 时，会话不会结束——它将继续以新的 Prompt 编号运行。这意味着：

  • ✅ 上下文会被重新注入：从近期会话重新注入（SessionStart hook 以 source: "clear" 触发）
  • ✅ 观测记录仍会被捕获，并添加到当前会话中
  • ✅ 会生成摘要：当 Claude 完成响应时（Stop hook 触发）

/clear 命令会清除 Claude 可见的对话上下文，并从近期会话中重新注入新的上下文，而底层会话会继续跟踪观测记录。

搜索你的历史记录

Claude-Mem 提供了用于查询项目历史的 MCP 工具。只需自然地提问：

"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"

Claude 会自动识别你的意图并调用 MCP 搜索工具，这些工具采用三层工作流（search → timeline → get_observations）以实现高效的 Token 使用。

后续步骤

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/claude-mem