HyperRecall

Portable memory for AI agents. 87.5% on Mem0's LoCoMo benchmark, $0 ingest cost.

Drop-in memory that thinks the way brains do — a hypergraph of experiences with spreading activation, decay, and contradiction handling. Not a bag of vector chunks.

Install

pip install hyperrecall

3-line quickstart

from hyperrecall import Mesh

mesh = Mesh("./mesh.db")
mesh.remember("Eli is building HyperRecall", participants=["Eli"])
print(mesh.recall("what is eli building").to_context_string())

Why HyperRecall

• 87.5% on LoCoMo (Mem0's harness, gpt-5 judge, 1540 questions) — 4pt behind Mem0's committed number using their own harness, with $0 ingest cost
• $0 ingest — no LLM extraction pass required; ingest scales linearly with input size, not model tokens
• Portable file format — export any mesh to Markdown, re-import, or move between agents. Your memory is not locked into a vector DB
• Contradictions & supersession as first-class — memories can conflict, be marked obsolete, or supersede older versions. Time is real
• Spreading activation retrieval — recall doesn't just find the nearest vectors; it finds the connected web

Why not just use Mem0 / Zep?

An honest comparison. These are good tools; HyperRecall makes different bets.

The core disagreement is triples vs. hyperedges. A knowledge graph shreds "Eli asked David about TEDx applications on July 13 at 8pm" into a handful of binary edges (Eli —asked→ David, conversation —about→ TEDx, …). The fact that these all happened in one episode — the thing a human actually remembers — is exactly what gets lost. HyperRecall keeps the episode whole as a single hyperedge. See DESIGN.md for the full argument.

Design principles

1. Genuine hypergraph. Hyperedges are first-class objects with a type, weight, decay rate, provenance, and members that each carry a role. Arity is arbitrary (N ≥ 2). This is not a triple store wearing a costume.
2. Neuroscience-inspired. Spreading activation, forgetting curves, Hebbian reinforcement, contradiction and supersession — memory as a dynamic system, not a static index.
3. Portable. Any mesh exports to human-readable Markdown+YAML and imports back losslessly. Your memory is yours; move it between Claude, Cursor, OpenClaw, or your own scripts. "USB-C for AI memory."
4. Open-source forever. Apache 2.0. Python-first, TS SDK later. No cloud lock-in, no proprietary format.

How it works (30 seconds)

• Nodes are memory units (facts, entities, decisions, outcomes), each with a confidence, an activation (its live salience), and a decay_rate.
• Hyperedges connect N ≥ 2 nodes; each member has a role and a weight. Types include Experience, Contradicts, Supersedes, Refines, CausedBy, MentionedTogether.
• Recall embeds your query, finds seed nodes (semantic + lexical), then spreads activation through hyperedges for k hops. Energy entering one member of a hyperedge lights up all the others. You get back a connected subgraph, ranked, with conflicts flagged — rendered to Markdown or a compact context string.
• Storage is a single SQLite file (FTS5 for lexical search, float32 BLOB embeddings searched in numpy — no native extensions required).

Roadmap

• Hypergraph substrate (nodes, N-ary hyperedges, roles)
• Spreading-activation retrieval → subgraph
• Decay + Hebbian reinforcement
• Contradiction + supersession semantics
• Portable Markdown+YAML export/import (lossless)
• SQLite + FTS5 storage, numpy embedding search
• CLI (hyperrecall remember | recall | export | import | demo)
• LLM-based ingestion — extract atomic nodes + typed edges from raw turns
• Pluggable real embedding models (OpenAI, local sentence-transformers)
• Automatic contradiction/supersession detection at ingest
• TypeScript SDK reading the same portable format
• Entity resolution / node dedup
• Optional encryption + federated sync

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

License

Apache 2.0. See LICENSE. Built by Eli Azer.