Tencent Hunyuan Open-Sources Hy-Memory 2.0: Three-Layer Persistent Memory So AI Agents Never Forget

One of the most frustrating flaws in AI coding agents is that after dozens of rounds of conversation, they forget the architecture decisions agreed upon earlier, or repeatedly debug code that was fixed long ago. No matter how large the context window gets, indiscriminately piling up raw conversation history leads to context rot, inflated per-turn latency, and runaway inference costs. The Tencent Hunyuan Cognitive Computing team's answer is to open-source a complete persistent memory solution, Hy-Memory 2.0, which splits an agent's memory into three layers that are managed separately.

One Stack, Three Components, Apache 2.0

Hy-Memory 2.0 is fully open-sourced under the Apache 2.0 license on GitHub and Hugging Face, and consists of three complementary components: the client library and SDK hy-memory (stable version 2.0.2), the local desktop and command-line management application MemHub (plug-and-play with ten mainstream development environments and autonomous agent tools), and the neural network model Hy-Memory-30B-A3B, dedicated to information extraction and conflict resolution.

The model uses Hunyuan's sparse mixture-of-experts (MoE) architecture, activating only 3 billion parameters per forward pass. It extracts entities from complex interaction streams, identifies changes in temporal premises, deduplicates, and then writes to a local SQLite relational database and hierarchical vector index. Officially, it achieves 72.6% accuracy on the LoCoMo continuous memory benchmark while reducing the average token consumption per query from 1159 to 703, cutting context overhead by 39.3%.

Sparse mixture-of-experts (MoE) architecture refers to a model composed of multiple feed-forward expert subnetworks, where each token's forward pass is routed to only a few of them, so the total parameter count can far exceed the actual activation. The name Hy-Memory-30B-A3B indicates roughly 30 billion total parameters and only about 3 billion activated per inference. This design lets the model maintain strong semantic extraction capabilities while keeping VRAM usage and per-inference latency low enough to deploy locally or on a small number of accelerators, making it suitable for memory writing and reconciliation scenarios that require low-latency repeated calls.

LoCoMo is an academic benchmark for ultra-long conversation memory. Through fact-based questions spanning dozens of turns across multi-session dialogues, it tests whether a system can accurately locate and correctly use early information within lengthy histories. The reason token consumption and accuracy are reported side by side is that while infinitely expanding the context window can improve recall, it brings context rot and linearly rising costs—making per-query cost a key metric for judging whether a memory solution is practical.

Three Layers, Each With Its Own Role

Working Memory: Short-Term Working Memory

This layer records the agent's current execution state: the decomposed action plan, pending subtasks, raw outputs of just-invoked tools, and intermediate reasoning drafts. When running a 50-iteration refactoring loop, stuffing all 50 tool-call histories into the prompt would blow up the window, whereas Working Memory dynamically synthesizes only state deltas—which files have passed unit tests, which functions failed to compile, what to do next. On MemoryArena, which evaluates goal persistence, this layer scores 55.31%, 8.4 percentage points higher than a pure summarization-compression pipeline.

Code Memory: Codebase Semantic Memory

Aimed at continuous software engineering scenarios, Code Memory doesn't just store text snippets—it builds a semantic graph on top of the project's abstract syntax tree (AST), indexing cross-file import relationships, function signatures, interface types, and the timeline of diffs and commits. It also persists "lessons learned": when an engineer corrects the agent, pointing out that the company's message library needs asynchronous initialization under a custom singleton, this constraint is anchored to a specific configuration file, and later proactively recalled and injected into prompts in other microservice tasks within the same monorepo. On CodeMemoryBench, this layer achieves 64.2% code context recall accuracy and a 35.6% direct resolution rate for SWE-level problems.

Abstract syntax tree (AST) is a tree-structured representation of source code at the syntactic level. Nodes correspond to language constructs such as function definitions, parameters, calls, imports, and type declarations, stripping away surface-level information like whitespace and comments. Compared with treating code as plain text chunks, AST-based indexing can precisely build a graph structure of "function signature—call site—owning file—import relationship," enabling retrieval to locate by symbol rather than by string similarity. When refactoring causes line numbers to drift, AST nodes and their semantic identities remain stable, so Code Memory can anchor historical lessons to specific symbols and configuration files and recall them accurately in cross-file, cross-microservice tasks.

Chat Memory: Conversational Episodic Memory

Chat Memory converts fragmented conversations into structured episodic events indexed by entity-relationship-time triples. The most common pitfall of traditional similarity retrieval is premise conflicts: a user says on Monday that production nodes run Python 3.12, then says on Thursday they've migrated to 3.14—naive RAG recalls both and induces the model to generate incompatible scripts. Hy-Memory-30B-A3B performs semantic reconciliation at this layer, recognizing that the newer statement temporally invalidates the old fact, archiving legacy data, and retaining currently valid facts. On LoCoMo, which targets 100k-token-scale continuous conversations, this layer supports overall performance reaching a 72.6% hit rate.

