TencentDB Agent Memory: How to Give Your AI Agent Long-Term Memory Without Any External APIs — 7,800+ GitHub Stars

If you've ever built an AI agent that forgets everything between conversations, you know the pain. You re-explain your project structure, coding conventions, and preferences every single session. Your agent acts like it has amnesia — because, technically, it does.

Memory is the missing piece that separates a toy chatbot from a real productivity tool. And now, TencentDB Agent Memory — an open-source project that's already accumulated 7,800+ stars on GitHub — solves this problem elegantly, locally, and without any external API calls.

Let's break down exactly how it works, why the architecture matters, and how you can start using it today.

What Is TencentDB Agent Memory?

TencentDB Agent Memory is a TypeScript library that provides fully local long-term memory for AI agents through a 4-tier progressive pipeline. Unlike traditional RAG approaches that dump everything into a flat vector store, this system builds a semantic pyramid — organizing memory hierarchically, just like human cognition.

The project is built and maintained by Tencent Cloud and is designed around two core pillars:

• Symbolic Short-Term Memory — Offloads heavy tool logs into compact Mermaid symbol graphs, cutting token usage dramatically during active tasks.
• Layered Long-Term Memory — Distills fragmented conversations into structured personas and scenes, not flat vector piles.

The result? When integrated with agent frameworks, it cuts token usage by up to 61.38%, improves pass rates by 51.52% (relative), and raises PersonaMem accuracy from 48% to 76%.

The 4-Tier Memory Architecture Explained

Most memory systems today take conversations, chunk them into pieces, and throw them into a vector database. Retrieval becomes a blind search across disconnected fragments with no macro-level guidance. TencentDB Agent Memory takes a fundamentally different approach.

The Memory Pyramid: L0 → L1 → L2 → L3

The architecture builds a semantic pyramid with four layers:

• L0 — Conversation: Raw dialogue, stored as-is. This is your ground truth — the full, unedited record of every interaction.
• L1 — Atom: Atomic facts extracted from conversations. "User prefers TypeScript over JavaScript." "The project uses PostgreSQL on port 5432." Small, discrete, reusable pieces of knowledge.
• L2 — Scenario: Scene blocks that group related atoms into contexts. "When working on the HotelPlus API, the user follows these patterns..." These are situational memories.
• L3 — Persona: The user profile layer. Day-to-day preferences, working style, communication patterns. This is what the agent "knows" about you at a glance.

The genius here is progressive disclosure. The agent normally only needs the top-layer (Persona) to function well. It drills down to Scenarios when context matters, and to Atoms only when specific details are needed. The raw Conversation layer serves as an audit trail.

Why Layering Beats Flat Vector Stores

Think about how your own memory works. You don't remember every word of every conversation you've ever had. You remember patterns, preferences, and key facts — and you can drill down into specifics when needed. That's exactly what this architecture replicates.

A flat vector store treats "user likes dark mode" and "user's PostgreSQL runs on port 5432" as equally-weighted fragments. A layered system knows that "user prefers clean, minimal UIs" (Persona layer) is what matters 90% of the time, and the specific port number only matters when you're configuring a database.

Symbolic Short-Term Memory: The Mermaid Trick

During long tasks, the biggest token consumers aren't the conversations — they're the verbose intermediate logs. Search results, code outputs, error traces, tool call responses. These can easily consume hundreds of thousands of tokens in a single session.

TencentDB Agent Memory handles this with a clever symbolic approach:

