TencentAgentMemoryBridge

Eine Gedächtnisbrücke, die um TencentDB Agent Memory Team Edition v2.0.0 (Branch feat/server_team) herum gebaut ist – sie verbindet die 4-stufigen Langzeitgedächtnisfähigkeiten (L0-Dialog → L1-Atomfakten → L2-Szenen → L3-Personas) mit verschiedenen AI-Agent-Plattformen.

Kein Rad neu erfinden: Die Fähigkeiten der Gedächtnis-Engine werden vollständig von TencentDB Agent Memory bereitgestellt; dieses Repository dient nur als Protokollbrücke. Die Team Edition führt MemoryProxy (transparenter LLM-Proxy) und v3-Isolation (Triple team / agent / user) ein; die alten /capture- und /recall-Endpunkte sowie die Sender-Isolation wurden ersetzt.

Autoritatives Design siehe docs/team-edition-role-model.md (Drei-Rollen-Modell + v3-Anbindung).

Architektur

┌───────────────┐   ┌───────────────────────────────┐
│ 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│
└───────────────┘   └───────────────────────┘

Kernprinzipien

• v3-Isolationstriple: Alle Lese-/Schreibvorgänge auf der Datenebene tragen team_id + agent_id + user_id (optional task_id für projektbezogene Unterscheidung) und ersetzen die alte Sender-Whitelist.

• Strikte Trennung von task\_id und Identität: agent_id (agt-*) ist die Plattformidentität und bleibt projektübergreifend unverändert; task_id ist ein projektbezogenes Label (Verzeichnisname oder explizite TASK_ID). Präfixe agt-/team-/usr-/sk- werden abgelehnt (mcp-bridge ≥ 0.4.0 prüft dies beim Start), um zu verhindern, dass Identitäts-IDs als task_id verwendet werden.

• Einzel-Team-Scope: /v3/atomic/search, /v3/core/read und /v3/scenario/ls suchen alle innerhalb des aktuellen Teams.

• Trennung von Abruf und Schreiben: L1 wird bei Bedarf über Tools abgefragt; L0 wird entweder transparent über MemoryProxy zurückgeführt oder explizit über mcp-bridge bzw. den Stop-Hook geschrieben.

Related MCP server: engram

Drei Integrationsmöglichkeiten

1. MemoryProxy (transparent, empfohlen)

Claude Code / WorkBuddy verweisen mit ANTHROPIC_BASE_URL (oder einem OpenAI-kompatiblen Endpunkt) auf MemoryProxy; die Gedächtnisverwaltung erfolgt automatisch:

• capture: Jede Gesprächsrunde fließt automatisch in L0 zurück, ohne expliziten Tool-Aufruf.

• inject: L2/L3 werden automatisch in den System-Prompt injiziert.

• Identität: URL-Pfad /{agent}/{spaceId} + Header-Vorauswahl über x-team-id / x-agent-id / x-task-id (oder Auswahl im ersten Formularschritt).

Voraussetzung: Die Bereitstellung und die Migrationsschritte der Team Edition müssen abgeschlossen sein (siehe role-model §10).

2. mcp-bridge (MCP-only-Clients)