Temporal premise change and conflict resolution is the core difficulty that distinguishes a memory system from ordinary retrieval. Naive similarity retrieval only looks at semantic closeness and cannot determine whether two statements have a replacement relationship in time, so old and new facts are recalled together. A common engineering approach is to attach a validity interval to each fact, treat the new statement as an invalidation declaration of the old fact, and move old records into an archive so they no longer enter the active retrieval set. Hy-Memory-30B-A3B takes on this judgment: recognizing that statements like "migrated to 3.14" semantically override previous version claims, thereby completing reconciliation at the write stage rather than leaving conflicts for the base model to resolve during generation.

Head-to-Head Comparison With Frontier Models

The experiments compare Hy-Memory 2.0 directly with DeepSeek^Ad 4.1, Claude Fable 5.1, and GPT-6 Astra across four dimensions: LoCoMo episodic memory, CodeMemoryBench codebase understanding, MemoryArena goal persistence, and average token consumption per query.

• Leading on LoCoMo: 72.6% versus GPT-6 Astra's 71.2%, Claude Fable 5.1's 70.8%, and DeepSeek 4.1's 68.4%. The advantage comes from the 30B-A3B expert model's proactive consolidation: instead of waiting for the base model to search thousands of tokens of noisy history for a variable declared at the beginning, Hy-Memory delivers the already-cleaned fact directly from local SQLite within 4 milliseconds.
• 39.3% token reduction: With remote solutions using native context caching, engineers still pay to read the entire history. Hy-Memory reduces tokens per query from 1159 to 703, saving nearly 40% of inference quota and avoiding hitting the context window's attention saturation zone.
• Clear advantage in the code domain: 64.2% QA accuracy and 35.6% full-task resolution rate on CodeMemoryBench come from native integration with the project's AST, which can associate compile-time errors with lessons recorded in past tasks.

Python Integration Example

The official SDK provides an asynchronous interface, allowing agents to read and write memories on transactional relational storage at millisecond latency without network round-trips. The following implementation connects to the local MemHub daemon, writes an active goal into Working Memory, registers a semantic patch and a lesson in Code Memory, then performs an episodic query:

import asyncio
import aiosqlite
from datetime import datetime

async def open_memhub_store(db_path: str = "/tmp/memhub_local.db"):
    conn = await aiosqlite.connect(db_path)
    await conn.execute("PRAGMA journal_mode=WAL;")
    await conn.execute("PRAGMA synchronous=NORMAL;")
    await conn.execute(
        "CREATE TABLE IF NOT EXISTS mem_records "
        "(node_id TEXT PRIMARY KEY, stratum TEXT NOT NULL, payload TEXT NOT NULL, "
        "info TEXT NOT NULL, logged_at TEXT NOT NULL);"
    )
    await conn.commit()
    return conn

async def insert_working_state(conn, chore_id: str, objective: str, scratch: str) -> str:
    rid = f"wrk_{chore_id}_{int(asyncio.get_event_loop().time() * 1000)}"
    meta = f'{{"chore_id": "{chore_id}", "phase": "active"}}'
    body = f"OBJECTIVE: {objective} | NOTES: {scratch}"
    t_now = datetime.utcnow().isoformat()
    await conn.execute(
        "INSERT OR REPLACE INTO mem_records VALUES (?, ?, ?, ?, ?);",
        (rid, "working", body, meta, t_now),
    )
    await conn.commit()
    return rid

async def store_codebase_rule(conn, pkg: str, ast_tag: str, lesson: str) -> str:
    rid = f"code_{pkg}_{ast_tag}"
    meta = f'{{"package": "{pkg}", "symbol": "{ast_tag}"}}'
    t_now = datetime.utcnow().isoformat()
    await conn.execute(
        "INSERT OR REPLACE INTO mem_records VALUES (?, ?, ?, ?, ?);",
        (rid, "code", lesson, meta, t_now),
    )
    await conn.commit()
    return rid

async def query_episodic_log(conn, top_k: int = 3):
    cur = await conn.execute(
        "SELECT node_id, stratum, payload, info, logged_at FROM mem_records "
        "ORDER BY logged_at DESC LIMIT ?;", (top_k,)
    )
    rows = await cur.fetchall()
    await cur.close()
    return [
        {"node_id": r[0], "stratum": r[1], "payload": r[2], "info": r[3], "logged_at": r[4]}
        for r in rows
    ]

async def execute_hymemory_orchestration():
    db = await open_memhub_store()
    await insert_working_state(db, "TASK-890", "调整异步连接池", "检查高峰超时")
    await store_codebase_rule(db, "pkg.io", "SocketPool", "固定 max_connections=500，空闲 60 秒关闭")
    matches = await query_episodic_log(db, 3)
    await db.close()
    return {"outcome": "ready", "hits": len(matches), "entries": matches}

async def main():
    res = await execute_hymemory_orchestration()
    print(f"执行完成: {res['outcome']}，记录数: {res['hits']}")
    for e in res["entries"]:
        print(f"  [{e['stratum']}] {e['payload']}")

