A small, honest memory engine
Prime Memory Folding is a standalone memory engine for agents and IDEs. It is not the claim that prime numbers beat databases. It is a reproducible composition of four layers, each doing the one job it is genuinely good at: deterministic prime-addressed structure, semantic vector recall, decay-driven folding, and an MCP server. Extracted from the Aether-Hyper research system, with the math made public and the identity-bearing internals left behind.
- Structure: exact, prime-addressed indexing. Deterministic, not fuzzy.
- Meaning: dependency-free cosine vector recall, additive to structure.
- Durability: folding decays, clusters, and compresses old memory.
- Reach: a stdio MCP server with 5 tools any IDE agent can call.
What it is, and what it isn't
Most memory projects oversell. This one draws a hard line around its claim surface and keeps it narrower than the ambition. The structure layer gives a clear, constant-factor win on the bundled benchmark, verified by checking result-set equivalence before timing. Everything beyond that is stated as exactly what it is, no more.
- IS: an O(1) domain index plus exact tag intersection by divisibility.
- ISN'T: a database replacement, and not 'orders of magnitude' anything.
- ISN'T: sublinear tag search. Tag filtering is O(n) candidates, one modulo each.
- ISN'T: a consciousness runtime. The identity internals stayed home by design.
Every memory gets a prime address
Each record carries a compact 128-bit address built by packing four prime-derived fields together. The runtime assigns a stable prime to every label it sees: common IDE memory domains ship as defaults, new labels get the next available prime, and once assigned a prime is never reused for that store. The address stays small and exact, which is what makes domain lookups O(1).
- domain_prime << 96 | subdomain_prime << 64 | concept_bucket << 32 | instance_id
- record_id is just the hex form of the packed 128-bit address.
- A domain index maps domain -> record ids, so domain queries skip the scan.
Tag filtering by prime multiplication
Here is the trick that makes tag intersection exact instead of fuzzy. Every tag maps to a prime. A record stores the product of all its tag-primes as one unbounded Python integer. To find every record tagged both 'technical' AND 'code', you multiply those two primes and test divisibility. If the record's product divides evenly, it has both tags. No set logic, no false positives, just arithmetic.
- tag_product = product(prime(tag) for tag in record.tags)
- Match test: record.tag_product % product(query primes) == 0
- Exact by construction: unique factorization means no collisions.
Vectors add meaning on top of structure
Exact addressing finds records you can name. Vector recall finds records that mean something similar even when the tags don't line up. Each record can carry an optional float vector; queries score candidates with plain cosine similarity and sort best-first. It is dependency-free, additive to the structure layer, and runs after the cheap filters have already shrunk the candidate set.
- Pre-filter by domain and tags first, then score what's left.
- Cosine similarity, no external libraries, no vector DB required.
- Structure narrows; meaning ranks. The two layers compose.
One query, four cheap gates
A query flows through gates from cheapest to most expensive. If you name a domain, it pulls candidates straight from the domain index instead of scanning. A strength threshold drops faded memories. A tag filter applies the modulo test. Finally, if you passed a vector, cosine similarity scores and ranks. Each gate is optional, and each one shrinks the work the next gate has to do.
- Domain filter? Use the index. No domain? Scan record values.
- Strength threshold prunes decayed records early.
- Tag filter runs the prime-product modulo test.
- Vector query runs last: cosine similarity, then best-first sort.
Folding keeps memory from becoming a log
An append-only memory store grows forever and gets slower and noisier as it goes. Folding is the maintenance pass that fixes that. Strength decays over time, weak records get pruned, similar records cluster by domain and vector, repeated patterns merge into a single folded memory, and that compact result gets promoted to long-term state. The store stays small, durable, and meaningful instead of just big.
- Decay strength, then prune the records that fell below threshold.
- Cluster by domain plus vector similarity, merge repeated patterns.
- Promote the folded memory and persist a compact long-term state.
An MCP server any IDE agent can call
The engine ships as a stdio MCP server so Claude, Cursor, VS Code, and JetBrains agents can use it as live memory. It exposes five tools and is hardened around protocol fixtures and malformed-frame recovery. CI smoke-tests the full handshake: initialize, notifications/initialized, tools/list, and tools/call. Live IDE-client validation is honestly flagged as still a manual step, not a finished claim.
- Five tools: encode, store, query, fold, stats.
- Handshake is CI-smoke-tested; live-client check is a tracked release gate.
- Run it via Python module or the Node launcher in bin/.
python3 -m prime_memory_folding.mcp_servernode bin/prime-memory-folding-mcp.jsExtracted from Aether, stripped of the hype
Prime Memory Folding came out of the Aether-Hyper research system. The repo keeps a slim evidence/ bundle showing that origin: the original prime cache, three architecture analyses, and a visual comparison. None of it is imported by the runtime; it exists so builders can inspect the idea's lineage. The famous '60,000x vs SQL' figure from that origin is retained only as caveated provenance, never as a claim about this code.
- evidence/ is provenance only. The package is standalone at runtime.
- Shaped by an adversarial build loop: a director plus independent build/review lanes.
- That loop caught a broken encoding path and a benchmark that flattered the project.