claude-memory

面向 Claude Code 的记忆与项目跟踪。一个 MCP 服务器。

• 对所有过去的 Claude Code 会话记录进行语义搜索——新会话能回忆起旧会话，远超上下文窗口的限制

• 持久化笔记（remember）——按项目或全局

• 结构化跟踪：项目 → 里程碑 → 史诗 → 工单 → 待办事项，以路线图形式呈现

• 跟踪项嵌入到同一向量空间——工单会出现在语义搜索结果中

• 项目级系统提示词，存储在数据库中，可在会话开始时注入

技术栈：Voyage AI 嵌入模型 + Qdrant 向量数据库 + SQLite + FastMCP。 全部免费：Voyage 免费套餐轻松覆盖个人使用，Qdrant Cloud 免费套餐可容纳 100 万向量（或运行本地 docker）。运营成本为 $0。

设置

两个密钥：

• Voyage → https://dashboard.voyageai.com

• Qdrant → 在 https://cloud.qdrant.io 创建免费集群，或运行 docker run -p 6333:6333 qdrant/qdrant

git clone https://github.com/mathis-sperlich/claude-memory
cd claude-memory
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env
# fill VOYAGE_API_KEY, QDRANT_URL, QDRANT_API_KEY

将 ingest.py 中的 SCAN_PROJECTS 指向你的会话记录目录（Claude Code 会将它们写入 ~/.claude/projects/<encoded-project-dir>/*.jsonl）。

摄取

.venv/bin/python ingest.py --dry-run   # sanity-check chunking
.venv/bin/python ingest.py             # embed + upsert

幂等——重复运行只会嵌入新的分块。可安全地作为 cron 任务。每小时运行的 launchd 模板：launchd/com.mathis.claude-memory.plist（编辑路径，cp 到 ~/Library/LaunchAgents/，然后 launchctl load）。

从命令行测试检索：

.venv/bin/python query.py "how did the auth token refresh bug get fixed?"

结果不理想？调低 ingest.py 中的 MAX_CHUNK_CHARS，或尝试在 .env 中使用更大的 EMBED_MODEL，并用 --reset 重新摄取。

接入 Claude Code

~/.claude/settings.json：

{
  "mcpServers": {
    "claude-memory": {
      "command": "/path/to/claude-memory/.venv/bin/python",
      "args": ["/path/to/claude-memory/mcp_server.py"]
    }
  }
}

重启 Claude Code。完成——Claude 现在拥有 query_history、remember、跟踪工具和系统提示词工具。

工具

记忆

跟踪

层级：项目 → 里程碑（可选）→ 史诗 → 工单 → 待办事项。

status：open / in_progress / done。priority：P0–P3。

系统提示词

set_system_prompt(content, project=) / get_system_prompt(project=) / list_system_prompts() / delete_system_prompt(project=)。全局层 + 项目级层，读取时组合。存储在 tracking.db 中。未设置时回退到 docs/usage.md。

钩子（可选，确定性）

MCP 工具由模型决定何时触发。钩子始终触发。hooks/session_start.py 在每次会话开始时注入当前项目的未关闭工单 + 系统提示词：

{
  "hooks": {
    "SessionStart": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "/path/to/claude-memory/.venv/bin/python /path/to/claude-memory/hooks/session_start.py"
      }]
    }]
  }
}

远程访问（可选）

默认 = 本地 stdio，零网络。想从 claude.ai 或其他机器访问同一份记忆？HTTP 传输 + Cloudflare 隧道 + 带登录白名单的 GitHub OAuth：

.venv/bin/python mcp_server.py --transport http --port 8765

完整教程（包括 launchd 服务 + 自愈看门狗）：CLOUD_SETUP.md。

备注

• 隐私：Voyage 在嵌入时能看到文本（根据服务条款，不会用客户数据训练），Qdrant Cloud 存储向量和负载。如果两者都让你担心 → 使用本地 Qdrant + 本地嵌入器，代码不变。

• 停滞的嵌入请求由 VOYAGE_TIMEOUT / VOYAGE_MAX_RETRIES 环境变量限制（默认 20 秒 / 2 次）。