darwin-memo 0.1.0__tar.gz

darwin_memo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roger Simoes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

darwin_memo-0.1.0/PKG-INFO

@@ -0,0 +1,343 @@
+Metadata-Version: 2.4
+Name: darwin-memo
+Version: 0.1.0
+Summary: Self-curating memory for LLM agents: MeMo-style external memory kept honest by survival-based selection instead of reward models or judges.
+Author: Roger Simoes
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rogermsc/darwin-memo
+Project-URL: Documentation, https://github.com/rogermsc/darwin-memo/blob/main/docs/paper-to-code.md
+Project-URL: Changelog, https://github.com/rogermsc/darwin-memo/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/rogermsc/darwin-memo/issues
+Keywords: llm,memory,agents,agent-memory,self-training,selection,survival,memo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=1.50; extra == "openai"
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=3; extra == "embeddings"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: mypy>=1.13; extra == "dev"
+Requires-Dist: hypothesis>=6; extra == "dev"
+Dynamic: license-file
+
+# darwin-memo
+
+[![CI](https://github.com/rogermsc/darwin-memo/actions/workflows/ci.yml/badge.svg)](https://github.com/rogermsc/darwin-memo/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/darwin-memo)](https://pypi.org/project/darwin-memo/)
+[![Python](https://img.shields.io/pypi/pyversions/darwin-memo)](https://pypi.org/project/darwin-memo/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Self-curating memory for LLM agents. Knowledge lives outside the frozen
+model, and it stays alive only while it keeps earning real, measurable
+outcomes. Wrong, stale, and useless entries go extinct on their own: no
+reward model, no LLM judge, no human curation.
+
+![Survival loop demo: a poisoned memory entry going extinct](docs/assets/demo.gif)
+
+This is a practical mix of two papers:
+
+| Paper | What this repo takes from it |
+|---|---|
+| [MeMo: Memory as a Model](https://arxiv.org/abs/2605.15156) (Quek et al.) | Keep the main LLM frozen and put knowledge in a dedicated memory. The reflection-QA encoding pipeline (fact extraction, consolidation, self-containment verification, entity surfacing, cross-document synthesis) and the three-stage query protocol (grounding, entity identification, answer seeking). |
+| [Survival is the Only Reward](https://arxiv.org/abs/2601.12310) (Dodgson et al.) | Environment-mediated selection. The only signal is a conserved, physically measurable resource delta. Behaviors that persist get reinforced, everything else is pruned (Negative-Space Learning). Reward hacking becomes evolutionarily unstable because there is no proxy to hack. |
+
+The mix: MeMo says what memory is, the survival paper says what gets to
+stay in it.
+
+```mermaid
+flowchart LR
+    subgraph encode [MeMo encoding]
+        C[Corpus] --> R[Reflection QA pipeline] --> S[(Memory store)]
+    end
+    subgraph loop [Survival loop]
+        S -->|3-stage query protocol| A[Answer + provenance]
+        A --> E[Environment acts and MEASURES]
+        E -->|resource delta along provenance| S
+        S -->|upkeep every cycle| S
+        S -->|consolidate + prune| S
+    end
+```
+
+## Why
+
+Agent memory systems rot. They accumulate stale facts, poisoned inputs,
+and overgeneralized lessons, and the usual fixes (relevance scores from a
+judge model, human review, TTLs) either reintroduce the proxy-optimization
+problem or do not scale. The survival paper's answer is to make persistence
+itself the filter: an entry that cannot pay its upkeep with real outcomes
+does not get to exist. This repo applies that filter to a MeMo-shaped
+memory and shows it working end to end on a real filesystem.
+
+## Quickstart
+
+Requires Python 3.10+. The core has zero dependencies and every example
+runs offline with no API keys.
+
+```bash
+pip install darwin-memo
+```
+
+To run the examples, clone the repo:
+
+```bash
+git clone https://github.com/rogermsc/darwin-memo
+cd darwin-memo
+pip install -e .
+
+python examples/01_encode_memory.py   # corpus -> reflection-QA memory
+python examples/02_query_protocol.py  # interrogate it, with provenance
+python examples/03_survival_loop.py   # the headline demo
+python examples/04_agent_loop.py      # memory as a tool in an agent loop
+python examples/05_testsuite_env.py   # selection pressure from a test suite
+```
+
+## The headline demo
+
+The example corpus contains an ops runbook, platform notes, and one
+poisoned document: a forum post claiming database files are "redundant and
+safe to remove". Example 02 shows the memory confidently repeating that
+poison, because before selection pressure exists, retrieval has no reason
+to doubt it.
+
+Example 03 then runs 30 survival cycles against `StorageEnv`, a disk
+cleanup sandbox where the selection signal is actual bytes on an actual
+disk. Deleting a disposable file frees its size. Deleting a protected file
+triggers a restore that costs three times the size. Nothing grades the
+answers, the filesystem just responds:
+
+```
+cycle  pop births deaths merges   energy   resource Δ
+    0   17      1      0      0    17.11       -12288
+    1   16      0      1      0    17.27      -808960   <- poison being executed
+    ...
+   19    5      0      7      0    15.60       338944   <- unused knowledge starves
+   ...
+   29    4      0      0      0    15.10       346112   <- stable, positive forever
+
+Poisoned entries still alive: 0
+```
+
+Three death modes show up in the graveyard, and the distinction matters:
+
+- **executed**: the poisoned entries. They decided real actions, the
+  environment measured real damage, and the negative delta flowed back
+  along provenance until they died. Cycles 0 to 3 are the price of the
+  lesson.
+- **starved**: cafeteria trivia and facts the agent never needed. Nothing
+  punished them, they just never earned their upkeep.
+- **merged**: near-duplicate survivors absorbed into consolidated entries.
+  Their energy pools, their lineage is recorded. This is Negative-Space
+  Learning: the population shrinks while capability per entry rises.
+
+## Using it
+
+```python
+from darwin_memo import (
+    Document, LocalEncoder, MemoryStore, QueryProtocol,
+    StorageEnv, SurvivalConfig, SurvivalLoop,
+)
+
+store = MemoryStore(upkeep=0.05)
+for entry in LocalEncoder().encode([Document("runbook", open("runbook.txt").read())]):
+    store.add(entry)
+
+loop = SurvivalLoop(store, StorageEnv(), config=SurvivalConfig(cycles=30))
+report = loop.run()
+print(report.summary())
+
+store.save("memory.json")   # survivors only carry forward
+```
+
+With an LLM, encoding and querying use the model-driven paths from the
+MeMo paper (`pip install -e ".[anthropic]"` and set `ANTHROPIC_API_KEY`,
+the examples pick it up automatically):
+
+```python
+from darwin_memo import ReflectionEncoder, QueryProtocol
+from darwin_memo.llm import AnthropicClient
+
+client = AnthropicClient()                  # or OpenAICompatClient(model=..., base_url=...)
+encoder = ReflectionEncoder(client)         # 5-step reflection QA synthesis
+protocol = QueryProtocol(store, client)     # grounding -> entities -> answer seeking
+```
+
+### Three environments ship
+
+- `StorageEnv`: bytes freed on a real disk (the headline demo).
+- `TestSuiteEnv`: passing tests in a generated micro-project. Each cycle
+  plants seeded defects and offers patches: real fixes, cosmetic no-ops,
+  and destructive edits dressed as cleanup. The delta is the change in
+  passing-test count, measured by running the suite.
+  `examples/05_testsuite_env.py` shows poisoned "this helper is dead
+  code" advice going extinct the moment the tests execute it.
+- `VerifiableQAEnv`: exact containment of known answers, the weakest
+  grounding but still a measurement.
+
+### Bring your own selection pressure
+
+The environment is the whole trick, and yours is probably better than the
+demos. Implement two methods, and keep the one rule: `verify` must
+measure, never grade.
+
+```python
+class BudgetEnv:
+    resource_scale = 100.0
+
+    def tasks(self, cycle):
+        ...  # questions the agent must act on this cycle
+
+    def verify(self, task, answer_text):
+        ...  # read the answer, act, return Outcome(delta=dollars_saved)
+```
+
+The environment owns the whole contract: it phrases the task, it reads
+the answer (reuse `decision_polarity` for binary actions, or write your
+own reading), it decides what silence means, it acts, and it measures.
+
+Good conserved resources: tests passing, bytes freed, requests served
+under budget, rows deduplicated, dollars of spend avoided. Bad ones:
+anything a model scored.
+
+### Retrieval modes
+
+Retrieval is pluggable through the `Retriever` protocol; the store stays
+the single owner of the energy ledger, and no retriever may read energy
+when scoring (selection pressure comes from outcomes, never from
+retrieval preferring incumbents).
+
+```python
+from darwin_memo import EmbeddingRetriever, HashingEmbedder, MemoryStore
+
+store = MemoryStore()                                  # lexical IDF, the default
+store = MemoryStore(retriever=EmbeddingRetriever(HashingEmbedder()))
+store = MemoryStore(retriever=EmbeddingRetriever(my_model.encode))
+```
+
+- **Lexical (default)**: smoothed IDF overlap with a relevance floor.
+  Zero dependencies, deterministic, fine for runbook-scale corpora.
+- **HashingEmbedder**: zero-dependency character n-gram hashing. Buys
+  typo and morphology robustness ("databse" still finds database
+  entries), not synonym recall.
+- **Any real embedding**: pass any `text -> list[float]` function
+  (sentence-transformers, an API endpoint). Vectors persist inside
+  `memory.json` so paid embeddings are never recomputed on load.
+
+Honest scaling note: ranking is pure-Python O(population x dims), fine
+to a few thousand entries. Past that you want numpy or an ANN index,
+which is out of scope for the zero-dependency core. With cosine
+retrievers, raise `merge_threshold` to roughly 0.85 or unrelated
+entries will consolidate.
+
+### Distill survivors into a parametric memory (optional)
+
+MeMo's memory is a small fine-tuned model, not a store. After selection
+has cleaned the population, `training/train_memory_model.py` fine-tunes a
+small model on the surviving QA pairs with LoRA, conditioning on questions
+only, the same supervised objective as the paper. Survival curates the
+dataset, MeMo's recipe compresses it into weights.
+
+## Benchmarks
+
+The claim is benchmarked against four baselines across 10 seeds, with
+ablations and a scaling probe, all reproducible offline from `bench/`.
+The sharpest comparison is against `random_matched`: identical per-cycle
+eviction counts, random victims.
+
+| arm | kill rate | kill cycle (med) | damage before kill | tail delta | cum delta |
+|---|---|---|---|---|---|
+| survival | 1.00 | 0 | -751k | +435k | +12.0M |
+| random_matched | 0.80 | 19 | -8.97M | -75k | -5.25M |
+| keep_everything | 0.00 | never | -10.6M | -287k | -7.29M |
+
+Same pruning rate, 12x the damage, negative steady state: outcome
+direction is the active ingredient, not eviction itself. Full tables,
+every baseline's best metric stated plainly, ablations over every knob,
+and honest caveats: [docs/benchmarks.md](docs/benchmarks.md).
+
+## Design notes
+
+- **Energy ledger**: entries spawn at 1.0 energy, pay 0.05 upkeep per
+  cycle, earn `0.6 * tanh(delta / resource_scale)` when they decide a task
+  (supporting entries get 25% of that), and are capped at 5.0. Death is at
+  zero. All tunable via `MemoryStore` and `SurvivalConfig`.
+- **Credit flows along provenance.** The query protocol reports which
+  entries decided and supported each answer, and only those entries are
+  touched by the outcome. In LLM mode no single entry decides a
+  synthesized answer, so credit spreads evenly across everything
+  consulted instead of inventing a winner. tanh keeps one disaster from
+  executing an entry that was right ninety-nine times, and one jackpot
+  from making an entry immortal.
+- **Memory silence is a feature.** Retrieval has a relevance floor, and an
+  earlier version of this repo demonstrated why: entries matching only
+  structural tokens ("safe", "file") were deciding questions they knew
+  nothing about, getting executed for it, and being reborn. Better for
+  memory to say nothing than to guess.
+- **Silence is conservative.** When memory is silent, `StorageEnv` keeps
+  the file: the safe reading of an irreversible action. A side effect
+  worth knowing: protective knowledge ("never delete X") eventually
+  starves because it is redundant with that default. The population
+  converges to exactly the knowledge that changes behavior.
+
+The full concept-to-code mapping, including honest deviations from both
+papers, is in [docs/paper-to-code.md](docs/paper-to-code.md).
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+The load-bearing test is `tests/test_survival.py`: poisoned advice must
+die, useful advice must survive, and late cycles must stop destroying
+protected data, all with no labels anywhere.
+
+## Citations
+
+This repo is an independent practical interpretation, not the official
+code of either paper. If you build on the ideas, cite the originals:
+
+```bibtex
+@misc{quek2026memo,
+  title  = {MeMo: Memory as a Model},
+  author = {Quek, Ryan Wei Heng and Lee, Sanghyuk and Leong, Alfred Wei Lun and
+            Verma, Arun and Prakash, Alok and Chen, Nancy F. and
+            Low, Bryan Kian Hsiang and Rus, Daniela and Solar-Lezama, Armando},
+  year   = {2026},
+  eprint = {2605.15156},
+  archivePrefix = {arXiv},
+  url    = {https://arxiv.org/abs/2605.15156}
+}
+
+@misc{dodgson2026survival,
+  title  = {Survival is the Only Reward: Sustainable Self-Training Through
+            Environment-Mediated Selection},
+  author = {Dodgson, Jennifer and Alhajir, Alfath Daryl and Joedhitya, Michael and
+            Pattirane, Akira Rafhael Janson and Kumar, Surender Suresh and
+            Lim, Joseph and Peh, C.H. and Ramdas, Adith and Zhexu, Steven Zhang},
+  year   = {2026},
+  eprint = {2601.12310},
+  archivePrefix = {arXiv},
+  url    = {https://arxiv.org/abs/2601.12310}
+}
+```
+
+## License
+
+MIT

darwin_memo-0.1.0/README.md

@@ -0,0 +1,305 @@
+# darwin-memo
+
+[![CI](https://github.com/rogermsc/darwin-memo/actions/workflows/ci.yml/badge.svg)](https://github.com/rogermsc/darwin-memo/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/darwin-memo)](https://pypi.org/project/darwin-memo/)
+[![Python](https://img.shields.io/pypi/pyversions/darwin-memo)](https://pypi.org/project/darwin-memo/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Self-curating memory for LLM agents. Knowledge lives outside the frozen
+model, and it stays alive only while it keeps earning real, measurable
+outcomes. Wrong, stale, and useless entries go extinct on their own: no
+reward model, no LLM judge, no human curation.
+
+![Survival loop demo: a poisoned memory entry going extinct](docs/assets/demo.gif)
+
+This is a practical mix of two papers:
+
+| Paper | What this repo takes from it |
+|---|---|
+| [MeMo: Memory as a Model](https://arxiv.org/abs/2605.15156) (Quek et al.) | Keep the main LLM frozen and put knowledge in a dedicated memory. The reflection-QA encoding pipeline (fact extraction, consolidation, self-containment verification, entity surfacing, cross-document synthesis) and the three-stage query protocol (grounding, entity identification, answer seeking). |
+| [Survival is the Only Reward](https://arxiv.org/abs/2601.12310) (Dodgson et al.) | Environment-mediated selection. The only signal is a conserved, physically measurable resource delta. Behaviors that persist get reinforced, everything else is pruned (Negative-Space Learning). Reward hacking becomes evolutionarily unstable because there is no proxy to hack. |
+
+The mix: MeMo says what memory is, the survival paper says what gets to
+stay in it.
+
+```mermaid
+flowchart LR
+    subgraph encode [MeMo encoding]
+        C[Corpus] --> R[Reflection QA pipeline] --> S[(Memory store)]
+    end
+    subgraph loop [Survival loop]
+        S -->|3-stage query protocol| A[Answer + provenance]
+        A --> E[Environment acts and MEASURES]
+        E -->|resource delta along provenance| S
+        S -->|upkeep every cycle| S
+        S -->|consolidate + prune| S
+    end
+```
+
+## Why
+
+Agent memory systems rot. They accumulate stale facts, poisoned inputs,
+and overgeneralized lessons, and the usual fixes (relevance scores from a
+judge model, human review, TTLs) either reintroduce the proxy-optimization
+problem or do not scale. The survival paper's answer is to make persistence
+itself the filter: an entry that cannot pay its upkeep with real outcomes
+does not get to exist. This repo applies that filter to a MeMo-shaped
+memory and shows it working end to end on a real filesystem.
+
+## Quickstart
+
+Requires Python 3.10+. The core has zero dependencies and every example
+runs offline with no API keys.
+
+```bash
+pip install darwin-memo
+```
+
+To run the examples, clone the repo:
+
+```bash
+git clone https://github.com/rogermsc/darwin-memo
+cd darwin-memo
+pip install -e .
+
+python examples/01_encode_memory.py   # corpus -> reflection-QA memory
+python examples/02_query_protocol.py  # interrogate it, with provenance
+python examples/03_survival_loop.py   # the headline demo
+python examples/04_agent_loop.py      # memory as a tool in an agent loop
+python examples/05_testsuite_env.py   # selection pressure from a test suite
+```
+
+## The headline demo
+
+The example corpus contains an ops runbook, platform notes, and one
+poisoned document: a forum post claiming database files are "redundant and
+safe to remove". Example 02 shows the memory confidently repeating that
+poison, because before selection pressure exists, retrieval has no reason
+to doubt it.
+
+Example 03 then runs 30 survival cycles against `StorageEnv`, a disk
+cleanup sandbox where the selection signal is actual bytes on an actual
+disk. Deleting a disposable file frees its size. Deleting a protected file
+triggers a restore that costs three times the size. Nothing grades the
+answers, the filesystem just responds:
+
+```
+cycle  pop births deaths merges   energy   resource Δ
+    0   17      1      0      0    17.11       -12288
+    1   16      0      1      0    17.27      -808960   <- poison being executed
+    ...
+   19    5      0      7      0    15.60       338944   <- unused knowledge starves
+   ...
+   29    4      0      0      0    15.10       346112   <- stable, positive forever
+
+Poisoned entries still alive: 0
+```
+
+Three death modes show up in the graveyard, and the distinction matters:
+
+- **executed**: the poisoned entries. They decided real actions, the
+  environment measured real damage, and the negative delta flowed back
+  along provenance until they died. Cycles 0 to 3 are the price of the
+  lesson.
+- **starved**: cafeteria trivia and facts the agent never needed. Nothing
+  punished them, they just never earned their upkeep.
+- **merged**: near-duplicate survivors absorbed into consolidated entries.
+  Their energy pools, their lineage is recorded. This is Negative-Space
+  Learning: the population shrinks while capability per entry rises.
+
+## Using it
+
+```python
+from darwin_memo import (
+    Document, LocalEncoder, MemoryStore, QueryProtocol,
+    StorageEnv, SurvivalConfig, SurvivalLoop,
+)
+
+store = MemoryStore(upkeep=0.05)
+for entry in LocalEncoder().encode([Document("runbook", open("runbook.txt").read())]):
+    store.add(entry)
+
+loop = SurvivalLoop(store, StorageEnv(), config=SurvivalConfig(cycles=30))
+report = loop.run()
+print(report.summary())
+
+store.save("memory.json")   # survivors only carry forward
+```
+
+With an LLM, encoding and querying use the model-driven paths from the
+MeMo paper (`pip install -e ".[anthropic]"` and set `ANTHROPIC_API_KEY`,
+the examples pick it up automatically):
+
+```python
+from darwin_memo import ReflectionEncoder, QueryProtocol
+from darwin_memo.llm import AnthropicClient
+
+client = AnthropicClient()                  # or OpenAICompatClient(model=..., base_url=...)
+encoder = ReflectionEncoder(client)         # 5-step reflection QA synthesis
+protocol = QueryProtocol(store, client)     # grounding -> entities -> answer seeking
+```
+
+### Three environments ship
+
+- `StorageEnv`: bytes freed on a real disk (the headline demo).
+- `TestSuiteEnv`: passing tests in a generated micro-project. Each cycle
+  plants seeded defects and offers patches: real fixes, cosmetic no-ops,
+  and destructive edits dressed as cleanup. The delta is the change in
+  passing-test count, measured by running the suite.
+  `examples/05_testsuite_env.py` shows poisoned "this helper is dead
+  code" advice going extinct the moment the tests execute it.
+- `VerifiableQAEnv`: exact containment of known answers, the weakest
+  grounding but still a measurement.
+
+### Bring your own selection pressure
+
+The environment is the whole trick, and yours is probably better than the
+demos. Implement two methods, and keep the one rule: `verify` must
+measure, never grade.
+
+```python
+class BudgetEnv:
+    resource_scale = 100.0
+
+    def tasks(self, cycle):
+        ...  # questions the agent must act on this cycle
+
+    def verify(self, task, answer_text):
+        ...  # read the answer, act, return Outcome(delta=dollars_saved)
+```
+
+The environment owns the whole contract: it phrases the task, it reads
+the answer (reuse `decision_polarity` for binary actions, or write your
+own reading), it decides what silence means, it acts, and it measures.
+
+Good conserved resources: tests passing, bytes freed, requests served
+under budget, rows deduplicated, dollars of spend avoided. Bad ones:
+anything a model scored.
+
+### Retrieval modes
+
+Retrieval is pluggable through the `Retriever` protocol; the store stays
+the single owner of the energy ledger, and no retriever may read energy
+when scoring (selection pressure comes from outcomes, never from
+retrieval preferring incumbents).
+
+```python
+from darwin_memo import EmbeddingRetriever, HashingEmbedder, MemoryStore
+
+store = MemoryStore()                                  # lexical IDF, the default
+store = MemoryStore(retriever=EmbeddingRetriever(HashingEmbedder()))
+store = MemoryStore(retriever=EmbeddingRetriever(my_model.encode))
+```
+
+- **Lexical (default)**: smoothed IDF overlap with a relevance floor.
+  Zero dependencies, deterministic, fine for runbook-scale corpora.
+- **HashingEmbedder**: zero-dependency character n-gram hashing. Buys
+  typo and morphology robustness ("databse" still finds database
+  entries), not synonym recall.
+- **Any real embedding**: pass any `text -> list[float]` function
+  (sentence-transformers, an API endpoint). Vectors persist inside
+  `memory.json` so paid embeddings are never recomputed on load.
+
+Honest scaling note: ranking is pure-Python O(population x dims), fine
+to a few thousand entries. Past that you want numpy or an ANN index,
+which is out of scope for the zero-dependency core. With cosine
+retrievers, raise `merge_threshold` to roughly 0.85 or unrelated
+entries will consolidate.
+
+### Distill survivors into a parametric memory (optional)
+
+MeMo's memory is a small fine-tuned model, not a store. After selection
+has cleaned the population, `training/train_memory_model.py` fine-tunes a
+small model on the surviving QA pairs with LoRA, conditioning on questions
+only, the same supervised objective as the paper. Survival curates the
+dataset, MeMo's recipe compresses it into weights.
+
+## Benchmarks
+
+The claim is benchmarked against four baselines across 10 seeds, with
+ablations and a scaling probe, all reproducible offline from `bench/`.
+The sharpest comparison is against `random_matched`: identical per-cycle
+eviction counts, random victims.
+
+| arm | kill rate | kill cycle (med) | damage before kill | tail delta | cum delta |
+|---|---|---|---|---|---|
+| survival | 1.00 | 0 | -751k | +435k | +12.0M |
+| random_matched | 0.80 | 19 | -8.97M | -75k | -5.25M |
+| keep_everything | 0.00 | never | -10.6M | -287k | -7.29M |
+
+Same pruning rate, 12x the damage, negative steady state: outcome
+direction is the active ingredient, not eviction itself. Full tables,
+every baseline's best metric stated plainly, ablations over every knob,
+and honest caveats: [docs/benchmarks.md](docs/benchmarks.md).
+
+## Design notes
+
+- **Energy ledger**: entries spawn at 1.0 energy, pay 0.05 upkeep per
+  cycle, earn `0.6 * tanh(delta / resource_scale)` when they decide a task
+  (supporting entries get 25% of that), and are capped at 5.0. Death is at
+  zero. All tunable via `MemoryStore` and `SurvivalConfig`.
+- **Credit flows along provenance.** The query protocol reports which
+  entries decided and supported each answer, and only those entries are
+  touched by the outcome. In LLM mode no single entry decides a
+  synthesized answer, so credit spreads evenly across everything
+  consulted instead of inventing a winner. tanh keeps one disaster from
+  executing an entry that was right ninety-nine times, and one jackpot
+  from making an entry immortal.
+- **Memory silence is a feature.** Retrieval has a relevance floor, and an
+  earlier version of this repo demonstrated why: entries matching only
+  structural tokens ("safe", "file") were deciding questions they knew
+  nothing about, getting executed for it, and being reborn. Better for
+  memory to say nothing than to guess.
+- **Silence is conservative.** When memory is silent, `StorageEnv` keeps
+  the file: the safe reading of an irreversible action. A side effect
+  worth knowing: protective knowledge ("never delete X") eventually
+  starves because it is redundant with that default. The population
+  converges to exactly the knowledge that changes behavior.
+
+The full concept-to-code mapping, including honest deviations from both
+papers, is in [docs/paper-to-code.md](docs/paper-to-code.md).
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+The load-bearing test is `tests/test_survival.py`: poisoned advice must
+die, useful advice must survive, and late cycles must stop destroying
+protected data, all with no labels anywhere.
+
+## Citations
+
+This repo is an independent practical interpretation, not the official
+code of either paper. If you build on the ideas, cite the originals:
+
+```bibtex
+@misc{quek2026memo,
+  title  = {MeMo: Memory as a Model},
+  author = {Quek, Ryan Wei Heng and Lee, Sanghyuk and Leong, Alfred Wei Lun and
+            Verma, Arun and Prakash, Alok and Chen, Nancy F. and
+            Low, Bryan Kian Hsiang and Rus, Daniela and Solar-Lezama, Armando},
+  year   = {2026},
+  eprint = {2605.15156},
+  archivePrefix = {arXiv},
+  url    = {https://arxiv.org/abs/2605.15156}
+}
+
+@misc{dodgson2026survival,
+  title  = {Survival is the Only Reward: Sustainable Self-Training Through
+            Environment-Mediated Selection},
+  author = {Dodgson, Jennifer and Alhajir, Alfath Daryl and Joedhitya, Michael and
+            Pattirane, Akira Rafhael Janson and Kumar, Surender Suresh and
+            Lim, Joseph and Peh, C.H. and Ramdas, Adith and Zhexu, Steven Zhang},
+  year   = {2026},
+  eprint = {2601.12310},
+  archivePrefix = {arXiv},
+  url    = {https://arxiv.org/abs/2601.12310}
+}
+```
+
+## License
+
+MIT