I got tired of agent memory being demoed like a scrapbook. The agent sees a fact, stores a summary, retrieves it later, and everyone nods because the demo remembered the user's favorite framework. That is the easy part. The part that bothers me starts after the demo, when a temporary workaround, a bad tool result, or a half-true preference comes back three days later wearing the costume of "memory."
That is the pain NeuroMem is built around. Long-running agents forget, but they also remember things they had no right to keep. They turn "use mock data for this run" into a permanent preference. They treat "this fixed the bug once" as a general rule. They preserve stale facts because overwriting the row would also erase the only evidence that explains how the row got there.
So I stopped thinking about memory as storage. Storage was not the missing piece. The missing piece was a write path with authority, evidence, rejection, lifecycle, and audit. In NeuroMem, memory is a mutation the runtime has to defend. The v0.2.0 runtime makes that boundary sharper: source evidence stays append-only, and the current worldview is a projection over that evidence, not a mutable table of truths.
Agent memory is usually sold as better recall. The product problem is write authority and current belief: what gets remembered, which candidate becomes the active worldview, why it was retrieved, when it should be suppressed, and how to prove what happened afterward.
temporary facts stale preferences wrong tool output worldview drift append-only evidence ledgered projection Summaries become durable facts before anyone asks whether they deserve to persist.
Events stay append-only while the resolver chooses the active candidate for a slot.
Queries, forgetting, sleep, outcomes, and replay point back to traces and ledger events.
The agent remembers faster, but the system still cannot explain why the memory exists.
Observe, route, commit, retrieve, forget, after_turn, sleep, and replay are separate runtime actions.
SQLite, traces, CLI, Worldview Snapshot, activation retrieval, lifecycle policy, ledger, and optional adapters.
The public package imports as neuromem_runtime.
The memory field is moving fast, but the center of gravity is still recall
I am not building NeuroMem in a vacuum. MemGPT made the operating-system metaphor feel real: context becomes something the agent manages across tiers instead of a single prompt you keep stuffing. Letta turned that idea into a practical framework with core and archival memory. That work changed how people talk about stateful agents. LangMem then made this more application-facing by giving agents tools to extract facts, learn behavioral patterns, and refine prompts over time.
The 2025 wave pushed harder on scale and structure. Mem0 framed production memory around extracting, consolidating, and retrieving salient facts from ongoing conversations, with a graph variant for relational context. A-Mem used a Zettelkasten-like approach so new memories can create notes, tags, links, and evolve older memory representations. Zep and Graphiti moved toward temporal knowledge graphs that keep historical relationships instead of flattening everything into static chunks. HippoRAG 2 made the "RAG to memory" shift explicit by combining graph activation with deeper passage integration for factual, associative, and sense-making tasks. MemoryOS made the operating-system analogy even more literal with short-term, mid-term, and long-term personal memory tiers.
By late 2025, the field had enough work that a survey, Memory in the Age of AI Agents, had to separate agent memory from plain RAG and context engineering. In early 2026, AgeMem went further and treated memory operations as tool-based actions learned inside the agent's policy. That is close to the direction I care about: memory is no longer just a database lookup.
My disagreement is about where the product pressure lands. Most of this progress improves what memory can retrieve, how it organizes experience, or how an agent decides when to call memory tools. NeuroMem starts one layer lower. Before I worry about the smartest recall policy, I want the runtime to answer a rougher question: was this evidence allowed to change the agent's current worldview?
Context tiers, graph memory, temporal graphs, and learned memory actions are improving quickly.
The runtime makes write authority, rejection, worldview candidates, lifecycle, and replay part of the normal path.
The dangerous memory is often the one that sounds reasonable
Most bad memory does not look malicious. It looks helpful. A user says "prefer the local mock provider today" because they are offline. A tool fails once and the agent records the workaround as the fix. A model compresses a messy debugging session into a neat sentence that leaves out the warning. Later, retrieval finds that sentence and the next run treats it as project knowledge.
This is why "just add memory" feels wrong to me. A long-running agent is already carrying chat history, tool output, preferences, files, errors, and half-finished plans. If the memory layer does not separate evidence from belief, current state from durable state, and retrieval from mutation, it gives the model a more permanent way to be wrong.
NeuroMem starts with a small split that matters: observe() records an immutable
experience event, and observe_and_commit() explicitly asks the runtime to validate
and persist memory from that event. Observation is evidence. Memory is a governed write. For
uncertain input, observe_and_route() adds another gate: it records the event, measures
worldview impact, and decides whether the event should remain ledger-only, append evidence, propose
a Frame, propose a worldview candidate, ask for clarification, quarantine the input, or mark
it for sleep.
memory = await nmem.MemoryRuntime.local(
namespace="demo/repo",
path="./.neuromem",
)
routed = await memory.observe_and_route({
"type": "user_preference",
"content": "User prefers brief direct answers.",
"keywords": ["style"],
})
await memory.observe_and_commit({
"type": "task_result",
"content": "Session refresh order fixed the login redirect loop.",
"task": "Fix login",
})
ctx = await memory.query(
"Have we fixed auth/session bugs before?",
lens="associative",
)
print(ctx.worldview)
print(ctx.worldview_trace)
print(ctx.prompt_sections)The write path should be harder than the recall path
I built NeuroMem around a policy executor because I do not want the LLM to be the thing that
directly edits durable memory. The model can act like a prefrontal controller: it can
propose a structured MemoryPolicy with retrieval, write, forgetting, and consolidation
intent. It does not get the storage handle.
The runtime keeps the boring checks in the trusted path. ValidatorStack
rejects writes below the confidence threshold, writes without evidence ids, unsupported operations,
cross-namespace targets, unsafe destructive updates, and consolidation plans that do not name
the clusters and target type they intend to change. A rejected policy can still leave an audit
record, but it does not leave a half-written memory card or a graph edge that future retrieval
will quietly trust.
The Worldview Impact Meter is the part that made this feel less like a storage wrapper and more like a runtime. It scores novelty, belief delta, entropy delta, contradiction, supersession, utility, propagation, source reliability, and risk. Low-impact input can stay in the ledger. Higher-impact input can become support evidence, a candidate Frame, a candidate worldview update, a clarification request, a quarantine record, or sleep priority.
This solved the thing I did not see in most memory tools: a memory write can fail closed, but the event does not disappear. The system can say, "I saw this event, but it is not allowed to become current belief in this form." When a live memory planner is missing, malformed, or unsafe, NeuroMem falls back to deterministic retrieval and routing plans. That is a different product shape from "summarize and upsert."
This is also where I differ from the parts of the current literature that make memory more agentic by letting the model decide more operations. I like that direction, especially in AgeMem, but I do not want learned memory behavior to erase the boring product contract. The agent may choose when to ask for memory work. The runtime still needs a veto.
The runtime captures what someone tried to change, then records the impact assessment.
Weak evidence, destructive updates, stale targets, and risky content do not mutate memory.
Memory, Frame, edge, lifecycle, graph, and index changes become execution records.
Hash-linked ledger events support replay, reconstruction, worldview traces, and "why" answers.
The worldview is a projection, not a table of truths
I use "worldview" in a very practical sense. It is not a philosophy module. It is the current operating view the agent gets to use: facts, preferences, constraints, procedures, schemas, hypotheses, and suppressions that have survived enough evidence pressure to appear in the prompt. The source record stays append-only. The worldview is what the runtime resolves from that record.
That gives NeuroMem a cleaner answer to a problem I kept hitting: old evidence and current belief are not the same thing. An event can remain in the ledger forever while the active worldview changes. A candidate can be useful enough to remember, but not trusted enough to become active. A stale preference can be suppressed from normal retrieval while still showing up in historical or audit views.
The machinery is small enough to inspect. A slot names the kind of belief under debate:
fact, preference, constraint, procedure,
schema, hypothesis, or suppression. Candidates
compete inside those slots. Their scores combine support, provenance, recency, utility,
lifecycle commitment, and user confirmation, then subtract contradiction, inhibition,
supersession, and staleness.
Conflict is explicit. If the top two candidates are too close, or active
contradict evidence exists, the slot is conflicted instead of quietly picking a
winner. Supersession pushes the older candidate out of the normal prompt, but the historical
and audit lenses can still show it. That is the point of the design: current state changes without
pretending the old evidence vanished.
The resolver lenses are the part I expect to use most. logical is for current facts,
preferences, and constraints. procedural is for procedures, schemas, and failure
patterns. historical keeps suppressed and superseded candidates visible.
audit adds evidence chains and rejected candidates. associative
keeps the active worldview and lower-commitment memory support together. The same memory store
can answer different questions without changing the source record.
Novelty, belief delta, contradiction, supersession, utility, source reliability, and risk decide the route.
Each slot holds candidates, selected state, confidence, evidence ids, and possible conflict.
Logical, procedural, historical, audit, and associative views resolve the same evidence differently.
Worldview slots, candidates, associative edges, and logic edges can be rebuilt from append-only journals.
The graph carries relationships a single card cannot hold
A single memory card is useful, but agents rarely fail on single facts. They fail on relationships: this fix replaced that fix, this rule came from those episodes, this procedure worked with that constraint, this older preference now conflicts with the current one. NeuroMem stores those relationships as edge evidence and materialized graph projections, not as prose hidden inside a summary.
The edge evidence model is deliberately small and inspectable. Events can
support, contradict, supersede, inhibit,
reinforce, decay, expire, restore,
generalize, or derive. Relations can be plain association, but
they can also be supports, contradicts, supersedes,
evidence_for, procedure_for, preference_of,
generalizes, or specializes. That matters: "these two memories
were nearby once" is not the same as "this one supersedes that one."
I care less about graph cleverness than about graph writes staying governed. Co-retrieval is
trace evidence by default. It does not automatically rewrite the long-term graph.
after_turn() can append success or failure evidence after a run, and
sleep() can compile repeated evidence into Frames and relations. The materialized
graph learns from use, but the source of truth is still the append-only journal.
During retrieval, the graph is not a separate magic search engine. It starts from ordinary
candidates, then runs a PPR-style activation pass over edges. Transfer is relation-aware:
supports and same_as move signal differently from
coactivated_with; procedure_for matters more for procedural recall;
preference_of matters more for preference recall; contradicts and the
wrong direction of supersedes suppress a path instead of amplifying it. The trace
records the path and the suppression reason, which is the difference between graph memory and
graph-shaped mysticism.
Cards carry evidence and recall context. Frames give candidates a typed shape for the worldview resolver.
Edge events are append-only. Associative and logic edges are projections that can be rebuilt.
Graph diffusion can surface neighbors, but worldview, lifecycle, and provenance gates still decide what enters context.
Contradicted, superseded, inhibited, archived, and obsolete memories do not get a free ride back into the prompt.
Recall without explanation is another kind of hallucination
Retrieval is where memory systems usually look best. A query matches an old fact. The agent sounds more personal. The context window gets a nice little packet. I still want that, but I want the packet to carry a resolved worldview and reasons, not vibes.
NeuroMem's base query path stays local: contextual memory cards, FTS5 and BM25 candidates, lexical and entity signals, optional dense, rewrite, or HyDE candidates, reciprocal rank fusion, graph activation, lifecycle and provenance gates, a lite rerank, then packed prompt context. Optional embedding, cross-encoder, and LLM rerank adapters can rank candidates, but they do not mutate memory.
The returned MemoryContext now carries worldview,
worldview_trace, and prompt_sections, along with selected memory
ids, score components, graph paths, suppression reasons, provenance ids, and a trace id.
to_prompt() renders the Worldview Snapshot before the supporting memory snippets.
If a bad answer happens later, I do not want to shrug and say "memory was involved." I want to
inspect which worldview slots and which memories entered the run.
The trace gets specific. Retrieval increments access counters as ledgered memory effects. It
stores hybrid scores, graph diffusion scores, inhibition scores, rejected ids, suppression
reasons, source channels, and the final context size.
after_turn() can later append success or failure outcome evidence for selected memories
from that trace. replay_trace(trace_id) is there because memory bugs should be debugged
like software bugs: with the plan, the inputs, the rejected branches, and the deltas on the table.
QueryPlanV2 -> Worldview Snapshot -> Memory Cards -> FTS5/BM25 candidates -> RRF fusion -> graph activation -> lifecycle and provenance gates -> context packing -> retrieval ledger.
The second hard part is letting memory get old
I used to think forgetting was mostly a delete button. It is not. A serious memory layer needs softer verbs. Some memories should decay because they are old. Some should be inhibited because they are suspicious. Some should be archived because they are no longer active but still explain the past. Some repeated experiences should compress into a more useful memory.
NeuroMem exposes decay, inhibit, invalidate,
archive, and compress as product forgetting paths. A
delete request is rejected by the public runtime. Forgetting appends lifecycle or
edge evidence while the source memory record stays available for audit. The ordinary path keeps
history because "we forgot this" is also something a runtime should be able to explain.
Contradiction is part of forgetting, too. observe_and_route() watches for update
language like "now", "instead", "replaces", and "supersedes". If new evidence conflicts with
retrieved memory, the runtime can append contradiction, supersession, or suppression evidence.
Normal retrieval can hide the older candidate, while the
historical and audit lenses still show how the belief changed. The
agent does not need to hold two conflicting facts in the prompt and hope the model chooses the
newer one.
Memory can be inhibited, invalidated, archived, compressed, decayed, or expired without erasing history.
Ledgered sleep can compile Frames, Procedures, Schemas, and evidence links.
Success or failure can reinforce or penalize selected memories as evidence.
The state machine came from taking memory biology seriously enough, but not literally
I am careful with neuroscience metaphors because they get cheap very quickly. NeuroMem is not trying to simulate a brain. The useful lesson I took from memory research is narrower: biological memory is not a table of permanent rows. It has encoding, consolidation, reconsolidation, suppression, forgetting, and reactivation. Those are state transitions.
Recent neuroscience keeps pushing away from the idea of a fixed memory trace. A 2024 review on memory engram stability and flexibility discusses memory updating, reconsolidation, forgetting, schema learning, linking, and representational drift. A 2024 review on active forgetting describes forgetting as an active process that can degrade or mask traces rather than a simple storage failure. A 2026 review of hippocampal systems consolidation argues that remote memory can still involve hippocampal participation, complicating the old handoff story.
That shaped NeuroMem's lifecycle design. A memory can be fresh, captured, linked, reinforced, mature, core, inhibited, obsolete, compressed, or archived only through explicit evidence. The runtime treats "sleep" as a governed consolidation pass, not a cute command name. A recent review of sleep's contribution to memory formation describes consolidation as interaction across hippocampal and neocortical systems, which maps better to replay and transition than to a cron job that rewrites summaries. Repeated experience can be compiled or linked, but the transition is ledgered. If a memory is reactivated and updated, that should look more like reconsolidation than silent overwrite.
The public sleep() path is now intentionally append-only. It does not call the old
mutable neuro_sleep() path by default, and it does not rewrite source memory maturity,
summaries, tags, or provenance. It selects high-impact, conflicted, repeated, or recently retrieved
clusters, then compiles Frames, Procedures, Schemas, and evidence links with a report. This is
not a sleep model. It is an explicit consolidation phase with source links and ledger events.
This is the part of the project I like most because it makes the implementation less fashionable and more honest. The state machine says memory has a life after insertion. It can mature, get weaker, become temporarily hidden, be compressed into a schema-like summary, or remain archived as evidence for why the agent once behaved a certain way.
Experience enters as immutable evidence before it becomes durable memory.
Repeated traces can become compiled Frames, Procedures, Schemas, and source links.
Memory can become less available without pretending the past never happened.
Reactivated memory should add evidence instead of being overwritten in place.
Local-first is about inspectability, not nostalgia
The base install is deliberately plain: pip install neuromem-runtime. It uses
SQLite and trace files. It does not need Docker, a hosted vector database, an API key,
LangGraph, or a model call to run the core path.
That choice is practical, not ideological. If I am debugging why an agent changed memory, I want files I can inspect, a database I can query, a ledger I can replay, and a package I can test without a provider being online. Cloud services and orchestration frameworks can sit around the runtime. They should not be the only place the truth lives.
The local database now stores more than memories. It also stores candidate Frames, edge evidence events, impact assessments, worldview slots, worldview candidates, candidate events, and materialized associative and logic edge caches. That sounds heavier than a vector store, but it buys something I care about: I can clear the caches, rebuild the worldview, and still have the source evidence.
Config, local database, traces, policy execution, worldview projection, ledger, retrieval, lifecycle, and CLI.
LangGraph, policy providers, eval extras, embeddings, and rerankers stay outside the authority boundary.
The project gave me a sharper definition of agent memory
I do not think NeuroMem is finished. The package is still alpha, and that label is useful. It keeps me honest. But building it changed what I now ask from any memory system. Can it separate evidence from current belief? Can it reject a write without losing the event? Can it show why a worldview candidate won? Can it let memory decay without deleting the audit trail? Can I replay the story after something goes wrong?
This connects directly to the rest of my agent work. Bio-agent made me care about evidence objects and reviewable runs. NeuroMem applies the same pressure to memory. The convenient context that helps an agent today should not quietly become tomorrow's durable truth. And if it does become truth, I want the runtime to show the evidence chain.
- MemGPT: Towards LLMs as Operating Systems
- Mem0: Building Production-Ready AI Agents with Scalable Long-Term Memory
- A-Mem: Agentic Memory for LLM Agents
- LangMem
- Zep and Graphiti: Temporal Knowledge Graph Architecture for Agent Memory
- HippoRAG 2: From RAG to Memory
- MemoryOS: Memory OS of AI Agent
- Memory in the Age of AI Agents
- AgeMem: Agentic Memory Learning
- Memory engram stability and flexibility
- Active forgetting and neuropsychiatric diseases
- Role of the hippocampus in systems consolidation of remote fear memory
- Sleep's contribution to memory formation
The line I am drawing
I do not want agent memory to feel magical. I want it to feel accountable. The model can suggest what might be worth remembering. The runtime should decide whether that evidence can change the worldview, which lens should expose it, why it came back, and what evidence it can show when someone asks.