Runtime internals

Memory that separates what happened from what matters.

Most agent runtimes flatten memory into one bucket. Tandem treats knowledge, run state, and governance as distinct first-class layers — so agents stay inspectable, resumable, and auditable at scale.

Read the docs See the engine

Inspectable

Prompt context and execution state stay separate.

Resumable

Replay picks up from checkpoints, not an overwritten transcript.

Auditable

Provenance and partitions make writes traceable.

Layered by design

Seven layers, one runtime.

Reference

Working memory = prompt context

Session memory = chat and step history

Persistent memory = governed knowledge

Semantic memory = retrieval by meaning

Artifact memory = durable outputs

Execution memory = replay and resume

Derived memory = rebuildable speedups

The core idea is simple: what the agent remembers should not be confused with what the agent did.

Agent memory architecture

The problem with flat memory

Most agent systems conflate conversation history, durable knowledge, execution state, and artifacts into one memory concept. That is fine for a demo, but it breaks the moment you need to replay a run, audit who saw what, resume after a crash, or scale beyond one user.

Tandem keeps those concerns distinct so the agent memory architecture stays legible. The runtime can answer from explicit knowledge, pause when governance requires it, and recover execution state without rewriting its beliefs.

flowchart LR
  subgraph L["Most runtimes"]
    direction TB
    LH[Chat history]
    LU[User facts]
    LR[Run state]
    LA[Artifacts]
    LC[Cache]
    LM[(Memory)]
    LH --> LM
    LU --> LM
    LR --> LM
    LA --> LM
    LC --> LM
  end

  subgraph R["Tandem"]
    direction TB
    TW[Working memory]
    TH[Chat history] --> TS[Session memory]
    TU[User facts] --> TP[Persistent long-term memory]
    TR[Run state] --> TE[Execution memory]
    TA[Artifacts] --> TAr[Artifact memory]
    TC[Cache] --> TD[Cache / derived memory]
    TS --> TW
    TP --> TW
    TE --> TW
    TAr --> TW
    TD --> TW
  end

Flat memory vs layered memory

Agent memory architecture taxonomy

The seven layers of agent memory

This taxonomy is useful even outside Tandem. It gives architecture teams a shared vocabulary for separating prompt context, durable knowledge, and replayable execution state before the system gets large enough to blur them together.

Layer 1

Working memory

In-flight prompt context, scratchpad, and active tool state that exist only for the current turn.

Example: The current turn's assembled prompt.

Layer 2

Session memory

Conversation and step history tied to a single run or session.

Example: The message log of one chat.

Layer 3

Persistent long-term memory

Cross-session saved knowledge the agent is expected to recall.

Example: User preferences and project facts.

Layer 4

Semantic memory

Embeddings and retrieval systems that recall by meaning rather than location.

Example: Vector search over past notes.

Layer 5

Artifact memory

Files, outputs, and documents that persist as inspectable artifacts.

Example: A generated report saved to disk.

Layer 6

Execution memory

Checkpoints, run state, and replay state needed to resume work.

Example: The snapshot needed to resume a crashed workflow.

Layer 7

Cache / derived memory

Cached outputs and snapshots that accelerate retrieval but are not the source of truth.

Example: An embedding cache.

Implementation details

How Tandem implements each layer

Each layer gets the same treatment: a short summary for fast reading, then a collapsed technical detail for operators who want schema, code paths, and storage layout.

Working memory

In Tandem, working memory is prompt context only — assembled per turn, never persisted. That keeps run artifacts clean and auditable.

Implementation details

Working memory is assembled at the turn boundary from session history, retrieved memory, and active tool state. It is not written to disk, and it is rebuilt on every run so the agent can stay inspectable without leaking scratchpad state into durable storage.

Session memory

Session transcripts and step history live separately from long-term memory, so what happened in the chat never silently becomes what the agent believes.

Implementation details

