Memory model

ROAM has three tiers of memory: canon, journal, and shared. They are persistent across runs, Ed25519-signed by the daemon, and designed so that an agent leaving the team does not take its work with it.

Three kinds of memory

Most multi-agent systems have one kind of memory: a chat history and maybe a vector store. That is fine for a single agent in a single session. It falls apart the moment two agents from different harnesses need to agree on what was decided last Thursday.

ROAM separates memory by what it is for, not where it is stored. The three tiers correspond to three real questions agents ask each other:

• Canon — what do we agree on? Facts, decisions, doctrine, completed work.
• Journal — what did I do, and when? A per-agent append-only log of their own actions.
• Shared — what does everyone need to know about how the world works, regardless of which framework they run on? Cross-runtime knowledge that survives a swap.

Canon — the agreed-upon truth

Canon is the institutional memory of the operating system. It is written to deliberately and read from constantly. Any agent can propose an entry; canon writes that materially affect other agents are surfaced as decisions for human approval.

Each canon entry has a state: reliable, suspect, quarantined, or invalidated. If a downstream agent finds an entry to be wrong, it can mark it suspect; an approved decision can quarantine or invalidate it. The history of state changes is itself part of the audit.

Canon is not a vector store. It is structured: facts, decisions, doctrine, role descriptions, completed task records. Search is by structure first. The model is closer to a small Wikipedia than a chatbot scratchpad.

Journal — what each agent did

Every agent has its own journal. It is append-only, signed, and ordered. Every consequential action — claiming a task, starting, completing, failing, peer-reporting another agent, updating its working doctrine — is journaled by the daemon.

The journal is what makes accountability possible. When EYDII decides an agent has drifted, the evidence is in the journal. When a swap is proposed, the new agent reads the outgoing one's journal to pick up exactly where the work left off. When you ask "who decided to ship this?" — the journal has the answer, and the daemon's Ed25519 signature proves nobody rewrote it.

Shared — knowledge across runtimes

Shared memory exists for one specific reason: an agent running inside Claude Code and an agent running inside Cursor should not have to relearn the same thing twice. If the team decides "our deployment target is a container, our database is Postgres, our error format is RFC 7807," that knowledge belongs in the shared layer where every harness can read it.

Shared memory is the layer most directly responsible for heterogeneous operation. It is how agents from different tools can behave like one team: they read from the same shared knowledge before they act.

Memory outlives the agent

The reason for separating memory from agent process state is that agents are not durable. A model gets deprecated. A framework changes its API. A specific persona drifts and gets retired. None of those events should erase what the team learned.

When an agent is swapped, the canon stays. The shared knowledge stays. The drifting agent's journal stays — sealed, marked, and queryable. The new agent inherits the persona's job description and Trust Score history, reads the canon, and picks up the open work. The team does not start over.

Where it lives on disk

Everything lives in your session directory. The daemon writes to well-known paths under it; you can inspect them at any time with ordinary tools.

<sessionDir>/
  artifacts/                   shared artifacts referenced by canon
  doctrine/                    working doctrine files
  registry/<agent-id>.yaml     agent registrations
  agent-logs/<agent-id>/       per-agent logs and journal traces
  peer-reports/                peer-to-peer drift reports
  tasks/                       task definitions
  state/                       session state
  .roam/
    roam.sock                  daemon Unix socket (created at start)
    digest.json                session stats
    observer-queue/            EYDII observation queue

The exact methods to read and write canon, journal, and shared tiers are documented in the SDK reference as the public package is finalized. Track the public repo at github.com/veritera-ai/roam.