agent memory: durable working notes / findings across turns (identity, not one-shot)

[btipling]

Parent

#548 (agent session architecture)

Problem

Thinking is ephemeral (not in SessionStore). That is fine — CoT should not
survive refresh.

What is not fine: nothing durable carries findings, decisions, or
identity across turns. The assistant refers to “the previous assistant.”
Each send feels one-shot. Other harnesses feel like the same agent walked
back into the room.

#536 (session TODOs) is adjacent (task list in the prompt). This issue is
semantic memory: “we decided X, the bug is in Y, don’t touch Z.”

Goal

The agent can choose to persist important findings/ideas across turns
(and we may auto-extract a small working-memory block). New/Clear resets it
(new session = new mind). Refresh keeps it (session-owned, like cwd).

Success: mid-session, “what did we conclude last turn?” is answerable from
session state, not from hoping the last 400 assistant paragraphs still
contain it after the 3.5M slice.

Constraints (lock)

• Thinking rows stay ephemeral. Do not dump CoT into Redis/Blob as the
  memory mechanism.
• Memory is session-owned (rides the session architecture — addressable per-user sessions with session-owned state (cwd, sandbox binding) #408 object / envelope meta or a
  dedicated small field) — not a new cloud product, not local-only.
• Bounded. A novel is not memory; it is another 8 MiB problem. Future plan
  Caps table (generous NEW cap, Function-safe if it rides a Function body).
• Feature-divide: canvas may show a compact “notes” affordance later; v1
  can be host-folded into the system/prompt only (no dual chat).
• Agent-authored persist is the honesty bar: we do not silently invent a
  persona from truncated history.

Non-goals

• Personas (feat: user agent personas (AGENTS.md profiles) + New session inject #329, shipped) — different layer (standing orders)
• Templates / fork (feat: agent templates / forking (save good context, reuse later) #372)
• Replacing the transcript

Suggested next

create-plan against #548 A2. Decide: reserved meta.workingNotes vs a
small Blob sidecar vs a first-class tool (remember / recall).

Peer harness notes

Pi CustomMessageEntry / CustomEntry inject extension state into (or
beside) the LLM context without dumping CoT. Oh My Pi “advisor” notes are a
separate window — we do not want a second agent; we want a small
session-owned notes block (#550) the fold can always include.

Compaction should keep notes (they are the identity), not summarize them
away (#552). Skills catalog (#557) is playbooks, not findings.

Orrery (2026-08-15)

Their durable-spec slot (stable prefix region) is the right home for notes: compact into it at phase boundaries (#552), do not append “earlier: …” onto growing history. Notes stay byte-stable across turns so #558’s block 1/2 split still caches. New/Clear wipes the slot (new mind).

[btipling]

Not the first-turn root cause. Operator report 2026-08-18 (“each send feels like the first turn / not myself”) lands on #548 / #549: we prune the tool graph and flatten history.

Working notes still matter after A1: compaction (#552) should write findings into this slot so identity survives a checkpoint. A notes block on top of today’s formatPromptWithHistory crumb is still a new assistant reading someone else’s diary. Do not promote A2 ahead of A1 to “fix amnesia.”

[btipling]

2026-08-19 source-level peer research

#550 is session-owned notes (New/Clear = new mind). Do not grow it into a cross-session handbook — that is #694, later, default off, and it does not fix first-turn identity.

Where notes live (lock with #558 / #552)

Codex world-state diffs and OpenCode Context Epochs are the right shape for a byte-stable slot:

• Freeze a durable-spec region (notes + files-touched after compact).
• Unchanged notes cost zero new tokens and keep the prefix cache (inference: cache-stable two-block system prompt (don’t bust the KV prefix) #558 block 1 stays put; notes ride the stable-enough durable-spec, or volatile block 2 if they churn every turn — create-plan picks one, but must not append “earlier: …” onto growing history).
• Compaction writes into the slot (compaction: model-capability context compaction (not API payload slices) #552), it does not summarize notes away.
• Replace the frozen baseline only at a compact / phase boundary, not mid-tool-streak.

OMP learn is the honesty bar for any auto-extract: write now, inject next prefix generation if injecting would bust KV cache. For in-session notes we do want them on the next turn of this session — so they belong in the durable-spec / block-2 region that is allowed to change, not in block 1.

Two systems (do not mix)

	#550 notes	#694 handbook
Lifetime	this session	across New session
Writer	live agent (tool or small auto block)	idle Phase 1/2, not /api/agent mid-turn
On compact	keep	n/a (not in the live vector)
On New/Clear	wipe	keep (if the flag is on)

Pi CustomMessageEntry is still the closest inject shape (beside the LLM context, not a second agent / OMP advisor window).

Personas (#329) stay standing orders. Notes are findings.