cortexm remembers what you tell it. Forever. For free. On your machine. Same result every time.

Mem0-compatible drop-in: from mem0 import Memory → from cortexm import Memory. Zero LLM calls at ingest. Zero LLM calls at retrieval. Zero monthly cost. Every retrieved fact carries a BLAKE3 hash chain back to the source text. One .db file you own.

Quick start

pip install cortexm          # works offline, no API keys, single command

from cortexm import Memory   # Mem0-compatible surface

m = Memory()
m.add("I work at Google", user_id="alice")
m.search("Where does Alice work?", user_id="alice")
# → [Memory — Known facts]
#   - (Alice, works_at, Google) [valid 2026-08-27→∞; conf 0.92;
#      id 3f2a91c2; src #a1b2c3d4; "I work at Google"]

Canonical LongMemEval — μ=0, $0, on a 4GB laptop

Full 500-question results — v0.6.4, the first full-corpus run that actually completed.

Honesty correction #1 (v0.6.4): the v0.6.2 README claimed 97.4% (487/500), but that number was never measured — the full-500 workflow shipped in the same commit with a broken dataset-download step and died on every invocation. The real slices from that era scored 0.943.

Honesty correction #2 (v0.6.5): the v0.6.4 README claimed 94.4% (472/500) — that number was contaminated. The aggregate step globbed benchmarks/results/canonical_slice_*.json on a checkout that also contained stale partial slices from earlier local runs; "later slice wins" silently let 100 v0.6.3-era results override fresh v0.6.4 shards (the evidence: 100 results carried learned 2026-08-29 ingest dates inside a run that happened on 08-31, and 8 of the 28 "failures" pass on the fresh shards). Re-aggregated from the five real shard artifacts only: 0.958 (479/500). v0.6.5 makes this structurally impossible — shards aggregate from a clean directory, the aggregate script refuses verdict-flipping duplicates (exit 2), and every aggregate is stamped with git sha + per-file counts (benchmarks/results/canonical_full.json → aggregate_provenance).

What the 21 failures taught us (v0.6.5 — all boring fixes, Pareto-first)

Every one of the 21 real failures was reproduced, root-caused, and fixed with the boring mechanism — no new models, no embedder swap, nothing dropped:

1. Assistant messages were truncated at 800 chars — segment them instead. 7 single_session answers ("Veja", "Absinthe", "Nu, pogodi!", "@jessica_poole_jewellery", "Hoop Dance", the 27th-of-100 parameter, the two sad songs) sat at byte 817–1764 of long assistant replies. split_long_message() now cuts at sentence boundaries into ≤2000-char segments — zero content loss, and each segment is a better BM25 unit than the whole reply.
2. Relative-time questions need calendar math, not vocabulary. "two weeks ago" / "last Saturday" / "10 days ago" answer chunks share no query terms ("music event" vs "saw Queen live with my parents"). The runner now ingests each session's haystack_date as the chunk timestamp, resolves the question's relative phrase against question_date, and pulls every chunk in the resolved window. 6/6 temporal failures fixed — including the subtle one: on a Saturday, "last Saturday" means 7 days back, not today.
3. "How much did I save?" is a difference, not a sum. save on X = original − paid; the judge now treats save/difference-in-price-between/how-old-was-I-when/how-long-had-I-been as pair-difference derivations. Word-number answers ("Two months", "three") parse too.
4. The subset-sum judge dropped the real summands. Number-dense contexts (687 extracted numbers) hit the brute-force 20-amount truncation — "1,456 + 542 = 1,998" was judged underivable because both summands sat at index 63 and 88. Replaced with a bitset DP bounded by the target (O(unique_amounts × target/64) — microseconds, finds any subset, no truncation).
5. Markdown escapes broke literal matching. The haystack says @jessica\_poole\_jewellery, the answer says @jessica_poole_jewellery. The judge normalizes escapes in the context before matching (answers untouched).
6. Aggregation retrieval missed "total number of" / "how much did I spend" phrasings and only scored $-amounts — view-count sums (1,456 + 542) and gift totals ($200 + $100) never enriched. Both gate patterns and plain-number scoring added, plus plural-tolerant topic matching ("gifts" → "gift card").

Verification: all 21 failures re-run through the exact production runner path (_run_one_question, fresh per-question DB) — 21/21 pass locally. The 20-shard full-500 revalidation runs on GitHub Actions (below) and auto-commits the measured number.

Run the full 500-Q benchmark via GitHub Actions: .github/workflows/longmemeval_canonical_full.yml — 20 shards × 25 questions in parallel (the v0.6.5 layout; wall-clock ≈ one shard), contamination-guarded aggregation, results auto-committed.

How cortexm compares (search-momentum table, honest numbers)

