🧠 hipercampo

🌍 Español: README.es.md · You are reading the English version.

A living memory for Claude, built on hypervectors — not embeddings.

Most LLM memories are the same thing: chunk text, turn it into dense vectors, and retrieve the closest ones (ANN / top-k). That measures similarity, but not relevance, not importance, and it never forgets. It's a landfill with a search box.

hipercampo tries something else. It's an MCP server that gives Claude a memory modeled on the hippocampus, with four ideas integrated into a cycle:

Engineering honesty. Surprise combines two signals: lexical novelty (1 − max similarity to what's stored) and real prediction error, estimated by an in-house incremental language model in bits/token (compression/MDL, no neural net, no GPU). The base encoder is lexical; for synonyms there's an optional semantic hook (below). Everything is swappable without touching the rest.

Install (full guide: INSTALL.md)

Quick path — local Python + Claude Code:

git clone https://github.com/armandojaleo/hipercampo.git
cd hipercampo
pip install -e .                                  # installs hipercampo + deps
python scripts/demo.py                            # (optional) watch the cycle run
claude mcp add hipercampo -- python -m hipercampo.server   # connect to Claude Code

Restart Claude Code and you'll have 6 new tools (hc_remember, hc_recall, hc_update, hc_consolidate, hc_forget, hc_stats). For Docker, Claude Desktop, .mcp.json, verification and troubleshooting → INSTALL.md.

30-second try (no Claude)

pip install numpy
python scripts/demo.py

You'll see the algebra distinguishing word order and the full cycle (surprise → recall → sleep → forget) working.

Test battery — it does what it says

python tests/test_vsa.py          # VSA algebra (bind/bundle/order)
python tests/test_memory.py       # the CYCLE: surprise, recall, sleep, forget, persistence
python tests/test_namespaces.py   # context isolation, concurrency, transactions
python tests/test_calibration.py  # adaptive surprise, rollback, empty query, cohesion
python tests/test_properties.py   # invariants over fabricated data (8 rounds)
python scripts/scenarios.py       # narrated story: Claude remembering a user

10 suites in total, all green in CI (Python 3.11–3.13). Example invariants checked: a duplicate never creates a second memory, a needle is retrieved among 25 distractors, forgetting never deletes something with importance ≥ 0.8, one context can neither see nor modify another's data, a failed transaction leaves no trace.

Baseline comparison (Phase 2)

python scripts/baselines.py [--semantic] pits hipercampo against the standard methods on the same corpus (10 facts + 10 confusable distractors). MRR per category

• false-recall rate (unrelated queries that still return something):

Honest reading:

• On ranking (MRR), hipercampo+semantic wins (0.95): it fuses lexical precision (keyword/typo) with semantic reach (synonyms). In pure-lexical mode it already beats BM25, especially on typos (0.95 vs 0.77) thanks to character trigrams.

• On abstention, it loses: embeddings reject negatives with a cosine threshold (falseRec 0.20); hipercampo doesn't yet (1.00). MIN_RECALL_SCORE needs calibration.

• The corpus is small and synthetic: a signal, not proof at scale. See ROADMAP.md.

Scale & latency (measured)

Vectorized scan (XOR of the whole matrix + native NumPy 2.0 popcount): ~5× faster than row-by-row. It's linear (no ANN index): plenty for personal memory (hundreds to thousands); at ~100k you'd want an index. A known limit, not hidden.

Tools Claude gains

The four axes of a memory (novelty ≠ importance ≠ reliability ≠ utility)

Forgetting combines the last three into a transparent retention (0.4·importance + 0.3·reliability + 0.3·utility): time only flags candidates, but value decides.

Compositional memory with roles (the differentiator)

The thing embeddings can't do: ask who did what to whom and get the right answer by role. A fact is encoded by binding each value to its ROLE and bundling — then you recover any field by unbinding (hipercampo/roles.py):

from hipercampo.roles import ItemMemory, encode_fact, query_role
im = ItemMemory()
fact = encode_fact({"subject": "dog", "predicate": "bites", "object": "man"}, im)
query_role(fact, "subject", im)   # -> [("dog", 0.74)]
query_role(fact, "object",  im)   # -> [("man", 0.76)]

python scripts/roles_demo.py shows the punchline: "dog bites man" and "man bites dog" have the same values but the recovered subject/object are swapped — a dense embedding places them at nearly the same point; VSA keeps them distinct. Measured: correct filler recovered per role with a clear margin (0.74 vs 0.54), capacity up to 5 roles. Wiring these role-records into the live MCP cycle is next (see ROADMAP.md).

Contexts, Docker, security

• Contexts: namespaces (HIPERCAMPO_NAMESPACE) to isolate projects/profiles in one DB, or separate files (HIPERCAMPO_DB). Local isolation, not multi-user security — hipercampo is local-first. See SECURITY.md.

• Docker: docker compose build && docker compose run --rm hipercampo.

• Security: retrieved text is data, not instructions. Built-in safeguards (hipercampo/safety.py): hc_remember warns on likely secrets (plaintext DB), hc_recall flags memories that look like injected instructions as untrusted. They warn, not block. Details in SECURITY.md.

Architecture

text ──▶ encoder.py ──▶ hypervector (10,000 bits)
                             │
       vsa.py  (bind / bundle / permute / vectorized popcount)
                             │
    memory.py  ── surprise · recall+spreading · sleep · forget · 4 axes
                             │
     store.py  ── SQLite WAL (memories + graph, namespace-isolated, transactional)
                             │
    server.py  ── MCP (stdio) ──▶ Claude

Related work & honest positioning

hipercampo did not invent hyperdimensional computing (HDC/VSA dates to the 90s: Kanerva, Plate), nor is it the first attempt at agent memory (Mem0, Letta, Graphiti, MemGPT; MnemoCore uses HDC). What's original is the specific combination: VSA + surprise (MDL) + consolidation + forgetting + four axes, exposed as an MCP server, treating memory as a cycle. We don't claim to beat embedding-based hybrid memories; we explore a different paradigm, with its limits measured.

License & attribution

MIT (see LICENSE). Original code; dependencies and ideas credited in ATTRIBUTION.md. House rule: if we use others' work, especially copyrighted, we say so.

Acknowledgments

Built by Armando Jaleo with Claude (Anthropic), measuring before believing and telling the truth about the limits. Thanks to Pentti Kanerva and Tony Plate, whose decades-old ideas are still alive here. And to whoever audits with rigor: honest criticism made this project better on every pass.

And yes — congratulations, Spain! 🇪🇸⚽ Some memories deserve confidence=1.0.

A memory is not a store: it's a cycle that saves, relates, consolidates, and forgets. If one day this helps machines remember with judgment — and lets the people who use them audit it — it will have been worth it. — made with care. 🧠