1. Offload: Full tool outputs are written to external files (refs/*.md), removing them from the active context window.
2. Encode: Task state transitions are encoded in Mermaid diagram syntax — precise enough for LLMs to parse, concise enough for humans to read.
3. Inject: Only the lightweight Mermaid task map (a few hundred tokens) stays in the agent's context.
4. Recall: When the agent needs to verify a detail, it uses the node_id from the Mermaid graph to instantly retrieve the full raw text.

graph LR
    Log["Verbose Logs\n(100K+ tokens)"] -->|"1. Offload"| FS[("External Files\n(refs/*.md)")]
    Log -->|"2. Encode"| MMD["Mermaid Canvas\n(with node_id)"]
    MMD -->|"3. Inject ~200 tokens"| Agent(("Agent Context"))
    Agent -. "4. Recall via node_id" .-> FS

This is the secret behind the 61% token reduction. The agent sees a clean task map instead of pages of raw logs, and can always drill down when something goes wrong.

Real-World Example: A Coding Agent That Remembers Your Stack

Imagine you're building a full-stack app with Next.js, Prisma, and PostgreSQL. Over several sessions, you've told your AI agent:

• You prefer server components over client components
• Your database uses the judge0 schema
• You always use zod for validation
• Your deployment pipeline goes through Jenkins
• You like barrel files for exports

Without memory: Every new session, you re-explain all of this. The agent suggests client components, ignores your schema naming, and proposes validation approaches you've already rejected.

With TencentDB Agent Memory:

// After installation, memory works automatically
// Session 1: You explain your stack
// L0: Raw conversation stored
// L1: Atoms extracted — "prefers server components", "uses zod", "Jenkins CI/CD"
// L2: Scenario formed — "Full-stack development preferences"
// L3: Persona updated — "Clean architecture advocate, TypeScript-first"

// Session 5: Agent already knows
// Agent sees Persona layer → generates server components by default
// Agent needs DB detail → drills to Atom layer → uses "judge0" schema
// No re-explanation needed

The agent doesn't just "remember facts" — it understands your patterns. When you start a new project, it already knows you'll want barrel files, server components, and zod validation. It's not searching a vector store; it's applying a learned persona.

Full Traceability: No Lossy Compression

One of the biggest concerns with memory systems is: what if it summarizes wrong? Traditional approaches use lossy compression — once you summarize a conversation, the original details are gone.

TencentDB Agent Memory solves this with deterministic drill-down paths:

Top Layer (Persona/Canvas)
    ↓ drill down
Mid Layer (Scenario/JSONL index)
    ↓ drill down
Bottom Layer (L0 Conversation / raw refs)

Every abstraction maintains a link back to its source. If the Persona says "user prefers TypeScript," you can trace that back through the Scenario and Atom layers all the way to the original conversation where you said it. Nothing is lost; everything is compressed with a return path.

This is huge for enterprise use cases where auditability matters. You're not trusting a black-box summary — you have full provenance for every piece of knowledge the agent claims to "remember."

Installation: 2 Commands and You're Running

The system defaults to a local SQLite + sqlite-vec backend, meaning zero infrastructure setup. For OpenClaw users, it's a two-liner:

# Install the plugin
openclaw plugins install @tencentdb-agent-memory/memory-tencentdb

# Restart to activate
openclaw gateway restart

For Hermes agent users, there's a Docker one-liner:

docker run -d \
  --name hermes-memory \
  -p 8420:8420 \
  -e MODEL_API_KEY="your-api-key" \
  -v hermes_data:/opt/data \
  hermes-memory

Once enabled, it automatically handles conversation capture, memory extraction, scene aggregation, persona generation, and recall — all before the next turn.

Benchmark Results That Matter

These aren't isolated single-turn benchmarks. They're measured over continuous long-horizon sessions — for example, SWE-bench runs 50 consecutive tasks per session to simulate real-world context accumulation:

• WideSearch (Short-term): Success rate from 33% → 50% (+51.52%), tokens from 221M → 86M (−61.38%)
• SWE-bench (Short-term): Success rate from 58.4% → 64.2% (+9.93%), tokens from 3,474M → 2,375M (−33.09%)
• AA-LCR (Short-term): Success rate from 44% → 47.5% (+7.95%), tokens from 112M → 77M (−30.98%)
• PersonaMem (Long-term): Accuracy from 48% → 76% (+59%)

The pattern is clear: less tokens, better results. The agent performs better when it's not drowning in context.

Key Benefits

• 61% token reduction — Save money on API costs while improving performance
• 51% better task success — Agents that remember make fewer mistakes
• Zero external APIs — Everything runs locally with SQLite
• Full traceability — Every memory links back to its source conversation
• Drop-in plugin — Works with OpenClaw and Hermes out of the box
• Open source — Full transparency, community-driven development
• Hierarchical memory — Mimics human cognition, not flat vector dumps
• Long-horizon ready — Tested over 50+ consecutive tasks per session

Frequently Asked Questions

What exactly is TencentDB Agent Memory?

TencentDB Agent Memory is an open-source TypeScript library by Tencent Cloud that provides hierarchical long-term memory for AI agents. It uses a 4-tier progressive pipeline (Conversation → Atom → Scenario → Persona) to organize memory like human cognition, running entirely locally with zero external API dependencies.

How does it reduce token usage by 61%?

It uses "symbolic short-term memory" — verbose tool outputs (search results, code, error traces) are offloaded to external files, and only a compact Mermaid task graph stays in the agent's context window. The agent can always retrieve full details via node_id references when needed.

Do I need a database server to use it?

No. The default backend is local SQLite with sqlite-vec for vector operations. You don't need PostgreSQL, Redis, or any external database. Everything runs on your machine. For production scale, you can configure TencentDB or other backends.

Which AI agent frameworks does it support?

Currently, it supports OpenClaw (as a plugin) and Hermes Agent (via Docker or manual installation). The architecture is framework-agnostic, so more integrations are expected as the community grows.

What happens if the memory system summarizes something wrong?

Every memory maintains a deterministic drill-down path back to the original conversation. If a Persona-level summary seems off, you can trace it through Scenario and Atom layers all the way to the raw L0 conversation. Nothing is irreversibly compressed — full provenance is always preserved.

Is it suitable for production use?

Yes. It's built by Tencent Cloud and tested over long-horizon sessions with 50+ consecutive tasks. The benchmarks show consistent improvements across multiple evaluation frameworks. The local-first architecture also means no external service dependencies that could cause downtime.

How does it compare to traditional RAG memory?

Traditional RAG flattens everything into a vector store and retrieves by similarity. TencentDB Agent Memory builds a hierarchical pyramid where the agent uses high-level personas for most interactions and drills down only when specifics are needed. This is more efficient, more accurate, and more human-like than blind vector search.