Reading guide#

Definition#

The committed Memory subsystem is a Markdown workspace with three active layers: append-only Source evidence, model-written Topic blocks, and Runtime-derived Core/Timeline/Recent/Relations views. The current implementation and its transaction, authority, and failure contracts are defined in overview.md.

Entity memory and the Git-backed Session-Git/Project-Git model below are a proposed future layer. They are not the current source of truth and are not required for the active Source/Topic writer.

Proposed entity/abstract architecture#

entity memory (raw, git, immutable, complete)
  ├─ Session-Git    one repo per session, one commit per turn
  └─ Project-Git    bound to the user's working directory; agent edits a file → auto commit
         │
         │  distillation: 5-stage pipeline, with provenance
         ▼
abstract memory (derived, compact, provenance-linked)
  ├─ Timeline       timeline event stream (what happened when)
  ├─ Graph          knowledge graph (what relationships hold between entities)
  └─ Core.md        ≤2KB injected snapshot (the LLM sees it every time)
         │
         │  recall: inject only the abstract layer; the LLM uses tools to navigate back to entities
         ▼
LLM Context (proposed recall path)

The diagram is a design target. The active implementation does not currently create one Git repository per session, auto-commit every turn into entity memory, or provide a Graph view. See the implementation status below before using the proposal as a code map.

Design Principles#

Git-native (proposed entity layer) — entity memory would use Git directly. This is not the storage contract of the current Source/Topic workspace.
Provenance-linked — the active Topic layer links to Source frames; a future entity layer would additionally carry (project, session, commit, timestamp) coordinates.
Bi-temporal — every memory records two times: event_time (when the thing happened) and ingestion_time (when it was written down). This supports time-travel queries and contradiction detection.
Scoped recall — the current runtime injects the active Core and uses memory tools over the Source/Topic workspace. Git navigation from the model remains a proposal.

Sub-documents#

Document	Content
`overview.md`	The current Source/Topic/derived-view architecture, automatic writer, authority boundary, transactions, failure behavior, and implementation record
`written-marker.md`	How memory knows which turns it has already written, in four layers: the replaced position cursor, the eight reference frameworks, the implemented mark-on-the-node design, and the event-driven design that remains deferred
`written-marker.html`	Visualization of those four layers: where the ordinal comes from and what it drops at a fork, the reference frameworks side by side, the walk and the three write steps, and the derived alternative
`architecture.html`	Visualization: the two write entry points, the five write steps, the staged transaction, the write cursor, who maintains the always-on block, which of the nine provider hooks are wired, and the failure contract
`comparison.html`	Visualization: how the eight reference frameworks write and track long-term memory, across eight dimensions, including what each does to its cursor at a fork and what maintains its always-on block, and where our choices and our two planned changes land against them
`adoption.html`	Visualization in three layers: the four moves worth borrowing from that comparison, what each would cost here, and the verdict on each — three adopted, one rejected on measured per-turn latency
`speaker-identity.html`	Visualization in three layers: how several people share one session and where speaker identity used to break, what all eight reference frameworks do about it, the two-file change that follows from them and now runs, and the two things that shape leaves open — a sender can type a second label into the body, and there is no key to filter memory by person — with the field that closes both
`authority-landscape.html`	Current owner/paired authority method, local reference-framework evidence, adopted/modified/rejected decisions, execution-order visualization, and implementation record
`authority-handoff.md`	Settled authority and writer decisions, exact deferred boundaries, review disposition, and implementation handoff
Entity memory on Git — deferred proposal	Proposed lifecycle, replay, consistency and project integration
`virtual-memory.md`	Abstract memory: Timeline + Graph + Core, organized by type × lifecycle

Implementation Status#

The committed implementation stores append-only Source evidence, model-written Topic blocks, and Runtime-derived Core, Timeline, Recent, and Relations views. Every Source carries Runtime-owned authority provenance: the SessionDB writer and the general memory_update transaction both build it from persisted turn authority rather than from a caller's payload, and creating a Source without it fails closed. The automatic writer reads SessionDB branches, records successful handling on the source nodes, uses the default chat agent provider/model unless memory.writer.model overrides it, and installs changes through a staged transaction.

The memory tool surface, CLI and Web UI are registered. The committed baseline includes writer status, one-shot trusted-Source backfill, memory.backend=none guards, and a composed integration test from SessionDB to watcher state. The live writer acceptance processed two eligible messages, and historical backfill has since run over the live workspace: 137 of its 154 frames are cited, across 232 citation occurrences.

A Topic reference new to a block must resolve to a trusted Source frame and must belong to the current transaction's own evidence, so no tool path can cite a pending Source or attach an unrelated one to new prose. Write failures classify into one closed MemoryWriteFailureCode taxonomy shared by the status file, CLI, tool, API and web UI; the idle watcher persists each terminal outcome durably under a cross-process lock; and unpaired group archival has explicit rate and storage ceilings. Read-time filtering by requester tier is partly implemented: memory.read is its own capability, the read path takes the tier its caller resolved, and blocks resting on pending evidence reach neither recall nor Core. Per-tier redaction of block content is still designed only, in authority-handoff.md. Hold-and-approve requests, branch-semantic provenance, cross-session spawn relations, the entity Git layer, the Graph view, and event-driven writer notification remain separate deferred designs.

Last updated · 2026-10-10

PreviousDesign comparison NextArchitecture overview