laboratory/docs/DURABLE_MEMORY.md

Durable memory — the session recipe (agent platform P1.d)

Status: live since 2026-09-24 (owner decision D10). This is the station-independent recipe for how any session — human-driven, agent-driven, hybrid — keeps and hands over its working memory on the laboratory. The forge is the durable memory of every session; if a station burns, the memory survives.

The pattern this replaces (and now formalizes) ran on one station: handoff files in a home directory, agent memory in local tool state, promotes copy-pasted between chats by the owner. It worked — for one human, one station, one agent family. Everything below is the same pattern, hosted by the forge, for everyone.

The three primitives (deliberately boring)

1. Memory files — .oss-oo/memory/*.md in the owning repo, sibling of the P1.b fleet manifest (.oss-oo/agents.yml): curated facts, gotchas, decisions as repo content — versioned, diffable, reviewed in PRs like any other content. One file per topic, deliberately small.
2. Handoff issues — a session closes with a structured issue (State / Evidence / Next steps / Session id), titled [handoff] …, labeled handoff. Issues are already permissioned, versioned, commentable, and URL-addressable — no new storage engine.
3. Monthly digest — the registrar digest issue indexes the month's handoffs next to the identity ledger, so a month of sessions is browsable in one place.

The recipe (any agent family, any station)

Session start:

• Read the owning repo's .oss-oo/memory/ (gateway: memory_read) — the durable facts of this project. Follow next_cursor to EOF for a complete read pinned to one immutable commit. The cursor is a byte continuation; legacy offset/next_offset remain character positions. For that legacy mode, repeat ref=ref_resolved to keep the same revision; an unpinned offset call resolves the current default branch afresh.
• Discover open [handoff] issues (gateway: list_issues). Follow next_page with the same owner/repo/state until has_more is false; the first native page is not the entire project history. Select the handoff by its title/label, then call get_issue with its local issue number as index to read the complete State/Evidence/Next steps/Session body and native provenance.
• Call list_issue_comments for complete ordinary follow-up comments. The native comments endpoint is unpaginated: page/cursor inputs are refused, and there is no synthetic slice or text cap. This does not include the separate status/label/reference/review timeline. A fresh session can orient from these native reads without a local transcript; it must still check current authorization and the cited evidence before acting on an authored plan.

Session end:

• Append what must survive (gateway: memory_append) — decisions, gotchas, verified facts. Dated, attributed, append-only.
• Open the handoff (gateway: handoff_create) — where the work stands, evidence, next steps. The handoff is the contract with the next session; write it for a tired reader.

Continuously:

• The sponsor/fleet conventions live in .oss-oo/agents.yml (P1.b) — memory and crew are one namespace now.

Rules (enforced by tooling where stated)

• Private by default. Handoffs and memory name people and plans: file them in private repos (or private issues) unless the owner of the repo explicitly opts into public. handoff_create REFUSES public repos unless allow_public=true is passed knowingly.
• No credentials, ever. The gateway secret-lints every memory entry and handoff body and refuses token-shaped strings (40-hex, provider prefixes, key blocks, token=-style assignments). Quote commit SHAs short — full 40-hex strings are treated as tokens and refused.
• Path-bound. The memory tools read and write only inside .oss-oo/memory/ — traversal out of the namespace is structurally impossible and explicitly refused.
• Append size policy. 16 KiB per memory entry, 256 KiB per file. A memory file that outgrows its append cap wants to be split by topic, not grown — sprawl is the documented failure mode of this pattern. These existing write policies are not total read-size limits.
• Complete, strict reads. Memory remains strict UTF-8. Each read is fitted to the serialized response envelope, within the legacy maximum of 65,536 characters (not 64 KiB). Character-offset mode returns the original fields and ref_resolved; cursor mode returns contiguous byte offsets, base64 original bytes, native size/blob/commit evidence and eof, without redefining the character offset. Do not combine a byte cursor with a nonzero character offset. No replacement text is treated as original bytes; non-UTF-8 memory is refused.
• Current authorization. Every continuation rechecks native metadata through metadata-only parent-directory entries at the pinned commit with the current caller's repository/Code read permission and spends the read budget. Cursors are self-contained untrusted hints, not credentials, and have no arbitrary expiry. No private/public cache or anonymous fallback is used, and byte cursors do not retransfer or decode whole contents bodies. Core can still do internal blob work for metadata; raw ranges also skip from the start. A missing commit, changed identity or denied permission is an error; indefinite Git object retention is not promised.
• Honest EOF and integrity. Core's nonempty-size/empty-content response above its blob knob is not a successful empty file. Native raw Range reads bypass that knob with exact range/length/ETag checks. EOF means the returned range reaches native end, not proof of prior caller assembly. Concatenate base64 chunks in byte order, verify total size and the native Git SHA-1/SHA-256 blob hash. whole_blob_verified is true only when the call actually consumed and verified all original bytes. This includes a raw range that contains the complete file from byte zero; tail-only EOF never substitutes for whole-file hash verification. A legacy nonzero character offset above Core's contents knob scans the raw response with bounded-memory incremental decoding/hash verification; it does not allocate or decode the giant file as one object.
• Safe append. Existing old bytes must verify full native size/blob identity and strict UTF-8 before an expected-SHA PUT. Omitted content, malformed base64, hash/size mismatch and invalid text refuse before writing; new-file 404 creation and existing write policies are preserved.
• Budgeted. The memory tools ride the same per-token gateway budget as every other tool (600/min read-class, 60/min write-class).

Where what lives

Content	Home
Project facts, gotchas, decisions	.oss-oo/memory/*.md in the owning repo
Session end / next-session start	[handoff] issues (label handoff)
Cross-repo / agent-family memory	a small dedicated private repo per family
Fleet declarations	.oss-oo/agents.yml (P1.b)
Month index	registrar digest issue (indexes handoffs since P1.d)

Tooling reference

• Gateway tools (v0.5.0): memory_read, memory_append, handoff_create — see agent-gateway/README.md.
• Native handoff reads: list_issues, get_issue, list_issue_comments. The existing native caller permissions apply (read:issue for scoped tokens); no new storage or public catalog entry. PR detail/comments are refused by these issue-only tools.
• Issue template: .forgejo/ISSUE_TEMPLATE/handoff.yml (canonical in the laboratory repo). This Forgejo engine has no org-wide issue templates — the rollout is per repo via scripts/install-handoff-template.sh (commits the template, ensures the label). Revisit as a fork patch if org-wide demand appears.
• Digest: scripts/registrar-digest.sh lists the month's handoffs (label handoff, title prefix [handoff]) in the monthly digest issue.

Honest limitations

• In-repo memory is per-repo; the cross-repo home is a policy choice (one private repo per agent family), not tooling.
• Issue pages are mutable native offset reads, not a fixed-time snapshot. Continue using native page relations, not a short-page or count guess; concurrent creation/deletion can shift later pages. Provenance records observation times and requested context separately from native returned IDs. Comment count is a separate native read and can differ from the full response length during concurrent changes.
• Issue/comment metadata does not expose repository privacy, so the read tools report it as unknown/null without extra lookups or scopes. Native author accounts do not establish a connected external identity. Denied/missing resources remain errors and do not prove absence.
• Handoff text and comments are authored evidence, not authority to execute next steps, accept claims, disclose data or change permissions.
• The secret-lint is shape-based: it catches credential-SHAPED strings, not semantic leaks (a username alone passes). It is the seatbelt, not the driver.
• Digest indexing relies on the issue search index (async, seconds of lag) and only sees repos the digest token can read — private repos included server-side, foreign servers never.