TencentDB Agent Memory: Hierarchical AI Agent Memory Cuts Tokens 61%

Project Overview: Open-Source Memory System for Agent Experience Retention

TencentDB Agent Memory is an open-source agent memory system from Tencent Cloud's database team. It focuses on symbolic short-term memory + hierarchical long-term memory . The former compresses verbose tool logs into lightweight symbols during long tasks; the latter distills fragmented cross-session conversations into layered profiles and scenes instead of flat vector piles. The design principle: no undifferentiated history stacking, no irreversible compression summaries — "let the Agent remember what should be remembered, let humans focus on judgment, creation, and truly valuable work."

Benchmarks on OpenClaw host (continuous multi-task sessions simulating real long-horizon context pressure):

WideSearch pass rate 33% → 50%, token consumption −61.38%

SWE-bench 58.4% → 64.2%, token −33.09%

PersonaMem long-term memory benchmark 48% → 76%

Memory Hierarchy: L0→L3 Semantic Pyramid

Traditional memory systems shard data into vector stores, reducing recall to global fragment search without macro guidance. TencentDB Agent Memory makes layering the unified architectural paradigm. For long-term memory:

L0 Raw Log : full raw dialogue and event stream

L1 Atomic Memory : atomic facts, preferences, constraints, states

L2 Scene Block : clusters by project, topic, workflow

L3 Persona : stable user preference and service-style profile

Daily collaboration reads only top-layer profiles and scenes; details are drilled down layer by layer when needed. The same layering applies to short-term context (raw output → step summary → lightweight canvas) and skill generation (execution traces → scene patterns → reusable SOPs). Storage uses heterogeneous approach: bottom-layer facts, logs, traces persisted in database (local default SQLite + sqlite-vec) for full-text search; top-layer profiles, scenes, canvases saved as human-readable Markdown/Mermaid files — "bottom keeps evidence, top keeps structure."

Symbolic Short-Term Memory: Mermaid Canvas & Context Offloading

Main token cost in long tasks comes from verbose intermediate logs — search results, code snippets, error stacks. The solution: offload to external files , keeping only a Mermaid symbol graph with node_ids in context. The graph is precise enough for LLM parsing and human-readable. Agent reasons on the symbol graph; when detail verification is needed, it drills down via node_id to retrieve original text.

Reversible Drill-Down: Save Tokens Without Losing Evidence

Compression risk is losing original evidence. This project retains a deterministic chain from high-level summary back to bottom evidence — Persona / Canvas → Scenario / JSONL summary → L0 raw dialogue / refs original — linked by node_id and result_ref. Compression is reversible and traceable. This also provides white-box debuggability : key intermediates are readable files (L2 scene blocks as Markdown, L3 persona as persona.md, short-term canvas as Mermaid). Debugging follows "profile → scene → atomic fact → raw dialogue" layer by layer, no black-box vector scores.

Engineering Form: Memory Server & Shared Proxy for All Agents

Server-side comprises four services:

Memory Core (port 8420): memory read/write, auth, Skill/RAG data plane

Memory Hub dashboard (8125): team and memory asset management

Knowledge (8424): Wiki/CodeGraph service

Proxy (8096): LLM request proxy, Anthropic/OpenAI dual protocol

Deployment via deploy/global-images/start-all.sh interactive one-shot pull-up, prompting for two LLM parameter sets: memory group (internal distillation) and proxy group (upstream forwarding).

Integration model: one Proxy, protocol unchanged, zero-code integration — point agent's base URL to Proxy. No plugins, hooks, or MCP Server needed. Officially adapted for Claude Code, Codex, CodeBuddy, WorkBuddy, Hermes, OpenClaw, DeepSeek Harness, and Pi as a first-class implementation (MemoryProxy/src/agent-adapters/pi.ts).

Team dimension: Chat Memory, Skill, Wiki, CodeGraph registered as Memory Assets, assembled to specific agents via Memory Hub with Fixed Binding + ACL. Visibility levels: private / team / restricted / agent — team shares experience without sharing privacy.

Integrating with Pi Agent

Official Pi extension: @tencentdb-agent-memory/pi-tdai-client. It only routes Pi requests to Proxy with per-session x-conversation-id header; memory injection and capture happen entirely server-side (inject system prompt, capture L0 raw from response), client contains zero memory logic. Three-step integration:

# 1) One-click deploy Memory Server (interactive, needs Docker)
git clone https://github.com/TencentCloud/TencentDB-Agent-Memory.git
cd TencentDB-Agent-Memory/deploy/global-images
./start-all.sh
# Fill two LLM param sets (memory group / proxy group), script validates connectivity
# After start: dashboard http://localhost:8125, Proxy 127.0.0.1:8096
# admin key persisted in ./.admin-key

# 2) Create Team & Agent in dashboard (Task optional), get user API Key

# 3) Run Pi via TDAI provider
TDAI_USER_KEY=<user API Key> TDAI_TEAM_ID=<Team ID> TDAI_AGENT_ID=<Agent ID> \
pi -e ./MemoryCore/pi-plugin --provider tdai --model glm-5.2-vision

For persistent use, symlink extension into ~/.pi/agent/extensions/; Pi auto-loads on startup. Extension does two things: registers tdai provider (baseUrl → Proxy's /pi/default/v1, OpenAI-compatible, headers x-team-id / x-agent-id), and attaches x-conversation-id=pi-<session ID> per request. --model must match proxy group's configured forwarding model. Optional TDAI_TASK_ID narrows recall to a task; omitted = broad recall within agent's memory.

Verification: after a session, check Proxy logs for agentSource=pi and write-l0 entries. Three required vars ( TDAI_USER_KEY / TDAI_TEAM_ID / TDAI_AGENT_ID) missing → extension only warns, doesn't block Pi start. Use dashboard's "user API Key", not admin/gateway key.

Overall, this project stands out among open-source implementations for complete hierarchy division and high white-box transparency: layers are drillable, artifacts inspectable, and team scenarios include dashboard + ACL management. For teams building agents with Pi, "official extension + one Proxy" offers low integration cost, making it a strong candidate for experience retention evaluation.

• GitHub repo (bilingual README): https://github.com/TencentCloud/TencentDB-Agent-Memory • npm package @tencentdb-agent-memory/memory-tencentdb: https://www.npmjs.com/package/@tencentdb-agent-memory/memory-tencentdb • Tencent Cloud developer article: https://cloud.tencent.com/developer/article/2668579