TencentAgentMemoryBridge

围绕 TencentDB Agent Memory 团队版 v2.0.0（feat/server_team 分支）构建的记忆桥梁——把 4 层长期记忆能力（L0 对话 → L1 原子事实 → L2 场景 → L3 画像）接入不同的 AI Agent 平台。

不造轮子：记忆引擎能力全部由 TencentDB Agent Memory 提供，本仓库只做协议桥接。团队版引入 MemoryProxy（透明 LLM 代理）与 v3 isolation（team / agent / user 三元组），旧 /capture /recall 与 sender 隔离已被取代。

权威设计见 docs/team-edition-role-model.md（三角色模型 + v3 接入）。

架构

┌───────────────┐   ┌───────────────────────────────┐
│ Claude Code / │──▶│  MemoryProxy（团队版，透明 LLM）│──▶ MemoryCore /v3/*
│ WorkBuddy     │   │  URL /{agent}/{spaceId}/v1/*   │
└───────────────┘   │  header 预选 x-team-id/x-agent-id │
┌───────────────┐   └───────────────────────────────┘
│ MCP-only 客户端 │──▶┌───────────────────────┐        │
│ (Claude Code, │   │  mcp-bridge (v3 重写)   │────────▶ MemoryCore /v3/*
│  CodeBuddy,   │   │  配置 TEAM/AGENT/USER 三元组 │
│  DSH, Octop)  │   └───────────────────────┘        │
└───────────────┘   ┌───────────────────────┐        │
┌───────────────┐   │  openclaw-plugin(官方)  │────────▶ MemoryCore /v3/*
│ OpenClaw      │──▶│  静态配置 teamId/agentId│
└───────────────┘   └───────────────────────┘

核心原则

• v3 隔离三元组：一切数据面读写都带 team_id + agent_id + user_id（可选 task_id 做项目级区分），取代旧 sender 白名单

• task_id 与身份严格分离：agent_id（agt-*）是平台身份、跨项目不变；task_id 是项目级标签（目录名或显式 TASK_ID），拒绝 agt-/team-/usr-/sk- 前缀（mcp-bridge ≥ 0.4.0 启动即校验），杜绝身份 id 被当 task_id 用

• 单团队作用域：/v3/atomic/search、/v3/core/read、/v3/scenario/ls 都在当前 team 内检索

• 召回与写入分离：L1 按需经工具查询；L0 由 MemoryProxy 透明回流或 mcp-bridge 显式/守护脚本写入

Related MCP server: engram

接入方式

1. MemoryProxy（透明，推荐）

Claude Code / WorkBuddy 把 ANTHROPIC_BASE_URL（或 OpenAI 兼容端点）指向 MemoryProxy，记忆自动处理：

• capture：每轮对话自动回流 L0，无需显式工具调用

• inject：L2/L3 自动注入 system prompt

• 身份：URL 路径 /{agent}/{spaceId} + x-team-id / x-agent-id / x-task-id header 预选（或首轮表单选择）

前置：需完成团队版部署与迁移步骤（见 role-model §10）。

2. mcp-bridge（MCP-only 客户端）

MCP 服务器，把记忆工具调用直连 MemoryCore Gateway（团队版 /v3/* 数据面）。配置见 docs/mcp-bridge-v3.md。

// .claude/settings.local.json
{
  "mcpServers": {
    "agent-memory": {
      "command": "npx",
      "args": ["-y", "tencent-agent-memory-mcp-bridge"],
      "env": {
        "MEMORY_ENDPOINT": "https://memory.kuai-private.top",
        "API_KEY": "<gate-api-key>",
        "SERVICE_ID": "default",
        "TEAM_ID": "<team-id>",
        "AGENT_ID": "<agent-id>",
        "USER_ID": "<user-id>"
      }
    }
  }
}

⚠️ 真实 key 只放本机 .env 或 MCP settings env，不要提交到仓库。

3. OpenClaw（官方插件）

用上游官方 openclaw-plugin，静态配置 teamId / agentId / userId。见 docs/openclaw-plugin-v3.md。

4. DeepSeek Harness（DSH 原生 MCP）

DSH 通过原生 MCP 客户端插件（@deepseek-ai/dsh-mcp-client）连接 mcp-bridge，模型看到 mcp__agent-memory__* 工具。配置模板见 examples/deepseek-harness/cordis.patch.yml，完整指南见 docs/deepseek-harness-v3.md。

5. Octop（自定义 MCP 连接器）

Octop 用原生自定义 MCP 连接器（stdio）连 mcp-bridge，模型看到 agent-memory_* 工具；default_open: true 让 Dashboard / IM / Cron 每轮自动带工具。入库由 scripts/octop-memory-autostore.mjs 守护兜底（读 ~/.octop/octop.db 的 thread_messages）。配置模板见 examples/octop/，完整指南见 docs/octop-v3.md。

自动入库（默认提交、按需取回）

Claude Code / CodeBuddy（Stop hook）

mcp-bridge 本身是工具服务器：store_memory 只有模型显式调用才写入。为保证"对话生成完成后自动发送"，通过 Stop hook 兜底：

• 脚本：scripts/stop-memory-store.mjs——每次响应结束，从 transcript 提取最后一段 user/assistant 文本，POST 到 MemoryCore /v3/conversation/add

• 配置：.claude/settings.local.json 的 hooks.Stop（凭据从同一文件的 mcpServers.agent-memory.env 读取，单一事实源）

• 去重：按 session_id + 最后 assistant 时间戳写 .claude/.memory-store-state.json，防止 /compact、/resume 重复入库

• 不阻塞：写入失败仅记 stderr、exit 0，不拖慢对话

"hooks": {
  "Stop": [{ "hooks": [{ "type": "command", "command": "node scripts/stop-memory-store.mjs", "timeout": 30 }] }]
}

DeepSeek Harness（守护脚本）

DSH 没有 Stop hook，用独立守护脚本 scripts/dsh-memory-autostore.mjs 实现同样语义：

• 原理：监听 ~/.dsh/sessions/**/session.jsonl.zstd（DSH 会话日志，zstd 多帧 JSONL），每个回合结束（turn/end 事件）自动把该轮 user + assistant 文本 POST 到 /v3/conversation/add

