Claude Code Memory Layer（示例项目）

给 Claude Code 加分层长期记忆的完整方案：L0 对话 → L1 原子事实 → L2 场景 → L3 用户画像， 双路检索（BM25 中文关键词 + 向量），全部本地运行。

基于 TencentCloud/TencentDB-Agent-Memory（MIT）的独立 Gateway 模式，绕过 OpenClaw/Hermes 宿主，直接用 Claude Code hooks + MCP 接入。

Claude Code 会话
   ├─ SessionStart hook    → 检测 :8420，不通则自动拉起 Gateway
   ├─ UserPromptSubmit hook → 召回记忆（渐进式披露压缩后注入上下文）
   ├─ Stop hook             → 捕获本轮对话入库
   ├─ MCP server            → Claude 可主动检索（memory_search / memory_recall / ...）
        ↕ HTTP 127.0.0.1:8420
Memory Gateway（独立 Node 进程，SQLite + sqlite-vec + FTS5/jieba）

为什么值得抄

• 分层记忆：不存平铺向量堆。对话蒸馏为原子事实（L1）→ 场景块（L2）→ 用户画像（L3），顶层结论可下钻回原始证据
• 渐进式披露注入：每轮对话不注入完整记忆（token 成本高），而是注入"章节骨架 + 行级完整内容 + 下钻提示"——语义不腰斩、框架不丢失、细节按需查（见 hooks/hook_recall.py 的 _summarize）
• 零配置检索：SQLite + sqlite-vec + 中文 FTS（jieba 分词），无外部向量库

前置要求

依赖	版本
Node.js	≥ 22.16
Python	≥ 3.10（hooks 与 MCP server 用）
LLM API key	任意 OpenAI 兼容端点（提炼用，如 DeepSeek）
Embedding key	可选；不配则降级为纯关键词检索（如硅基流动 BAAI/bge-m3，1024 维）

部署步骤

1. 目录结构

<repo>
├── hooks\             # Claude Code hooks（Python）
├── mcp-server\        # MCP 工具（FastMCP）
└── start-gateway.bat  # Gateway 启动脚本

2. 安装 Gateway

# 安装 npm 包（目录结构要求: <repo>/tdai-memory-openclaw-plugin）
mkdir <repo>/tmp-install && cd <repo>/tmp-install
npm init -y --silent
npm install @tencentdb-agent-memory/memory-tencentdb@latest --omit=dev
cp -r node_modules/@tencentdb-agent-memory/memory-tencentdb <repo>/tdai-memory-openclaw-plugin
rm -rf <repo>/tmp-install
cd <repo>/tdai-memory-openclaw-plugin && npm install --omit=dev && npm install tsx

3. 配置 <repo>/memory-tdai/tdai-gateway.json

{
  "server": { "port": 8420, "host": "127.0.0.1" },
  "llm": {
    "baseUrl": "https://api.deepseek.com",
    "apiKey": "sk-你的key",
    "model": "deepseek-v4-flash"
  },
  "memory": {
    "capture": { "enabled": true, "l0l1RetentionDays": 90 },
    "extraction": { "enabled": true, "enableDedup": true, "maxMemoriesPerSession": 10 },
    "recall": { "enabled": true, "maxResults": 5, "scoreThreshold": 0.3, "strategy": "hybrid" },
    "embedding": {
      "enabled": true,
      "provider": "openai",
      "baseUrl": "https://api.siliconflow.cn/v1",
      "apiKey": "sk-你的key",
      "model": "Pro/BAAI/bge-m3",
      "dimensions": 1024,
      "sendDimensions": false
    }
  }
}

sendDimensions: false 必须关闭：bge-m3 不支持 Matryoshka 维度参数。embedding 段可整个去掉（降级为关键词检索）。

4. 启动并验证

start-gateway.bat        # 或 MEMORY_TENCENTDB_ROOT=<repo> start-gateway.bat
curl http://127.0.0.1:8420/health   # → {"status":"ok",...}

5. 注册 hooks（~/.claude/settings.json）

{
  "hooks": {
    "SessionStart": [
      { "matcher": "", "hooks": [
        { "type": "command", "command": "python <repo>/hooks/ensure_gateway.py", "timeout": 40 },
        { "type": "command", "command": "python <repo>/hooks/hook_recall.py full", "timeout": 20 }
      ]}
    ],
    "UserPromptSubmit": [
      { "matcher": "", "hooks": [
        { "type": "command", "command": "python <repo>/hooks/hook_recall.py", "timeout": 20 }
      ]}
    ],
    "Stop": [
      { "matcher": "", "hooks": [
        { "type": "command", "command": "python <repo>/hooks/hook_capture.py", "timeout": 30 }
      ]}
    ]
  }
}

（<repo> 换成你的实际路径；Windows 下用正斜杠。）

6. 注册 MCP server（可选，主动检索）

python -m venv mcp-server/.venv
mcp-server/.venv/Scripts/python.exe -m pip install fastmcp

~/.claude/settings.json 的 mcpServers：

{
  "mcpServers": {
    "memory-gateway": {
      "type": "stdio",
      "command": "<repo>/mcp-server/.venv/Scripts/python.exe",
      "args": ["<repo>/mcp-server/server.py"]
    }
  }
}

7. 灌入初始记忆

记忆库是空的，需要先喂数据（把已有笔记/文档作为对话捕获入库）：

# 示例：把一份笔记 capture 成一轮对话（L1 提炼由网关后台执行）
import json, urllib.request
body = json.dumps({
    "session_key": "note-001",
    "user_content": "用户笔记《学习计划》：每周 20 小时 Python 后端…",
    "assistant_content": "已收到。",
}, ensure_ascii=False).encode()
req = urllib.request.Request("http://127.0.0.1:8420/capture", data=body,
    headers={"Content-Type": "application/json"})
urllib.request.urlopen(req)

接口速查（Gateway）

接口	必填	用途
GET /health	—	健康检查
POST /capture	user_content, assistant_content, session_key	捕获一轮对话
POST /recall	query, session_key	召回（含画像上下文）
POST /search/memories	query	检索记忆（格式化结果）
POST /search/conversations	query	检索原始对话
POST /session/end	session_key	触发提炼

注意：/seed 是独立导入管道，结果不进实时检索库；实时入库请走 /capture。

设计说明

为什么注入用"结构压缩"而不是截断？ text[:600] 会把句子切成半截、把关键规则（往往在文末）整段丢掉。_summarize 的做法：标题骨架必保（框架不丢）、内容按行级截留（语义不腰斩）、场景路径压成文件名（下钻路标）、结尾提示用 MCP 工具查全文——这就是上游"渐进式披露"哲学的落地。

token 成本：完整画像 ~5700 字符 → 每轮注入 ~630 字符（约 11%），会话开始时注入一次完整版，平时按需下钻。

License

MIT（演示代码部分）；Gateway 本体为上游项目 TencentDB-Agent-Memory（MIT）。