Metadata-Version: 2.4
Name: hyperrecall
Version: 0.1.0
Summary: Hypergraph memory for LLM agents — spreading activation, decay, and a portable file format.
Project-URL: Homepage, https://github.com/elicazer/hyperrecall
Project-URL: Repository, https://github.com/elicazer/hyperrecall
Project-URL: Documentation, https://github.com/elicazer/hyperrecall#readme
Project-URL: Issues, https://github.com/elicazer/hyperrecall/issues
Author: Eli Azer
License: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,hypergraph,knowledge-graph,llm,memory,retrieval,spreading-activation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: numpy>=1.23
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.9
Provides-Extra: all
Provides-Extra: crewai
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: langchain
Provides-Extra: langgraph
Provides-Extra: llamaindex
Provides-Extra: mcp
Provides-Extra: pydanticai
Description-Content-Type: text/markdown

# 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

```python
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.

| | Vector memory (naive RAG) | Mem0 / Zep (KG memory) | **HyperRecall** |
|---|---|---|---|
| Structure | none — flat chunks | knowledge graph: `(head, relation, tail)` triples | **hypergraph: N-ary edges with roles** |
| One "Eli asked David about TEDx on Jul 13" fact | 1 opaque chunk | ~4–6 lossy triples that lose the *co-occurrence* | **1 `Experience` edge binding all 5 participants** |
| Retrieval | top-k cosine | graph walk / triple lookup | **spreading activation → connected subgraph** |
| Forgetting | none (or crude TTL) | usually none | **pluggable decay curve (Ebbinghaus, power-law)** |
| Reinforcement on access | none | none | **Hebbian boost** |
| Contradictions | invisible | often silently overwritten | **explicit `Contradicts` edge, both surfaced with a flag** |
| Supersession | invisible | overwrite (history lost) | **`Supersedes` edge; newest preferred, history kept** |
| Portability | proprietary store | proprietary store | **directory of Markdown+YAML, lossless round-trip** |
| Core deps | vector DB | vector DB + graph DB + LLM | **stdlib sqlite3 + numpy** |

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`](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

- [x] Hypergraph substrate (nodes, N-ary hyperedges, roles)
- [x] Spreading-activation retrieval → subgraph
- [x] Decay + Hebbian reinforcement
- [x] Contradiction + supersession semantics
- [x] Portable Markdown+YAML export/import (lossless)
- [x] SQLite + FTS5 storage, numpy embedding search
- [x] 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

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

## License

Apache 2.0. See [`LICENSE`](LICENSE). Built by Eli Azer.
