Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs(design): fold maintainer review into the offer-not-claim proposal (#959)
AkitaOnRails18c6949fcc79
diff --git a/docs/design-handoff-offer-not-claim.md b/docs/design-handoff-offer-not-claim.mdindex 9ed7d546..406936d1 100644--- a/docs/design-handoff-offer-not-claim.md+++ b/docs/design-handoff-offer-not-claim.md@@ -1,6 +1,6 @@# Design proposal: offer, don't claim, at session start (#959)-**Status: proposal for review — not implemented.** The maintainer marked #959+**Status: accepted design (maintainer review folded in, 2026-10-01) — not implemented.** The maintainer marked #959design-first: it touches the single-claim contract (invariant #16 — a handoffis claimed exactly once by two independent `state='open'` guards) in severalplaces at once, so this is the design pass requested before any code lands.@@ -49,7 +49,15 @@ has no opt-out, and `to_agent` is stored but never used to target delivery.one. An automatic (`SessionEnd`) handoff is scoped by cwd path-boundary.Owner is checked first, before the manual short-circuit, so cross-operatormixing is already excluded — this proposal only touches same-operator,- same-project delivery.+ same-project delivery. `startup_handoff` (`reader.rs`) also already skips a+ baton whose source session is still live (`LIVE_BATON_QUIET_PERIOD`, 10+ minutes, `router.rs`), so a session started next to a running one does not+ take its handoff.+- **Expiry**: handoffs already have an `expired` state. `SessionEnd` expires+ the same cwd's older automatic batons (`expire_same_cwd_auto_handoffs`,+ `ops.rs`) and a post-claim sweep expires superseded ones, so automatic+ batons do not pile up; only manual ones stay open until accepted or+ cancelled.- **`to_agent`**: a column exists on the handoff row (`ai-memory-store`), isthreaded through `row_to_agent_message`-adjacent plumbing, and is written— always as `None`. `memory_handoff_begin`'s args@@ -93,6 +101,11 @@ siblings in `crates/ai-memory-cli/src/config.rs`):claim_on_session_start = true # default: unchanged behavior```+**Where the switch lives.** A server-wide `[handoff]` key applies to every+operator on a shared server. Prefer (or additionally offer) a per-project+`.ai-memory.toml` marker key, so one team's repository can opt into offer mode+without changing another's. Settle this before implementation.+When `true` (default — **no behavior change for existing installs**),`fetch_and_accept_handoff_at` claims exactly as it does today.@@ -104,9 +117,19 @@ almost this exact lookup — this proposal does not add a second tool).```📬 ai-memory: a pending handoff `<id>` from `<from_agent>`, left `<age>` ago.- Use `memory_handoff_accept` to pick it up.+ To pick it up, call `memory_handoff_accept` with handoff_id `<id>`.```+The notice must name the exact `handoff_id` and tell the agent to accept that+id. "Accept the latest" could claim a different handoff that arrived after the+notice was rendered; an exact-id accept just loses the race cleanly when the+notice is stale (both `state='open'` guards still decide).++**Managed-run ledger.** Today the managed-run context claim commits in the+same transaction as the handoff claim. In offer mode the ledger/context claim+still happens at session start — only the single-use handoff slot becomes an+offer — so a managed run does not lose its continuity packet.+The brief and managed-run context (`managed_md`) are unaffected either way —only the single-use handoff slot's own claim becomes conditional.@@ -140,6 +163,9 @@ interact).manual-beats-automatic short-circuit matters — see Open questions.- Selection (`prefer_handoff`) is otherwise unchanged: `to_agent` filters thecandidate set, it does not introduce a new ranking dimension.+- An explicit `memory_handoff_accept` with an exact `handoff_id` ignores+ `to_agent`: targeting only shapes automatic delivery and the notice, it never+ stops a user from deliberately picking a baton up in another harness.## Open questions for review@@ -149,7 +175,7 @@ interact).specifically to block a hostile handoff summary from injectinginstructions into a session that never asked to see it (a non-consumingnotice is, by construction, something the receiving agent cannot choose- to skip the way it can choose not to call `memory_handoff_pop`). A+ to skip the way it can choose not to call `memory_handoff_accept`). Ahandoff's summary is written by whatever agent or operator ended theprior session — same trust level as a cross-project message. **Leaningtoward metadata-only** (id, `from_agent`, age — no summary text), matching@@ -179,10 +205,11 @@ interact).otherwise — an un-regenerated plugin simply keeps claiming unconditionallyforever, which is not a crash, just a no-op upgrade.5. **A handoff nobody ever explicitly accepts**: with `claim_on_session_start- = false`, does an un-accepted handoff expire on its own, or stay open- indefinitely until `memory_handoff_cancel`/a new one supersedes it? No- existing TTL mechanism was found for handoffs; proposing no new one here- (status quo: open until accepted or cancelled) unless review disagrees.+ = false`, does an un-accepted handoff expire on its own? Partly answered:+ automatic batons are already expired by `SessionEnd` and the post-claim+ sweep (see Expiry above), so offer mode does not accumulate them. Only+ manual handoffs stay open until accepted or cancelled; no new TTL is+ proposed for those unless review disagrees.## Non-goals (v1)