The problem
Most LLM memories are "chunk → embed → top-k": they rank by similarity and never ask whether something is relevant, current, or trustworthy. Nothing is ever forgotten. It's a landfill with a search box.
hipercampo separates what it remembers from what it suspects, and runs a cycle modeled on the hippocampus: surprise-gated writing, sleep consolidation, and active forgetting, over a navigable graph of 10,000-bit hypervectors.
Four ideas, one cycle
| mechanism | what it does | inspiration |
|---|---|---|
| vsa / hypervectors | Memories as binary hypervectors with real algebra (bind/bundle). Tells "the dog bites the man" from its reverse — something dense embeddings blur. CPU-only, no GPU. | Kanerva · Plate |
| surprise gate | A double veto: won't store the redundant (something similar exists) nor the predictable (an internal compression model already saw it coming, measured in bits). | hippocampal prediction error |
| sleep | An offline pass groups similar episodes into semantic memory and archives the originals, on your own schedule. | hippocampus → cortex replay |
| forgetting | Strength decays with disuse. The weak goes dormant, not
deleted, and can resurface through hc_muse. Importance
protects. |
adaptive forgetting |
≈1%
of nodes visited per recall at 100,000 memories — it navigates a small-world graph instead of scanning it, and that number is measured, not claimed.
Try it — 30 seconds, no agent client
$ pip install numpy $ python scripts/demo.py
You'll watch the algebra distinguish word order, then the full cycle — surprise → recall → sleep → forget — run end to end.
Engineering honesty
Tools every agent gains
| tool | for |
|---|---|
| hc_remember | Store something, if it's novel or surprising enough to pass
the gate. importance protects from forgetting; confidence
weights ranking. |
| hc_recall | Retrieve by similarity and spreading activation — and it can abstain, returning nothing rather than guessing. |
| hc_muse | Creative recall: surfaces indirect connections and dormant memories that resurface to tie ideas together. |
| hc_dream | Creative sleep: proposes bridges between memories that share a common associate — staged as hypotheses, never live until confirmed. |
| hc_remember_fact | Store a structured subject/predicate/object fact.
A superseding fact doesn't delete the old one — it closes its validity and the
old value becomes history. |
| hc_ask_role | Ask for a field knowing the others — "who bites the man?" —
by unbinding. Answers what's true now, or, with days_ago, what was
true then. |
| hc_consolidate / hc_forget | Sleep and active forgetting on demand. hc_forget(dry_run=True)
rehearses what would go dormant without touching anything. |
18 tools total; only the 6 daily ones are announced by default so tool descriptions don't tax every request — the rest activate hot, on first use.
Scale & latency — measured
| corpus | quality | p95 | visited |
|---|---|---|---|
| 655 real Python stdlib docs | navigate-vs-scan fidelity 1.000 | CI-gated | 42.6% |
| 10,000 structured memories | precision@5 1.000 | ~2.2 ms | 1.751% |
| 100,000 structured memories | group precision@5 1.000 | 6.94 ms | 1.094% |
At 100k the resident index is 141.5 MB; cold
construction takes 7.46 s, warm reuse 0.073 ms. Reproduce with
scripts/nav_scale.py and scripts/nav_real.py --check.
What it costs you — measured in tokens
| source | cost | when |
|---|---|---|
| announced tools (6, default) | ~810 tok | every request |
| with HIPERCAMPO_TOOLS=all (18) | ~2,070 tok | every request |
| hook injection | ≤350 tok | only on turns that fire |
The expensive part was never the memory — it's tool descriptions traveling in every request whether or not they're called. Measured end to end over a 30-turn session: 87k → 26k tokens.
0.000
contradiction rate answering superseded facts, vs 0.708 for a store-everything baseline — a six-month simulated agent memory, 1,844 events. Temporal validity means a new fact closes the old one instead of leaving two truths in the graph.
Contexts stay separate, on purpose
All memory lives in a single file; namespaces are drawers inside it. You write to your own and read from the ones you link — what's linked is read, never touched.
~/.hipercampo/hipercampo.db ├── __self__ the agent's working identity ├── personal who you are ├── proj-webshop ══> you write here while working on the shop └── proj-blog ──> you read it, but never touch it
Local isolation, not multi-user security — hipercampo is local-first by design, and stays that way. Full map in INSTALL.md.
Honest positioning
hipercampo did not invent hyperdimensional computing — VSA dates to the '90s (Kanerva, Plate) — nor is it the first attempt at agent memory (Mem0, Letta, Graphiti, MemGPT). What's original is the specific combination: VSA algebra + surprise (MDL) + consolidation + forgetting + four independent axes, exposed as an MCP server, treating memory as a cycle rather than a store. We don't claim to beat embedding-based hybrid memories — we explore a different paradigm, with its limits measured and stated, not buried.
This is a beta
Local-first with no telemetry means nothing phones home — which also means your feedback is the only signal we get. Open a beta feedback issue for what worked and what rubbed, or a bug report for what broke. No account-tracking, no analytics — just issues, PRs, and stars.
Read further