MCP-Server, der Gedächtnis-Tool-Aufrufe direkt mit dem MemoryCore-Gateway verbindet (Datenebene /v3/* der Team Edition). Konfiguration siehe 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>"
      }
    }
  }
}

⚠️ Echte Schlüssel nur in die lokale .env oder die MCP-Settings-Env ablegen, nicht ins Repository committen.

3. OpenClaw (offizielles Plugin)

Das offizielle Upstream-Plugin openclaw-plugin verwenden und teamId / agentId / userId statisch konfigurieren. Siehe docs/openclaw-plugin-v3.md.

4. DeepSeek Harness (DSH-natives MCP)

DSH verbindet sich über das native MCP-Client-Plugin (@deepseek-ai/dsh-mcp-client) mit mcp-bridge; das Modell sieht die Tools mcp__agent-memory__*. Konfigurationsvorlage siehe examples/deepseek-harness/cordis.patch.yml, vollständige Anleitung siehe docs/deepseek-harness-v3.md.

Automatische Speicherung (standardmäßig übermitteln, bei Bedarf abrufen)

Claude Code / CodeBuddy (Stop-Hook)

mcp-bridge selbst ist ein Tool-Server: store_memory schreibt nur, wenn das Modell es explizit aufruft. Um sicherzustellen, dass „nach Abschluss der Antwortgenerierung automatisch gesendet wird", dient der Stop-Hook als Fallback:

• Skript: scripts/stop-memory-store.mjs – bei jedem Antwortende den letzten User/Assistant-Textabschnitt aus dem Transkript extrahieren und per POST an MemoryCore /v3/conversation/add senden.

• Konfiguration: hooks.Stop in .claude/settings.local.json (Anmeldedaten werden aus mcpServers.agent-memory.env in derselben Datei gelesen, Single Source of Truth).

• Deduplizierung: Anhand von session_id + letztem Assistant-Zeitstempel wird .claude/.memory-store-state.json geschrieben, um doppelte Speicherung bei /compact und /resume zu verhindern.

• Nicht blockierend: Bei Schreibfehlern wird nur stderr protokolliert und mit Exit 0 beendet; das Gespräch wird nicht verlangsamt.

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

DeepSeek Harness (Daemon-Skript)

DSH hat keinen Stop-Hook; ein eigenständiges Daemon-Skript scripts/dsh-memory-autostore.mjs implementiert dieselbe Semantik:

• Prinzip: Überwacht ~/.dsh/sessions/**/session.jsonl.zstd (DSH-Sitzungsprotokolle, zstd-Mehrframe-JSONL). Am Ende jeder Runde (turn/end-Ereignis) werden die User- und Assistant-Texte dieser Runde automatisch per POST an /v3/conversation/add gesendet.

• Identität: team/agent/user + Zugangsschlüssel werden aus der lokalen DSH-Konfiguration wiederverwendet (~/.dsh/profiles/web/cordis.patch.yml → mcp-agent-memory.env, Single Source of Truth); Umgebungsvariablen können überschreiben.

• task_id: Wird automatisch aus dem cwd im Sitzungs-Header abgeleitet (Projektverzeichnisname); pro Projekt unabhängig.

• Deduplizierung: Schreibt ~/.dsh/.dsh-memory-autostore-state.json anhand von session_id + turn; beim Start wird eine Basislinie erstellt, ohne die Historie zurückzuverfolgen – nur neu hinzugekommene Runden werden übermittelt.

• Verwendung: Bei der Bereitstellung zuerst node scripts/dsh-memory-autostore.mjs --baseline-only ausführen (bestehende Runden als Basislinie markieren, ohne die Historie nachträglich zu übermitteln), danach node scripts/dsh-memory-autostore.mjs --once (inkrementelle Übermittlung, z. B. über einen geplanten Task) oder dauerhaft node scripts/dsh-memory-autostore.mjs (10-s-Polling); --backfill übermittelt die Historie nachträglich; --dry-run scannt nur.

MCP-Tools

end_session wurde entfernt: In v3 ist session nur ein Client-Key; es gibt keinen separaten Endpunkt zum Schließen. _context (≥0.4.0): Jedes Tool-Ergebnis spiegelt den aktuellen Isolationsbereich {team_id, agent_id, user_id, task_id} wider; Modell/Benutzer können daran erkennen, dass Agent und Task nicht vermischt wurden.

Projektstruktur

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

Lokale Entwicklung

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

Upstream-Abhängigkeiten

• TencentDB Agent Memory — das von Tencent Open Source bereitgestellte 4-stufige Langzeitgedächtnissystem (Team Edition enthält MemoryProxy + v3-Isolation).

Lizenz

MIT