if __name__ == "__main__":
    asyncio.run(main())

This code shows how MemHub's asynchronous interface lets an agent register technical lessons and operational steps without adding network overhead, completing queries at millisecond latency on relational storage protected by WAL (Write-Ahead Logging) transactions.

WAL (Write-Ahead Logging) is a SQLite journaling mode in which write operations are first appended to a separate log file and then merged back into the main database, allowing reads and writes to proceed concurrently without blocking each other on a single large lock. For the agent's high-frequency, small-batch memory writes and instant queries, this means more controllable query latency and lighter transaction commits. The example above also sets synchronous=NORMAL, a trade-off between durability and throughput: in a crash, the last small segment of committed transactions could theoretically be lost, but ordinary power loss and process exits won't corrupt the database—suitable for memory scenarios that can tolerate minimal rollback.

Note that the example code directly operates on SQLite's mem_records table, which is a simplified connection between the demo layer and the storage layer; in production, writes should go through the hy-memory SDK's asynchronous interface, with the SDK responsible for maintaining the hierarchical vector index, persisting entity-relation extraction results, and ensuring cross-layer consistency—avoiding bypassing the index and breaking retrieval.

Cost Math and Deployment Paths

If a 100-person engineering team each has 50 conversation rounds per day with agents, the traditional approach consumes an average of 1159 tokens of history per round—about 5.8 million tokens per day, and over 170 million tokens per month billed at frontier prices. With Hy-Memory 2.0 at 703 tokens per round, daily consumption drops to 3.5 million, saving over 68 million tokens per month, while a smaller input window also reduces time-to-first-token latency.

Deployment comes in two forms. Individual developers can install the MemHub desktop app or compile it locally; the program automatically detects installed editors and automation tools, injects the memory interceptor, and creates a statically encrypted SQLite database in the user directory. Distributed teams can deploy the MemHub daemon in a Docker container, mount PostgreSQL or networked SQLite, and privately deploy Hy-Memory-30B-A3B on two balanced NVIDIA accelerator cards or a single high-end accelerator card plus a local accelerated runtime, without relying on third-party APIs. To migrate from LangChain Memory or naive RAG, the official repository provides migration scripts that convert JSON histories and vector stores into the three-layer typed structure.

Technical Q&A

How is this different from traditional RAG? Traditional RAG performs geometric retrieval over a vector store, ignoring the time dimension and reasoning structure, and often recalls outdated or irrelevant snippets. Hy-Memory 2.0 uses a three-layer architecture plus the 30B-A3B expert model's proactive semantic reconciliation to deduplicate facts, detect contradictions in sequential statements, and isolate tool drafts in Working Memory.

Is Hy-Memory-30B-A3B required? No. MemHub is designed to be decoupled; on a laptop you can run a heuristic mode based on AST rules and SQLite, and only bring in the MoE model when you need deep reconciliation of long conversations and high-fidelity semantic deduplication.

Which editors and tools are supported? MemHub natively integrates with ten: VS Code (official agent extension), the JetBrains family, Neovim (Lua plugin), autonomous command-line terminals, and more.

What's the query latency? With local SQLite WAL plus HNSW indexing, Working Memory and Code Memory retrieval takes under 5 milliseconds per turn—negligible compared with the hundreds of milliseconds to several seconds of inference latency of frontier models.

License and data ownership? The source code, libraries, and model weights are all released under Apache 2.0, permitting commercial use, modification, security auditing, and fully private hosting, meeting compliance requirements such as LGPD and GDPR without sending data to external vendors.

A Few Observations

The three-layer memory split is closer to engineering reality than simply piling on context window: code structure, conversational facts, and execution drafts inherently deserve different retention policies and expiration rules. The combination of open source and local-first has genuine appeal for data-sensitive enterprise teams. One caveat: the LoCoMo, CodeMemoryBench, and MemoryArena scores cited here all come from the official technical report's framing, and no third-party reproductions have appeared yet—actual results still need validation in real projects.

One-line Summary

Tencent Hunyuan open-sources Hy-Memory 2.0, using three-layer persistent memory to reduce agent forgetting and token overhead.

Paragraph Summary

The Tencent Hunyuan Cognitive Computing team has open-sourced Hy-Memory 2.0 under the Apache 2.0 license, releasing three components: the SDK hy-memory, the local management app MemHub, and the MoE model Hy-Memory-30B-A3B. It splits agent memory into three layers: Working Memory manages execution state and intermediate drafts, Code Memory indexes codebase semantics via abstract syntax trees and accumulates lessons learned, and Chat Memory organizes conversational episodes as entity-relationship-time triples while resolving temporal contradictions. It reaches 72.6% accuracy on LoCoMo, cuts tokens per query from 1159 to 703 (a 39.3% reduction), and achieves local retrieval latency under 5 milliseconds. The solution emphasizes local-first and private deployment; MemHub integrates with ten mainstream development environments and supports migration from LangChain Memory or naive RAG. The author notes that the cited results come from official reports and await third-party reproduction.