RootMemory

Provenance-aware memory for multi-agent AI systems. It tells corroboration apart from repetition.

pip install rootmemory

The problem

A customer writes "we're targeting October, but the date isn't final."

Agent A reads the email  ->  "the deadline is October 15"
Agent B reads Agent A    ->  "the deadline is October 15"
Agent C reads Agent B    ->  "the deadline is October 15"

Your shared memory now shows three agents agreeing. There is still only one source, and it did not say that. Every belief traces back to the same email — but a list of conclusions has forgotten that, so the system counts three votes and acts.

RootMemory keeps those numbers apart:

agreeing agents            3
supporting beliefs         3
independent evidence roots 1   <- the only number that reflects reality

Quick start

from rootmemory import RootMemory, open_memory

with open_memory("sqlite+pysqlite:///memory.db") as session:
    memory = RootMemory(session)

    research = memory.register_agent("ResearchAgent")
    risk     = memory.register_agent("RiskAgent")
    exec_    = memory.register_agent("DecisionAgent")

    # evidence from the outside world
    article = memory.create_observation("news", "Revenue may have slipped.")

    # three agents, but only the first one read the article
    b1 = memory.create_belief(research.id, "Supplier under pressure.", "risk", 0.6, [article])
    b2 = memory.create_belief(risk.id,     "Supplier is unstable.",     "risk", 0.8, [b1])
    b3 = memory.create_belief(exec_.id,    "Significant risk.",         "risk", 0.85, [b2])

    claim = memory.get_or_create_claim("risk", "Supplier is in distress.")
    for belief in (b1, b2, b3):
        memory.support_claim(claim.id, belief.id)

    verdict = memory.evaluate_claim(claim.id)

agreeing agents          3
supporting beliefs       3
independent sources      1
decision                 REJECT
why                      3 supporting beliefs descend from a single evidence source.

Add a genuinely separate source and it promotes. That is the entire idea.

How it works

Four objects, one rule.

Object	What it is
Observation	evidence from outside. Immutable — only its validity can change.
Belief	what an agent concluded. Must cite what it came from.
Claim	a proposition beliefs support or contradict.
Decision	an action taken because of a claim.

The rule: every belief must say what it was derived from. RootMemory refuses to store one that cites nothing. That turns memory into a family tree, so any belief can be walked back to the real-world evidence at the bottom.

A claim enters shared memory only through the promotion gate, which counts independent evidence roots — never agreeing agents. Contradictions are preserved rather than overwritten. And retracting a source walks forward through everything built on it: beliefs are retracted, claims downgraded, dependent decisions flagged needs_review.

Plugging into a framework

The core imports no agent framework. Adapters are optional extras.

LangChain / LangGraph long-term memory

pip install "rootmemory[langgraph]"

from langchain.agents import create_agent
from rootmemory.integrations.langgraph_store import RootMemoryStore

agent = create_agent(model=..., tools=[...], store=RootMemoryStore(agent_id=risk_id))

BaseStore.put has nowhere to say "here is what I read first", so the adapter infers it: the store remembers what it served to that agent and cites it as the parents of whatever it writes next. Provenance capture with no cooperation from the model.

Tools that force citation

from rootmemory.integrations.langchain_tools import build_tools
model = model.bind_tools(build_tools(memory, agent_id))

derived_from is a required field in the tool schema, so a model cannot record an opinion without saying what it read.

LangGraph nodes

from rootmemory.integrations.langgraph_memory import MemoryState, remembering

graph.add_node("risk", remembering(memory, risk_id, claim_key="supplier_risk")(assess))

State carries belief ids, not just text — text has forgotten where it came from.

Anything else

AsyncRootMemory is plain async Python with no framework types in its signatures. Non-Python agents can use the REST API.

Optional extras

Extra	Adds
rootmemory[api]	FastAPI service, Alembic migrations, and the visual portal at /ui
rootmemory[langgraph]	LangGraph store, node wrapper, LangChain tools
rootmemory[postgres]	PostgreSQL driver
rootmemory[llm]	LLM-backed claim normalization
rootmemory[all]	everything

The core depends only on SQLAlchemy, Pydantic and structlog. Importing the memory engine will not drag in a web framework.

The portal

pip install "rootmemory[api]"
rootmemory serve

Open http://localhost:8000/ui. Observations form the floor and everything built on them stacks above, so an echo chain renders as a tall thin tower on a single foundation. Click any node to trace it back to the evidence it actually came from; everything off that path dims.

Design rules

• Every belief has at least one causal parent. No provenance, no shared memory.
• Observations are never edited or deleted, only marked invalid.
• Only the promotion service may confirm a claim.
• Contradictions are preserved, never overwritten.
• Graph cycles are refused.
• Agreement count and independent-evidence count are always reported separately.
• The core is deterministic. An LLM may write belief text; it never decides what counts as evidence.

Measured against a naive shared scratchpad

Same beliefs, same confidences, same thresholds — the baseline just has no ancestry to consult.

Metric	RootMemory	Shared scratchpad
False corroboration rate	0.0	0.25
Wrong-action rate	0.0	0.5
Promotion precision	1.0	0.5
Repair completeness	1.0	0.0

Cost: roughly 5–6x more rows, because the family tree is kept alongside the conclusions.

Documentation

• Running it — step-by-step, including the demo and portal
• Architecture — the four algorithms in detail
• API reference
• Deployment — config, auth, claim normalization, rollout
• Evaluation — generated benchmark results

Status

Working, tested MVP: 144 tests, type-checked and linted. Runs on SQLite with no server. PostgreSQL is supported and its migration renders correct DDL, but has not yet been exercised against a live server.

License

MIT