Disk memory

The workshop remembers on disk — ledger, resume, board, last-session card. The chat window is not memory.

What it is#

A small set of plain Markdown files that survive the end of a chat window.

File What it holds Who writes it
.workflow/RESUME.md Where the workshop stands; the first thing a new seat reads You and the Chair
.workflow/LEDGER.md The numbered requirements list, one - [ ] N. line per item You and the Chair
.workflow/BOARD.md The live board: open sessions, claims, verdicts Orchemax and the Chair
<project>/docs/TRACKER.md Per-project state table — status, SPEC, evidence The project's agents
.orch/LAST_SESSION.md Telegraphic card describing the seat that just ended Orchemax, at close
.orch/MEMORY_BRIEF.md Short durable brief, when memory is enabled Orchemax
.orch/ORCH_RUNTIME.md This seat's identity: session, agent, role, MCP hint Orchemax, at open

orch init seeds the first three; the rest appear as you work.

Why it exists#

Because chat is ephemeral and everybody keeps pretending it is not. A model's context window ends, gets compacted, or gets replaced by a different model tomorrow. Anything that has to outlive the window has to be a file — and a file the next agent can find without being told where to look, which is why the paths are fixed rather than configurable per project.

The second reason is arbitration. When two sessions disagree about what was decided, a ## Clarified block in the ledger settles it and a chat transcript does not.

How it relates to the rest#

  • A worker's verify_report and the guardrail verdict Orchemax observes at session close both land on the board, so the board is the one place where reported and observed halves sit side by side.
  • task_claim / orch task claim <ledger-file> <item> puts exactly one owner on a - [ ] N. line, visible on the board and released when the task finishes or the session is reaped. Two agents cannot quietly both take item 12.
  • The sealed orch-recall skill exists to make a new seat read .orch/LAST_SESSION.md instead of asking you to re-explain the project.

Medium horizon (not claude-mem)#

Orchemax does not mirror tools that observe every tool call into a months-long vector store. Memory is:

  1. Disk truth — LEDGER / RESUME / BOARD / LAST_SESSION (durable decisions).
  2. Tiny inject — LAST_SESSION ≤ 2400 bytes and MEMORY_BRIEF ≤ 1200 bytes into seat orientation; default brief is at most 8 entries from the last memory.horizon_days (default 14).
  3. On-demand recall — memory_recall with limit + max_bytes (~2 KB).
  4. Typed SQLite TTL — memory.retention_days expires noise in days (context 3, observation 7, event/error 14, decision/goal/learning 30, instruction/preference/fact 45).

Doctrine (GATES.md, principles, skills) is permanent on disk — it is not SQLite memory. Tune inject/horizon under Settings → Memory. Never dump prior chat transcripts (agent-recall style) into a new seat.

Searching it: memory_recall#

The MCP tool memory_recall (and orch memory recall on the CLI) does not stop at the durable memory_remember entries. It also searches ctxstore's indexed context chunks and greps .orch/LAST_SESSION.md and .orch/MEMORY_BRIEF.md for the same query, so "did we already decide this" has one answer instead of three places to check by hand. The search itself is full-text (SQLite FTS5 where the embedded driver has it, a plain substring scan otherwise) rather than exact-string only, so a query for "budget" also finds an entry that says "budgets". limit caps hits per source; max_bytes (default 2 KB) caps the total reply so a recall never turns into a second transcript.

Shrinking a file is a human decision#

.workflow/BOARD.md and .orch/LAST_SESSION.md grow. When one gets unwieldy:

orch memory condense

It runs through the workspace gateway and it is never automatic — no size threshold triggers it. It preserves ## Clarified and ## Ownership byte-for-byte, keeps every open checkbox item, and leaves the original beside the file. There is deliberately no MCP tool for it: an agent cannot decide to forget on your behalf.

The optional context.hooks.pre_compact hook runs the same condenser just before a harness compacts its own context. Like every hook, it is off until you turn it on — see Hooks and guards.

Footprint and trimming (0.5.0)#

Orchemax releases what it fills. It measures its own footprint — build cache, worktrees, scratch and logs — in orch stats, trims the Go build cache when idle and over its limit, removes stray orch binaries at start, and frees dead workers' worktrees without losing their branches or uncommitted work. See Release 0.5.0.

Nothing to run here#

Reading these files is the point; writing them is ordinary editing. memory_recall reads them for you on demand; the only command you run yourself is orch memory condense, and only when a file is too big, not on a schedule.