VoiceMem (xzf-thu/VoiceMem, Aug 2026) popularized the side-by-side memory-system comparison. We borrowed the format — every competitor number below is quoted from their README/tech report, our numbers are measured, and the benchmarks are different, so rows are labeled, not conflated:

Why no voice? VoiceMem's pitch is memory for voice agents — it owns the ASR, voiceprint, scene, and emotion stack. cortexm's pitch is memory as a substrate: it's voice-agnostic and modality-agnostic by design. You don't need to route your users' audio through a memory system to get long-term recall — paste the transcript (or the ASR of your choice) and the trace/VSA/verbatim tiers do the remembering. If you're building a real-time voice agent and want memory co-located with the VAD loop, VoiceMem is the specialized tool; if you want deterministic, auditable memory under any front-end — text today, voice tomorrow, whatever comes next — that's this.

Known boundaries (the short list)

Full detail: docs/FAILURE_MODES.md — every failure tied to a public benchmark question.

1. The extractor is a 61-pattern lookup, not a language model. Phrasings outside the pattern library are silently dropped at ingest (e.g. "Anna has a cat named Whiskers") — they remain retrievable via verbatim/BM25 chunk recall, but never become structured facts. This is the price of μ=0: no generativity, no fabrication, no drift.
2. ZK proofs are trusted-prover attestations. The v0.6.4 backend (Pedersen + Sigma protocols on secp256k1) is sound at the commitment layer — challenges are bound to announcements, both OR-proof branches verify, H has no known discrete log, thresholds are enforced — but the linkage between committed values and store rows is established at prove-time by the prover. Verify the integration layer before trusting it against a malicious host.
3. Set membership reveals the leaf index. The value stays hidden (random-blinding Pedersen + equality proof); the position in the set does not. Position-hiding needs a ZK-friendly Merkle construction — documented future work.
4. No cross-user inference, ever. Every fact is scoped by user_id; the scope sandbox turns empty scopes into empty results (not unrestricted fallbacks). This is a feature, and it also means no "insight across users" stories.
5. Compression tiers are documented, not default. int8/binary quantization trade recall for space (see docs/COMPRESSION.md); the default build keeps full-precision embeddings because the benchmark headroom doesn't justify the loss yet.
6. Judge coverage is rule-based. The deterministic judge answers via strategy dispatch (bool/list/nugget/sum_or_diff/percentage/numeric_agg/holiday/paren). Questions outside those strategies score 0 even when retrieval succeeded — the failure is honest, the number is real.

When to use cortexm vs Mem0 / Zep / Chroma

• Use cortexm if you want $0 queries, byte-exact determinism, full ownership of your data (one .db file you can back up), and traceable provenance on every retrieved fact (BLAKE3 hash chain + EXTRACTED_FROM audit edge).
• Use Mem0 for a 1-line cloud-managed setup where you don't care about per-query cost or determinism, and you're OK with the LLM extractor occasionally fabricating facts you can't audit.
• Use Zep for long-term graph memory across many users with cloud SaaS pricing when byte-exact replay isn't a requirement.
• Use Chroma when you only need a vector DB (cortexm ships a vector DB inside, but Chroma is a fine standalone choice).

Drop-in plugins (already shipped)

• Mem0-compatible surface: from cortexm import Memory — drop-in for from mem0 import Memory
• LangChain: plugins/langchain → context-m-langchain on PyPI
• LlamaIndex: plugins/llamaindex → postprocessor
• OpenAI Agents SDK: plugins/openai_agents
• Claude Code: plugins/context-m-claude — session lifecycle hooks
• MCP server: cortexm serve (stdio JSON-RPC, zero extra dependencies)
• REST server: cortexm serve-rest — OpenAPI 3.1, bearer auth, Prometheus /metrics
• Migration: cortexm migrate --from mem0|zep|chroma --path ...

Documentation

The README is intentionally short. Everything else lives in docs/:

Examples & tests

• examples/ — runnable scripts, offline, no API keys (01_quickstart → 20_agent_session)
• tests/ — 733 tests: fabric + enterprise + PPR + concurrency + sandbox + enrichment + WAL crash-recovery + migration + CRDT federation + Rust parity + ZK soundness/forgery + public-API smoke
• cortexm/experimental/ — deterministic research borrows (graph recall, coherence) — μ=0 or it doesn't ship
• leaderboard/ — self-hosted benchmark site (rebuild: python leaderboard/build.py; open leaderboard/index.html)
• AGENTS.md — how AI coding agents should interact with this repo (2026 standard)
• CONTRIBUTING.md — contribution guide

License

Apache 2.0 — open core done right: the memory fabric is and stays open; federated sync and the audit UI are the enterprise tier.