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)         │   └───────────────────────┘        │
└───────────────┘   ┌───────────────────────┐        │
┌───────────────┐   │  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 모두 현재 팀 내에서 검색

• 리콜과 쓰기 분리: L1은 필요 시 도구로 조회; L0는 MemoryProxy가 투명하게 유입하거나 mcp-bridge가 명시적/Stop hook으로 기록

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 전용 클라이언트)

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 참조.

자동 저장(기본 커밋, 필요 시 리콜)

Claude Code / CodeBuddy(Stop hook)

mcp-bridge 자체는 도구 서버입니다: store_memory는 모델이 명시적으로 호출할 때만 기록됩니다. "대화 생성 완료 후 자동 전송"을 보장하기 위해 Stop hook으로 보완합니다:

• 스크립트: scripts/stop-memory-store.mjs——각 응답 종료 시 transcript에서 마지막 user/assistant 텍스트를 추출하여 MemoryCore /v3/conversation/add로 POST

• 구성: .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 텍스트를 /v3/conversation/add로 자동 POST

• 신원: team/agent/user + 게이트키는 DSH 로컬 구성(~/.dsh/profiles/web/cordis.patch.yml → mcp-agent-memory.env, 단일 사실 소스) 재사용, 환경 변수 오버라이드 지원

• task_id: 세션 헤더의 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(10초 폴링); --backfill로 과거 커밋 보충; --dry-run은 스캔만

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
├── 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

로컬 개발

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

상위 의존성

• TencentDB Agent Memory — 텐센트 오픈소스 4계층 장기 메모리 시스템(팀 에디션에 MemoryProxy + v3 isolation 포함)

License

MIT