TencentAgentMemoryBridge

Puente de memoria construido alrededor de TencentDB Agent Memory edición de equipo v2.0.0 (rama feat/server_team) — que conecta las capacidades de memoria a largo plazo de 4 capas (L0 conversación → L1 hechos atómicos → L2 escenarios → L3 perfil) a diferentes plataformas de agentes de IA.

No reinventamos la rueda: todas las capacidades del motor de memoria las proporciona TencentDB Agent Memory; este repositorio solo hace de puente de protocolo. La edición de equipo introduce MemoryProxy (proxy LLM transparente) y aislamiento v3 (triplete team / agent / user); los antiguos /capture /recall y el aislamiento por remitente han sido reemplazados.

El diseño de referencia se encuentra en docs/team-edition-role-model.md (modelo de tres roles + integración v3).

Arquitectura

┌───────────────┐   ┌───────────────────────────────┐
│ 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)         │   └───────────────────────┘        │
└───────────────┘   ┌───────────────────────┐        │
┌───────────────┐   │  openclaw-plugin(官方)  │────────▶ MemoryCore /v3/*
│ OpenClaw      │──▶│  静态配置 teamId/agentId│
└───────────────┘   └───────────────────────┘

Principios fundamentales

• Triplete de aislamiento v3: todas las lecturas/escrituras de la capa de datos llevan team_id + agent_id + user_id (opcional task_id para distinción a nivel de proyecto), reemplazando la antigua lista blanca de remitentes.

• Separación estricta entre task_id e identidad: agent_id (agt-*) es la identidad de la plataforma, invariable entre proyectos; task_id es una etiqueta a nivel de proyecto (nombre de directorio o TASK_ID explícito), rechaza los prefijos agt-/team-/usr-/sk- (mcp-bridge ≥ 0.4.0 valida al inicio), evitando que los IDs de identidad se usen como task_id.

• Ámbito de un solo equipo: /v3/atomic/search, /v3/core/read, /v3/scenario/ls buscan dentro del equipo actual.

• Separación de recuperación y escritura: L1 se consulta bajo demanda mediante herramientas; L0 se refluye de forma transparente por MemoryProxy o se escribe explícitamente por mcp-bridge / Stop hook.

Related MCP server: engram

Tres formas de integración

1. MemoryProxy (transparente, recomendado)

Claude Code / WorkBuddy apuntan ANTHROPIC_BASE_URL (o un endpoint compatible con OpenAI) a MemoryProxy, y la memoria se procesa automáticamente:

• capture: cada turno de conversación refluye automáticamente a L0, sin necesidad de llamadas explícitas a herramientas.

• inject: L2/L3 se inyectan automáticamente en el system prompt.

• Identidad: ruta de URL /{agent}/{spaceId} + preselección por headers x-team-id / x-agent-id / x-task-id (o selección en el primer formulario).

Requisito previo: completar los pasos de despliegue y migración de la edición de equipo (ver role-model §10).

2. mcp-bridge (clientes solo MCP)

Servidor MCP que conecta directamente las llamadas a herramientas de memoria con MemoryCore Gateway (plano de datos /v3/* de la edición de equipo). Configuración en 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>"
      }
    }
  }
}

⚠️ Las claves reales solo deben estar en el .env local o en el entorno de configuración de MCP, no las subas al repositorio.

3. OpenClaw (plugin oficial)

Usa el openclaw-plugin oficial upstream, con configuración estática teamId / agentId / userId. Ver docs/openclaw-plugin-v3.md.

4. DeepSeek Harness (MCP nativo de DSH)

DSH se conecta a mcp-bridge mediante el plugin de cliente MCP nativo (@deepseek-ai/dsh-mcp-client), y el modelo ve las herramientas mcp__agent-memory__*. La plantilla de configuración está en examples/deepseek-harness/cordis.patch.yml, y la guía completa en docs/deepseek-harness-v3.md.

Almacenamiento automático (envío por defecto, recuperación bajo demanda)

Claude Code / CodeBuddy (Stop hook)

mcp-bridge en sí es un servidor de herramientas: store_memory solo escribe cuando el modelo lo llama explícitamente. Para garantizar el "envío automático al finalizar la generación de la conversación", se usa un Stop hook como respaldo:

• Script: scripts/stop-memory-store.mjs — al final de cada respuesta, extrae el último fragmento de texto user/assistant del transcript y lo envía por POST a MemoryCore /v3/conversation/add.

• Configuración: hooks.Stop en .claude/settings.local.json (las credenciales se leen de mcpServers.agent-memory.env en el mismo archivo, fuente única de verdad).

• Deduplicación: escribe .claude/.memory-store-state.json según session_id + timestamp del último assistant, para evitar duplicados en /compact y /resume.

• No bloquea: si la escritura falla, solo registra en stderr y sale con 0, sin ralentizar la conversación.

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

DeepSeek Harness (script daemon)

DSH no tiene Stop hook; se usa un script daemon independiente scripts/dsh-memory-autostore.mjs para implementar la misma semántica:

• Principio: escucha ~/.dsh/sessions/**/session.jsonl.zstd (registros de sesión de DSH, JSONL multiframe zstd), y al final de cada turno (evento turn/end) envía automáticamente el texto user + assistant de ese turno por POST a /v3/conversation/add.

• Identidad: team/agent/user + clave de acceso reutilizan la configuración local de DSH (~/.dsh/profiles/web/cordis.patch.yml → mcp-agent-memory.env, fuente única de verdad), con soporte para sobrescribir mediante variables de entorno.

• task_id: se deriva automáticamente del cwd en el header de la sesión (nombre del directorio del proyecto), independiente por proyecto.

• Deduplicación: escribe ~/.dsh/.dsh-memory-autostore-state.json según session_id + turn; al iniciar se crea una línea base sin retroceder en el historial, solo se envían los turnos nuevos posteriores.

• Uso: al desplegar, primero node scripts/dsh-memory-autostore.mjs --baseline-only (marca los turnos existentes como línea base, sin retroceder en el historial), luego node scripts/dsh-memory-autostore.mjs --once (envío incremental, con tareas programadas) o en modo residente node scripts/dsh-memory-autostore.mjs (sondeo cada 10s); --backfill para reenviar el historial; --dry-run solo escanea.

Herramientas MCP

end_session ha sido eliminado: en v3, session es solo una clave de cliente, sin endpoint de cierre independiente. _context (≥0.4.0): cada resultado de herramienta refleja el dominio de aislamiento actual {team_id, agent_id, user_id, task_id}, para que el modelo/usuario pueda confirmar que agent y task no se mezclan.

Estructura del proyecto

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
├── examples/
│   ├── codebuddy/            # CodeBuddy MCP 安装/更新指南
│   ├── claude-code/          # Claude Code 配置指南
│   └── deepseek-harness/     # DeepSeek Harness cordis.patch.yml 模板
├── docs/
│   ├── team-edition-role-model.md   # 团队版三角色模型（权威）
│   ├── mcp-bridge-v3.md             # mcp-bridge v3 使用指南
│   ├── deepseek-harness-v3.md       # DeepSeek Harness 接入指南
│   ├── openclaw-plugin-v3.md        # OpenClaw 官方插件接入
│   └── design-overview.md           # 旧架构设计（已过时，仅参考）
├── CLAUDE.md                 # 项目指令
└── package.json

Desarrollo local

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

Dependencias upstream

• TencentDB Agent Memory — sistema de memoria a largo plazo de 4 capas de código abierto de Tencent (la edición de equipo incluye MemoryProxy + aislamiento v3)

Licencia

MIT