Local four-tier memory for long-horizon agents

Long-horizon agents still die the same death: context fills with tool dumps, search HTML, stack traces, and half-remembered preferences, then quality and cost both collapse. Most "memory" products answer that with another vector store and a summarizer. TencentDB Agent Memory takes a different bet: memory is a progressive pipeline, not a bag of embeddings, and the whole thing can run locally with zero external memory APIs.

That is not marketing fluff. The design rejects two common failure modes at once, irreversible lossy summarization and flat fragment retrieval, and replaces them with layered structure you can audit on disk. For teams already on OpenClaw or Hermes, the numbers are strong enough to try in real multi-session work. For everyone else, the architecture is the part worth stealing, even if the plugin path is still narrow.

Flat stores do not scale with session length

Classic agent memory shreds turns into chunks, embeds them, and hopes cosine similarity will reconstruct intent later. That works for "what did the user say about dark mode?" It fails when the agent needs macro structure: which step produced this error, which SOP applies to this repo, which user preference is binding vs one-off.

Tencent's pitch is blunt. Formation and recall should both be hierarchical. Short-term overload and long-term personalization are different problems. Dumping both into one vector index turns recall into a blind search across disconnected fragments with no top-level map.

The project also draws a hard line against pure history accumulation. Re-pasting every tool log into the window is not memory. It is billable noise. The goal is progressive disclosure: keep evidence, expose structure, and only drill down when the agent actually needs the raw payload.

Two pillars: layering and symbolization

The long-term stack is an L0–L3 pyramid:

• L0 Conversation: raw dialogue and execution traces
• L1 Atom: extracted atomic facts and preferences
• L2 Scenario: clustered scene blocks (coding, research, workflow patterns)
• L3 Persona: durable user/profile layer for day-to-day defaults

Upper layers answer fast questions. Lower layers stay available as evidence. That is the opposite of a single summary that cannot be unwound.

Short-term memory uses a parallel layering trick. Raw tool outputs land in archive files (refs/*.md). Step-level summaries live in JSONL. The live context surface is a compact Mermaid canvas that encodes steps, dependencies, and state as symbols the model can reason over without re-ingesting every API blob. When something breaks, the agent follows a node_id back down instead of replaying the whole log.

Storage matches the layers. Bottom evidence (facts, logs, traces) sits in a database for full-text and vector retrieval. Default path is local SQLite plus sqlite-vec. Top artifacts (personas, scenes, canvases) are human-readable Markdown. Optional Tencent Cloud VectorDB (TCVDB) is available when you outgrow laptop scale, but the default story is zero external memory dependency.

The important product claim is traceability. Compression is not a one-way hash. There is a deterministic path from persona or canvas node back to ground-truth dialogue and tool output. That matters the moment you have to debug a wrong preference or a failed multi-step task in production-adjacent workflows.

What the OpenClaw numbers actually show

Project-reported results on continuous long-horizon sessions (not single-turn evals) are the reason this repo is getting attention:

xychart-beta
  title "Token reduction with plugin (relative %)"
  x-axis [WideSearch, SWE-bench, AA-LCR]
  y-axis "% fewer tokens" 0 --> 70
  bar [61.38, 33.09, 30.98]

Read these carefully. SWE-bench here runs 50 consecutive tasks per session to simulate context accumulation pressure, not the usual isolated-issue setup. The biggest win is WideSearch token burn, which is exactly where verbose tool and web payloads dominate. PersonaMem's jump is the long-term personalization argument in one number: layered profiles beat flat recall for user-consistent behavior.

Caveat remains: these are the project's own measurements on OpenClaw with the plugin. Treat them as directionally useful and re-measure on your task mix. Still, relative gains of that size on multi-session runs are rarer than another "we added RAG" blog post.

Against peers, the comparison that matters is shape, not star count. Lightweight fact stores such as Mem0 optimize personalized snippets at scale, often with external vector infrastructure. TencentDB Agent Memory is aimed at long tasks plus cross-session structure, with short-term offload as a first-class feature. If you need multi-tenant memory platforms, a broader SDK ecosystem wins. If you need auditable long-horizon sessions on a supported agent host, the layered local path is more interesting.

What adoption looks like in practice

Today the practical path is plugin-first, not framework-agnostic. Native integration targets OpenClaw and Hermes. Generic adapters are described as planned, not shipping everywhere.

For OpenClaw-style installs, the loop is intentionally short:

openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
openclaw gateway restart
openclaw plugins list

Zero-config local mode is the default. Config lives in the host agent JSON (for example enabling memory-tencentdb and optionally tuning capture retention, L1 extraction/dedup, L1→L2→L3 pipeline schedule, recall policy, and embeddings). Memory artifacts land under a host memory directory as inspectable files: L0 JSONL dialogues, L1 atoms, L2 scenarios, L3 profile Markdown, plus Mermaid canvases for active tasks.

That white-box layout is the real developer feature. When the agent "remembers" the wrong SOP, you open files instead of spelunking an opaque vector collection. When token burn spikes, you can see whether offload is failing to keep tool blobs out of the live window.

Trade-offs to budget for:

• Host lock-in for now. If you are not on OpenClaw/Hermes, you are either waiting on adapters or lifting the layering ideas into your own runtime.
• SQLite scale. Local mode is fine for modest session memory (rough guide from project commentary: under ~100k entries before considering TCVDB migration).
• Extraction cost. L1 atomization and higher-layer distillation still consume model calls. Token savings show up over multi-step sessions, not free magic on turn one.
• Ops surface. Progressive pipelines mean schedules, retention, dedup, and recall policy. You gain control; you also own knobs.

Where it fits well: multi-day coding agents that should retain repo conventions; research agents that offload web dumps while keeping an investigation graph; workflow agents that need resumable state; support-style agents that carry preferences across sessions without re-prompting the user every morning.

Where it is weaker: greenfield multi-framework platforms that need one memory SDK everywhere, or pure multi-tenant SaaS memory where a managed fact store already exists.

Worth your attention if the host fits

TencentDB Agent Memory is a genuine architectural shift relative to flat agent RAG, not just another wrapper around embeddings. Symbolic short-term canvases plus L0–L3 long-term layering attack the actual failure modes of long-horizon agents: context bloat and uninspectable personalization. The OpenClaw numbers make the cost/quality case concrete, and MIT-licensed local defaults remove the "send every conversation to a hosted memory API" objection.

The limiter is ecosystem width, not the core idea. If you already run a supported host and feel token pressure on multi-session tasks, install the plugin, run a real 20–50 step workflow, and inspect the files under the memory directory before and after. If you maintain your own agent runtime, study the progressive disclosure model and Mermaid offload pattern even if you never take the plugin. Flat vector memory will keep shipping. Structured memory is what long-horizon agents actually need.