Session memory is stored in memory.sqlite under session-scoped tables and is searchable via FTS5. It never automatically promotes into long-term memory without an explicit write, which keeps short-lived context distinct from durable knowledge.

Persistent long-term memory

Durable, governed memory records carry provenance, classification, and partitions instead of collapsing into one flat bucket of notes.

Implementation details

The memory_records table is partitioned by scope: session, project, and global. Capability tokens control read and write access, and every record carries provenance so operators can trace where the knowledge came from and how it entered the system.

Semantic memory

Tandem uses built-in sqlite-vec plus FTS5 for hybrid keyword and vector retrieval, so teams do not need an external provider just to search by meaning.

Implementation details

The vector index sits next to the record store. Hybrid search combines lexical and semantic scores with configurable weights, and an embedding cache avoids repeat work when the same sources are indexed again.

Artifact memory

Outputs are first-class artifacts with durable references, not blobs mixed into the transcript.

Implementation details

An artifact registry tracks durable outputs by run and session. Artifacts stay inspectable independently of the agent's chat log, which makes it possible to review what was produced without replaying the entire conversation.

Execution memory

Run state and blackboard data live in dedicated context_runs storage, separate from knowledge memory. That split is what makes replay and resume actually work.

Implementation details

Each context_runs/<run_id>/ directory holds ContextRunState, events.jsonl, blackboard.json, and checkpoints. Execution state is replayable on its own, without mutating memory_records or changing what the agent knows.

Cache / derived memory

Embedding caches, FTS indexes, and derived snapshots speed retrieval, but they remain rebuildable rather than authoritative.

Implementation details

All derived stores are rebuildable from primary tables. You can evict or rebuild them without losing durable memory, which keeps operational caches separate from the data that matters.

flowchart LR
  T[Agent turn] --> WM[Working memory]

  subgraph K["Knowledge"]
    direction TB
    SM[Session memory]
    PM[Persistent memory]
    SEM[Semantic memory]
    AM[Artifact memory]
  end

  subgraph E["Execution"]
    direction TB
    CR[context_runs/]
    CK[checkpoints]
    EV[events.jsonl]
    BB[blackboard.json]
  end

  subgraph D["Derived"]
    direction TB
    CD[Cache / indexes]
  end

  SM --> WM
  PM --> WM
  SEM --> WM
  AM --> WM

  T --> CR
  CR --> CK
  CR --> EV
  CR --> BB

  SEM -. rebuildable .-> CD
  CD -. rebuildable .-> SEM

Tandem memory architecture

Why the separation matters

Replay, governance, and scale need typed memory

Replay and resume only work when execution state lives separately from knowledge memory. Tandem can replay a run without corrupting durable beliefs, and it can resume a crashed workflow without rewriting the reasoning trail that led there.

Governance depends on typed memory. Partitions, capability tokens, classifications, and provenance only make sense when the runtime knows whether a record is session-scoped, project-scoped, or global. Flat memory cannot be governed because you cannot audit what you cannot distinguish.

Multi-tenant systems need clear boundaries. Session memory, project memory, and global memory must stay isolated or data will leak across users as the system grows beyond one person and one prompt.

Governance and audit

Controls that make memory governable

Implementation details

Partitions by scope. Session, project, and global partitions keep memory records in the right boundary so a single agent can operate across multiple tenants without accidental bleed-through.

Capability tokens. Read and write access is granted explicitly, which gives operators a narrow control plane instead of a flat database credential that can touch everything.

Classifications. Records can be marked by sensitivity or purpose so policy can treat operational notes, customer facts, and shared knowledge differently.

Provenance. Every record carries where it came from and when it was written, which makes later inspection possible without guessing how the memory entered the system.

Audit trail. Writes are logged across the runtime, which makes replay, review, and incident investigation possible even when memory changes over time.

Keep exploring the runtime.

Read the memory docs Explore the engine on GitHub

Looking for the hosted community agent product? Explore Tandem Agents.