Sign in

HeapDB for AI agent memory

Memory that learns what your agent actually uses.

heapdb-memory ranks your agent’s memories by relevance, importance and learned usefulness, and explains every recall. Every time your agent reports what it used, HeapDB learns from it.

Add to Claude CodeTry the demo

Open sourceApache-2.0Python SDK, MCP server, LangGraph & LlamaIndex

RECALL “When is Maya's flight?” IN user:maya K 3 EXPLAIN

Ask the agent’s memory. Tell it what helped.

HeapDB recalls the memories most likely to help with this question and explains each one. The demo opens after the agent reported which memory it used for the flight question; mark memories used or not used and watch HeapDB learn which kinds of memory help which kinds of question.

An assistant’s memories of Maya

Example data

After one round of feedback. The first time this was asked, the assistant’s own note “searched flights to Lisbon” was the closest text match and ranked first, with Maya’s message second. The agent reported that it used Maya’s message and not the note, and HeapDB re-ranked.

RECALL “When is Maya's flight to Lisbon?” IN user:maya K 3 EXPLAIN

  1. Maya: my flight to Lisbon leaves Friday at 9:40, back on Mondayscore 0.317

    • rel 0.79
    • importance 0.8
    • useful 0.50
    • qt:when&date:yes 0.07
    • episode
    • has date
    • speaker: Maya
    • recency off

  2. Assistant: searched flights to Lisbon for Mayascore 0.282

    • rel 1.00
    • importance 0.8
    • useful 0.35
    • qt:when&num:no 0.06
    • episode
    • speaker: assistant
    • recency off

  3. Maya: my sister Ana is coming to Lisbon tooscore 0.183

    • rel 0.50
    • importance 0.8
    • useful 0.46
    • qt:when&speaker:named 0.07
    • episode
    • speaker: Maya
    • recency off

Score = relevance × importance × learned usefulness. Recency is off (weight 0), the setting tuning picked on LoCoMo. Mark a memory used or not used and watch the ranking learn.

More in the demo →

Get started in a minute

Install the package, add three memories, recall them with EXPLAIN, and report what your agent used. That’s the whole loop.

# Python 3.10+
pip install "heapdb-memory[mcp]"
# Claude Code: add the MCP server
claude mcp add heapdb-memory -e HEAPDB_MEMORY_NAMESPACE=user:me -- heapdb-memory-mcp
from heapdb_memory import Memory

mem = Memory(namespace="user:maya")
mem.add("Maya's flight to Lisbon leaves Friday 9:40", kind="fact")
mem.add("Maya is vegetarian and avoids peanuts", kind="preference")
mem.add("flights api: 14 fares to Lisbon found", kind="tool_result", source="tool")

res = mem.recall("when does Maya fly to Lisbon?", k=3)
print(res)
mem.mark_used([res[0].id])   # the agent used it: learn from that

output (results 2 and 3 without their EXPLAIN lines) RECALL 'when does Maya fly to Lisbon?' IN user:maya (3 candidates) 1. [8461ecf34413] Maya's flight to Lisbon leaves Friday 9:40 score=0.1247 rel 1.00 (bm25 1.00) x recency 1.00 (age 0.0d) x importance 0.95 x useful 0.13 [date:yes=0.01, ent:yes=0.01, kind:fact=0.01] 2. [b54afdee0c45] Maya is vegetarian and avoids peanuts score=0.0851 3. [c19207ccc692] flights api: 14 fares to Lisbon found score=0.0404

Every result tells you why it ranked, as relevance × recency × importance × learned usefulness. Once your agent reports what it used, usefulness starts telling memories apart.

Full setup guideGitHub (heapdb-memory)

Why HeapDB for memory

  • Learns which memories help

    When your agent marks memories used or not used, HeapDB learns which kinds of memory help which kinds of question. On LoCoMo that improves retrieval by +0.051 MRR over an equally tuned BM25 + embedding hybrid, and the gain holds with realistic noisy feedback (+0.035 with half the citations missed and 10% wrong).

    LoCoMo results →

  • Every recall explained

    Every memory comes back with its relevance, importance, learned usefulness and the links behind it. You see why it ranked, and you can correct it.

    EXPLAIN →

  • Plugs into your agent

    Connect through our MCP server for Claude Code, Claude Desktop and Cursor, through the LangGraph and LlamaIndex adapters, or straight from the Python SDK.

    Setup →

heapdb-memory is open source (Apache-2.0) on PyPI. On LoCoMo, learned usefulness improves retrieval by +0.051 MRR over an equally tuned hybrid, and by +0.035 with realistic noisy feedback.

Go deeper

The full example walks through the mapping, the scoring formula, setup for each integration and the benchmarks. Agent memory runs on HeapDB, the same engine behind our other use cases.