• 身份：team/agent/user + 门禁 key 复用 DSH 本机配置（~/.dsh/profiles/web/cordis.patch.yml → mcp-agent-memory.env，单一事实源），支持环境变量覆盖

• task_id：从会话 header 的 cwd 自动派生（项目目录名），每项目独立

• 去重：按 session_id + turn 写 ~/.dsh/.dsh-memory-autostore-state.json；启动建基线不回溯历史，只提交之后新增轮次

• 用法：部署时先 node scripts/dsh-memory-autostore.mjs --baseline-only（把现有轮次记为基线，不回溯提交历史），之后 node scripts/dsh-memory-autostore.mjs --once（增量提交，配合计划任务）或常驻 node scripts/dsh-memory-autostore.mjs（10s 轮询）；--backfill 补提交历史；--dry-run 只扫描

Octop（守护脚本）

Octop 也没有 Stop hook，用 scripts/octop-memory-autostore.mjs 实现同样语义：

• 原理：读 harness 会话日志 ~/.octop/workspaces/<ws>/<sysfiles>/sessions/YYYY-MM-DD.jsonl（agent runtime 自己写，覆盖每次真实对话），把「user → 该轮最后一条有文本的 assistant」配对成一只 turn，POST 到 /v3/conversation/add

• 一轮闭合规则：等到下一条 user 出现、或源文件静默超过 OCTOP_AUTOSTORE_IDLE_FLUSH（默认 120s）才提交，避免把"先说一句 → 调工具 → 再说结论"里的前言当成最终回复

• 备选源：--source sqlite → 读 ~/.octop/octop.db 的 thread_messages（只读连接）。注意那是客户端投影，Dashboard 新开对话的轮次可能不落库

• 身份：env 优先，其次 MEMORY_CONFIG（默认 ~/.config/octop-memory/agent-memory.json，chmod 600）

• session_id：默认 thread_id（一对话一 session）；OCTOP_AUTOSTORE_SESSION_MODE=source 改按通道归并

• task_id：TASK_ID（默认 octop）；与 agent_id 严格分离

• 去重：按 thread_id 记游标（最后提交的 assistant 时间戳）写 ~/.octop/.octop-memory-autostore-state.json；游标带源前缀、失败不推进；state.json.lock 进程锁防并发重复

• 用法：与 DSH 版一致（--baseline-only / --once / --backfill / --dry-run），systemd 用户级单元模板见 examples/octop/octop-memory-autostore.service

MCP 工具

end_session 已移除：v3 中 session 只是客户端 key，无独立关闭端点。 _context（≥0.4.0）：每个工具结果回显当前隔离域 {team_id, agent_id, user_id, task_id}，模型/用户可据此确认 agent 与 task 未混用。

项目结构

tencent-agent-memory-bridge/
├── packages/
│   ├── mcp-bridge/           # MCP Server → MemoryCore /v3/* 直连（v3 重写）
│   └── bridge-server/        # 已退役（旧 sender 代理层，仅保留历史参考）
├── scripts/
│   ├── stop-memory-store.mjs # Stop hook：响应结束后自动写 L0（Claude Code）
│   ├── stop-memory-store-codebuddy.mjs # CodeBuddy Stop hook
│   ├── dsh-memory-autostore.mjs   # DSH 守护：读会话日志，按轮次自动写 L0
│   └── octop-memory-autostore.mjs # Octop 守护：读 octop.db，按轮次自动写 L0
├── examples/
│   ├── codebuddy/            # CodeBuddy MCP 安装/更新指南
│   ├── claude-code/          # Claude Code 配置指南
│   ├── deepseek-harness/     # DeepSeek Harness cordis.patch.yml 模板
│   └── octop/                # Octop 自定义 MCP 连接器 + systemd 守护模板
├── docs/
│   ├── team-edition-role-model.md   # 团队版三角色模型（权威）
│   ├── mcp-bridge-v3.md             # mcp-bridge v3 使用指南
│   ├── deepseek-harness-v3.md       # DeepSeek Harness 接入指南
│   ├── octop-v3.md                  # Octop（agent harness）接入指南
│   ├── openclaw-plugin-v3.md        # OpenClaw 官方插件接入
│   └── design-overview.md           # 旧架构设计（已过时，仅参考）
├── CLAUDE.md                 # 项目指令
└── package.json

本地开发

pnpm install
pnpm --filter mcp-bridge build
pnpm --filter mcp-bridge test

上游依赖

• TencentDB Agent Memory — 腾讯开源的 4 层长期记忆系统（团队版含 MemoryProxy + v3 isolation）

License

MIT