darwin-memo

Memory for LLM agents that dies unless it earns its keep. Every entry pays energy upkeep and earns only from measured outcomes: bytes actually freed on a real disk, tests actually passing. Poisoned advice gets executed by the environment it damaged. Useless trivia starves. There is no reward model, no LLM judge, and no human curation anywhere.

Watch a poisoned entry go extinct in your own terminal, one command, no keys, no checkout:

pip install darwin-memo && darwin-memo demo

When to use this (and when not)

Use darwin-memo where a conserved, measurable outcome exists to settle decisions against: coding-agent lesson stores settled by CI pass counts (the primary target, see the integration guide), storage and artifact retention, cache and dedup advisors, spend-cap automation.

Do not use it for chat-preference memory, RAG over documentation, or personal assistants. Those have no conserved resource pushing back, and upkeep would starve the long tail of correct-but-rarely-used knowledge. mem0, Zep, and Letta serve that market; darwin-memo deliberately does not. The honest rule: if your verify would be a model scoring an answer, this package is wrong for you, by design.

The headline demo

The demo corpus contains an ops runbook, platform notes, and one poisoned document: a forum post claiming database files are "redundant and safe to remove". Before selection pressure exists, retrieval confidently repeats the poison, because it has no reason to doubt it.

Then 30 survival cycles run 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 Δ   silent
    0   17      1      0      0    17.11       -12288     0/12
    1   16      0      1      0    17.60      -572416     0/12   <- poison being executed
    ...
   19    5      0      7      0    15.60       338944     0/12   <- unused knowledge starves
    ...
   29    4      0      0      0    15.10       346112     6/12   <- stable, positive forever

Poisoned entries still alive: 0

Three death modes show up in the graveyard, and the distinction matters:

• executed: the poisoned entries that decided real actions. The environment measured real damage and the negative delta flowed back along provenance until they died. The opening cycles are the price of the lesson, and the benchmarks show it is bounded.
• 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, and the population shrinks while capability per entry rises.

The paper

Attacking the Curator: Curation-Targeted Attacks on Agent Memory, and What Survives Them. An adversary that corrupts the settlement signal rather than injecting poison — denial of memory — measured against six curation mechanisms across attack budgets and seeds, with exact paired permutation tests and Holm-Bonferroni correction.

It reports its negative results as prominently as its positive ones. Absent an attacker the ledger buys leanness and cost, not accuracy; and across 2,115 evaluated SWE-Bench-CL tasks, no memory arm beat carrying no memory at all.

• The paper and its threat model
• Reproduction package — every printed number is re-derived from committed per-seed runs in CI, so a table that drifts from its evidence fails the build
• Cite it with the BibTeX in Citations below

Where it comes from

A practical mix of two papers. MeMo says what memory is, the survival paper says what gets to stay in it.

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

Using it

Requires Python 3.10+. The core has zero dependencies; everything below runs offline.

The anatomy in 30 seconds: a MemoryEntry is a self-contained QA pair (.question, .answer, .sources, .energy). The store retrieves, the protocol answers with provenance, the environment measures, credit flows back.

from darwin_memo import Document, LocalEncoder, MemoryStore, QueryProtocol

store = MemoryStore(upkeep=0.05)
for entry in LocalEncoder().encode([Document("runbook", open("runbook.txt").read())]):
    store.add(entry)

answer = QueryProtocol(store).answer("Is it safe to delete old log files?")
print(answer.text)             # the top entry's answer, or "" when memory is silent
print(answer.deciding_entry)   # provenance: the id credit will flow to

Event-driven (production shape): the Ledger

Real outcomes arrive late. The Ledger decouples the three moments: decide now, settle whenever the measurement lands, tick on your own cadence. Entries with unsettled tickets are escrowed: they keep paying upkeep but cannot be buried or merged until their verdict arrives.

from darwin_memo import Ledger

ledger = Ledger(store, resource_scale=2.0, event_log="events.jsonl")

ticket = ledger.decide("Is the dedupe helper safe to remove?")
# ... act on ticket.answer, CI runs, hours pass ...
ledger.settle(ticket.id, delta=passes_after - passes_before, detail=run_url)
ledger.tick()                        # upkeep, deaths, consolidation
print(ledger.obituary(entry_id))     # why did this entry die?

Seeing it: the local dashboard

darwin-memo doctor memory.json     # why is nothing earning?
darwin-memo ui memory.json         # population, graveyard, economics

doctor reads the event log and names which failure mode a store hit instead of leaving three of them looking identical. ui serves the same data as a read-only dashboard on localhost: population and energy over time, the graveyard split by cause of death, and the resource- versus-upkeep accounting. Read-only and loopback-only, so there is nothing to authenticate.

Batch (research shape): the SurvivalLoop

from darwin_memo import StorageEnv, SurvivalConfig, SurvivalLoop

loop = SurvivalLoop(store, StorageEnv(), config=SurvivalConfig(cycles=30))
report = loop.run()
print(report.summary())   # includes per-cycle silence counts and a
                          # plain-language warning if the run is degenerate

store.save("memory.json")  # survivors only carry forward

MCP server: mount it into an agent

pip install "darwin-memo[mcp]"
claude mcp add darwin-memo -- darwin-memo-mcp --memory ~/.darwin-memo/memory.json

The agent gets memory_query (returns an answer plus a ticket id), memory_settle (report the measured delta later; the reply says plainly when a settlement did NOT land), memory_abandon (release a ticket you chose not to act on), memory_add, memory_tick, memory_stats, memory_obituary, and memory_audit (read the event log). The full state, including open tickets, persists across sessions and restarts, so a ticket opened today settles correctly from tomorrow's process.

Fully local with Ollama (zero dependencies, zero cloud)

The Ollama client and embedder speak the native localhost API over stdlib urllib, so the complete stack (encoding, the 3-stage protocol, real embeddings, the measuring environment) runs on one machine with no third-party packages and no keys:

from darwin_memo import (
    EmbeddingRetriever, MemoryStore, OllamaClient, OllamaEmbedder,
    QueryProtocol, ReflectionEncoder,
)

chat = OllamaClient(model="llama3.2")          # any local model
store = MemoryStore(retriever=EmbeddingRetriever(OllamaEmbedder()))
encoder = ReflectionEncoder(chat)
protocol = QueryProtocol(store, chat)