Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(hooks): claim complete startup context atomically
AkitaOnRailsea354e6ebf97
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 115feb00..779ee682 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -54,6 +54,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0now always pass `-i`, while `-t` is added only when stdin and stdout areboth terminals. `AI_MEMORY_NO_TTY=1` disables only TTY allocation andno longer disconnects stdin. (#243)+- Managed `SessionStart` delivery now includes a pending single-use+ handoff before the portable workstream ledger and optional project+ brief. Handoff and ledger acknowledgements are claimed together only+ after the complete response has been assembled; a failed or racing+ ledger claim cannot consume the handoff or suppress retry delivery.+ (#235)## [1.18.0] - 2026-07-23diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rsindex 66bc9e3c..0ecf8ddc 100644--- a/crates/ai-memory-hooks/src/router.rs+++ b/crates/ai-memory-hooks/src/router.rs@@ -1090,7 +1090,7 @@ async fn fetch_and_accept_handoff(// too. The brief already reaches the managed path (it is recomposed per// session, so resolving it twice was harmless); the handoff is single-use// and had no second chance.- let managed_md = fetch_managed_context(state, &query, agent).await?;+ let managed = fetch_managed_context(state, &query, agent).await?;// `/handoff` has no session_id in the request — `per_session` mode// therefore falls back to the single slot (graceful degradation),// while `per_actor` keys by `user` alone.@@ -1110,32 +1110,54 @@ async fn fetch_and_accept_handoff(false,).await?;- let handoff_md = {- let handoff = state- .reader- .latest_open_handoff(ws, proj, query.cwd.clone())- .await?;- match handoff {- Some(h) => {- state.writer.accept_handoff(h.id, agent, None).await?;- Some(render_handoff_markdown(&h))- }- None => None,- }- };+ let handoff = state+ .reader+ .latest_open_handoff(ws, proj, query.cwd.clone())+ .await?;+ let handoff_md = handoff.as_ref().map(render_handoff_markdown);// The brief is additive and non-destructive: unlike the handoff (a- // single-use slot consumed above), it is recomposed on every opted-in+ // single-use slot claimed below), it is recomposed on every opted-in// session start — exactly what a Claude Code `/clear` needs (#176).let brief_md = render_requested_session_brief(state, &query, ws, proj).await?;// Handoff first: it is a short curated pointer and must not be buried// under a ledger that can run tens of KB. The existing ledger-then-brief- // order is preserved.+ // order is preserved. Claim both single-use inputs only after every+ // fallible read and render has succeeded, and in one transaction so a+ // failed or racing managed claim cannot consume the handoff by itself.+ let acceptance = if handoff.is_some() || managed.is_some() {+ state+ .writer+ .accept_startup_context(+ handoff.as_ref().map(|handoff| handoff.id),+ agent,+ None,+ managed.as_ref().map(|managed| managed.run_id),+ )+ .await?+ } else {+ ai_memory_store::StartupContextAcceptance::default()+ };+ let handoff_md = if acceptance.handoff_accepted {+ handoff_md+ } else {+ None+ };+ let managed_md = if acceptance.managed_context_accepted {+ managed.and_then(|managed| managed.markdown)+ } else {+ None+ };Ok(combine_handoff_and_brief(handoff_md,combine_handoff_and_brief(managed_md, brief_md),))}+struct PendingManagedContext {+ run_id: ManagedRunId,+ markdown: Option<String>,+}+/// Render the managed-run ledger for this SessionStart, if there is one.////// Returns `None` — never an early exit for the caller — when the run is@@ -1146,7 +1168,7 @@ async fn fetch_managed_context(state: &HookState,query: &HandoffQuery,agent: AgentKind,-) -> anyhow::Result<Option<String>> {+) -> anyhow::Result<Option<PendingManagedContext>> {let Some(raw_run_id) = query.managed_run.as_deref() else {return Ok(None);};@@ -1186,8 +1208,10 @@ async fn fetch_managed_context(context.workstream_id,context.sync_after,);- let _ = state.writer.accept_managed_run_context(run_id).await?;- Ok(rendered)+ Ok(Some(PendingManagedContext {+ run_id,+ markdown: rendered,+ }))}async fn render_requested_session_brief(@@ -5732,23 +5756,20 @@ mod tests {.await.unwrap();- let rendered = fetch_and_accept_handoff(- &state,- HandoffQuery {- agent: Some("codex".into()),- cwd: Some(cwd),- workspace: Some("default".into()),- project: Some("scratch".into()),- project_strategy: None,- briefing: None,- briefing_budget: None,- managed_run: Some(run.run_id.to_string()),- session_id: Some("native-2".into()),- },- None,- )- .await- .unwrap();+ let query = HandoffQuery {+ agent: Some("codex".into()),+ cwd: Some(cwd),+ workspace: Some("default".into()),+ project: Some("scratch".into()),+ project_strategy: None,+ briefing: None,+ briefing_budget: None,+ managed_run: Some(run.run_id.to_string()),+ session_id: Some("native-2".into()),+ };+ let rendered = fetch_and_accept_handoff(&state, query.clone(), None)+ .await+ .unwrap();let rendered = rendered.expect("managed SessionStart must return context");assert!(@@ -5768,6 +5789,13 @@ mod tests {.is_none(),"a handoff delivered on a managed SessionStart must be marked accepted");+ assert!(+ fetch_and_accept_handoff(&state, query, None)+ .await+ .unwrap()+ .is_none(),+ "the combined handoff and managed packet must be delivered only once"+ );}fn brief_page(diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rsindex 0a58c479..ced1ada8 100644--- a/crates/ai-memory-store/src/lib.rs+++ b/crates/ai-memory-store/src/lib.rs@@ -60,7 +60,7 @@ pub use workstream::{FinishWorkstreamRun, FinishedWorkstreamRun, ManagedRunContext, PrepareWorkstreamRun,PreparedWorkstreamRun, StoredManagedRunStatus, WorkstreamSelection,};-pub use writer::WriterHandle;+pub use writer::{StartupContextAcceptance, WriterHandle};/// Filename used inside the data dir's `db/` subdirectory.pub const DB_FILENAME: &str = "memory.sqlite";@@ -122,9 +122,9 @@ impl Store {mod tests {use super::*;use ai_memory_core::{- ActorContext, AgentKind, LinkTarget, ManagedRunId, NewObservation, NewPage, NewSession,- NewWorkstreamEvent, ObservationId, ObservationKind, PageId, PagePath, ProjectId, Sanitized,- Sanitizer, SessionId, Tier, UserId, WorkspaceId, WorkstreamEventKind,+ ActorContext, AgentKind, LinkTarget, ManagedRunId, NewHandoff, NewObservation, NewPage,+ NewSession, NewWorkstreamEvent, ObservationId, ObservationKind, PageId, PagePath,+ ProjectId, Sanitized, Sanitizer, SessionId, Tier, UserId, WorkspaceId, WorkstreamEventKind,};use rusqlite::{Connection, params};use sha2::{Digest, Sha256};@@ -4419,6 +4419,84 @@ mod tests {);}+ #[tokio::test]+ async fn startup_context_claim_is_atomic_and_single_use() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let (ws, proj) = open_managed_scope(&store, "startup-claim").await;+ let run = store+ .writer+ .prepare_workstream_run(managed_prepare_input(ws, proj, "test:1"))+ .await+ .unwrap();+ let insert_handoff = || NewHandoff {+ workspace_id: ws,+ project_id: proj,+ from_session_id: None,+ from_agent: AgentKind::ClaudeCode,+ to_agent: None,+ cwd: None,+ summary: "continue".into(),+ open_questions: Vec::new(),+ next_steps: Vec::new(),+ files_touched: Vec::new(),+ };++ let first_handoff = store.writer.insert_handoff(insert_handoff()).await.unwrap();+ let accepted = store+ .writer+ .accept_startup_context(+ Some(first_handoff),+ AgentKind::Codex,+ None,+ Some(run.run_id),+ )+ .await+ .unwrap();+ assert_eq!(+ accepted,+ StartupContextAcceptance {+ handoff_accepted: true,+ managed_context_accepted: true,+ }+ );+ assert!(+ store+ .reader+ .latest_open_handoff(ws, proj, None)+ .await+ .unwrap()+ .is_none()+ );++ let second_handoff = store.writer.insert_handoff(insert_handoff()).await.unwrap();+ let rejected = store+ .writer+ .accept_startup_context(+ Some(second_handoff),+ AgentKind::Codex,+ None,+ Some(run.run_id),+ )+ .await+ .unwrap();+ assert_eq!(+ rejected,+ StartupContextAcceptance::default(),+ "an already-delivered managed packet must reject the whole claim"+ );+ assert_eq!(+ store+ .reader+ .latest_open_handoff(ws, proj, None)+ .await+ .unwrap()+ .map(|handoff| handoff.id),+ Some(second_handoff),+ "a failed managed claim must roll back the handoff transition"+ );+ }+#[tokio::test]async fn run_context_delivers_newest_events_in_sequence_order() {let tmp = TempDir::new().unwrap();diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rsindex 513d48d6..6c08c160 100644--- a/crates/ai-memory-store/src/ops.rs+++ b/crates/ai-memory-store/src/ops.rs@@ -57,7 +57,7 @@ pub struct PurgeSummary {pub embeddings_deleted: u64,}use jiff::Timestamp;-use rusqlite::{Connection, OptionalExtension, params};+use rusqlite::{Connection, OptionalExtension, Transaction, params};use sha2::{Digest, Sha256};use crate::error::{StoreError, StoreResult};@@ -1242,11 +1242,22 @@ pub fn accept_handoff(accepting_agent: AgentKind,accepting_session: Option<&SessionId>,) -> StoreResult<()> {+ let tx = conn.transaction()?;+ accept_handoff_in_transaction(&tx, handoff_id, accepting_agent, accepting_session)?;+ tx.commit()?;+ Ok(())+}++pub(crate) fn accept_handoff_in_transaction(+ tx: &Transaction<'_>,+ handoff_id: &HandoffId,+ accepting_agent: AgentKind,+ accepting_session: Option<&SessionId>,+) -> StoreResult<bool> {let now = Timestamp::now().as_microsecond();let agent = accepting_agent.as_str();let session: Option<&[u8]> = accepting_session.map(|s| &s.as_bytes()[..]);- let tx = conn.transaction()?;- let (ws, proj) = handoff_scope(&tx, handoff_id)?;+ let (ws, proj) = handoff_scope(tx, handoff_id)?;let changed = tx.execute("UPDATE handoffs SET state = 'accepted', accepted_by = ?1, accepted_at = ?2, \accepted_by_session = ?3 \@@ -1256,7 +1267,7 @@ pub fn accept_handoff(// Only a real state transition ('open' -> 'accepted') is audited.if changed > 0 {audit(- &tx,+ tx,"accept_handoff",ws.as_ref(),proj.as_ref(),@@ -1265,8 +1276,7 @@ pub fn accept_handoff(now,)?;}- tx.commit()?;- Ok(())+ Ok(changed > 0)}/// Mark an open handoff expired so it will no longer be consumed.diff --git a/crates/ai-memory-store/src/workstream.rs b/crates/ai-memory-store/src/workstream.rsindex b792d89c..a26e2bc3 100644--- a/crates/ai-memory-store/src/workstream.rs+++ b/crates/ai-memory-store/src/workstream.rs@@ -517,13 +517,31 @@ pub(crate) fn link_native_session(/// Mark the assigned synchronization packet delivered to SessionStart.pub(crate) fn accept_context(conn: &mut Connection, run_id: ManagedRunId) -> StoreResult<bool> {- let now = Timestamp::now().as_microsecond();let tx = conn.transaction()?;+ let accepted = accept_context_in_transaction(&tx, run_id, false)?;+ tx.commit()?;+ Ok(accepted)+}++pub(crate) fn claim_context_in_transaction(+ tx: &Transaction<'_>,+ run_id: ManagedRunId,+) -> StoreResult<bool> {+ accept_context_in_transaction(tx, run_id, true)+}++fn accept_context_in_transaction(+ tx: &Transaction<'_>,+ run_id: ManagedRunId,+ require_undelivered: bool,+) -> StoreResult<bool> {+ let now = Timestamp::now().as_microsecond();let run: Option<(Vec<u8>, String, Option<String>, i64)> = tx.query_row("SELECT workstream_id, agent_kind, native_session_id, sync_through \- FROM managed_runs WHERE id = ?1 AND state = 'active'",- params![run_id.as_bytes()],+ FROM managed_runs WHERE id = ?1 AND state = 'active' \+ AND (?2 = 0 OR context_delivered = 0)",+ params![run_id.as_bytes(), i64::from(require_undelivered)],|row| Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?)),).optional()?;@@ -543,7 +561,6 @@ pub(crate) fn accept_context(conn: &mut Connection, run_id: ManagedRunId) -> Stoparams![sync_through, now, workstream, agent, native_session],)?;}- tx.commit()?;Ok(true)}diff --git a/crates/ai-memory-store/src/writer.rs b/crates/ai-memory-store/src/writer.rsindex 1d986633..0a31bc59 100644--- a/crates/ai-memory-store/src/writer.rs+++ b/crates/ai-memory-store/src/writer.rs@@ -31,6 +31,15 @@ use crate::workstream::{FinishWorkstreamRun, FinishedWorkstreamRun, PrepareWorkstreamRun, PreparedWorkstreamRun,};+/// Result of atomically claiming the startup context assembled for one hook.+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]+pub struct StartupContextAcceptance {+ /// The requested single-use handoff changed from open to accepted.+ pub handoff_accepted: bool,+ /// The requested managed synchronization packet changed to delivered.+ pub managed_context_accepted: bool,+}+/// Commands accepted by the writer thread.pub(crate) enum WriteCmd {GetOrCreateWorkspace {@@ -294,6 +303,13 @@ pub(crate) enum WriteCmd {run_id: ManagedRunId,reply: oneshot::Sender<StoreResult<bool>>,},+ AcceptStartupContext {+ handoff_id: Option<HandoffId>,+ accepting_agent: AgentKind,+ accepting_session: Option<SessionId>,+ managed_run_id: Option<ManagedRunId>,+ reply: oneshot::Sender<StoreResult<StartupContextAcceptance>>,+ },FinishWorkstreamRun {input: FinishWorkstreamRun,reply: oneshot::Sender<StoreResult<FinishedWorkstreamRun>>,@@ -1175,6 +1191,30 @@ impl WriterHandle {rx.await.map_err(|_| StoreError::WriterClosed)?}+ /// Atomically claim the handoff and managed ledger selected for one+ /// SessionStart response.+ ///+ /// When a managed run was requested but is no longer claimable, the+ /// handoff remains open and both result fields are false.+ pub async fn accept_startup_context(+ &self,+ handoff_id: Option<HandoffId>,+ accepting_agent: AgentKind,+ accepting_session: Option<SessionId>,+ managed_run_id: Option<ManagedRunId>,+ ) -> StoreResult<StartupContextAcceptance> {+ let (tx, rx) = oneshot::channel();+ self.send(WriteCmd::AcceptStartupContext {+ handoff_id,+ accepting_agent,+ accepting_session,+ managed_run_id,+ reply: tx,+ })+ .await?;+ rx.await.map_err(|_| StoreError::WriterClosed)?+ }+/// Index an immutable transcript segment and release the run lease.pub async fn finish_workstream_run(&self,@@ -1587,6 +1627,41 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {let result = crate::workstream::accept_context(&mut conn, run_id);send_or_warn(reply, result, "accept_managed_run_context");}+ WriteCmd::AcceptStartupContext {+ handoff_id,+ accepting_agent,+ accepting_session,+ managed_run_id,+ reply,+ } => {+ let result = (|| {+ let tx = conn.transaction()?;+ let managed_context_accepted = match managed_run_id {+ Some(run_id) => {+ crate::workstream::claim_context_in_transaction(&tx, run_id)?+ }+ None => false,+ };+ if managed_run_id.is_some() && !managed_context_accepted {+ return Ok(StartupContextAcceptance::default());+ }+ let handoff_accepted = match handoff_id {+ Some(handoff_id) => ops::accept_handoff_in_transaction(+ &tx,+ &handoff_id,+ accepting_agent,+ accepting_session.as_ref(),+ )?,+ None => false,+ };+ tx.commit()?;+ Ok(StartupContextAcceptance {+ handoff_accepted,+ managed_context_accepted,+ })+ })();+ send_or_warn(reply, result, "accept_startup_context");+ }WriteCmd::FinishWorkstreamRun { input, reply } => {let result = crate::workstream::finish_run(&mut conn, &input);send_or_warn(reply, result, "finish_workstream_run");diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 82d36fb5..7869e110 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -118,6 +118,9 @@ session, and marks lifecycle calls with an invocation-scoped run id.SessionStart injects an unseen bounded event range; Crush receives it through atemporary supported global-context path because it lacks SessionStart. The hostimports the native transcript tail and a Git checkpoint when the child exits.+An explicitly pending handoff is delivered before the managed event range;+their single-use delivery claims share one writer transaction after the+complete startup response has been assembled.ai-memory opens native stores read-only. Raw sanitized JSONL segments areimmutable, while SQLite supplies monotonic sequences, FTS, nativesource/delivery cursors, and idempotent retry state. A full-ledgerdiff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex a2d94e73..eed8323b 100644--- a/docs/design-decisions.md+++ b/docs/design-decisions.md@@ -300,10 +300,13 @@ are excluded explicitly.A renewable single-writer lease resolves precedence and concurrency instead ofattempting bidirectional file synchronization. SessionStart receives a bounded-unseen delta; the full visible ledger stays searchable. Repository checkpoints-are evidence at run boundaries and never commit, stash, reset, or otherwise-mutate the checkout. The markdown wiki remains the durable knowledge surface;-the managed ledger is an operational continuity substrate.+unseen delta without replacing an explicitly pending handoff. When both exist,+the curated handoff is rendered first and their delivery claims commit+atomically after the complete startup response is assembled. The full visible+ledger stays searchable. Repository checkpoints are evidence at run boundaries+and never commit, stash, reset, or otherwise mutate the checkout. The markdown+wiki remains the durable knowledge surface; the managed ledger is an+operational continuity substrate.Native-session adoption is restricted to bootstrapping an otherwise-emptyworkstream. The interactive launcher may offer recent sessions recorded for thediff --git a/docs/managed-workstreams.md b/docs/managed-workstreams.mdindex 24991cde..c22ee7fd 100644--- a/docs/managed-workstreams.md+++ b/docs/managed-workstreams.md@@ -94,8 +94,11 @@ consume the later adoption opportunity.The UserPromptSubmit hook issues the `/handoff` GET with the native`session_id` in the query; the server links the session and renders thepacket atomically, and Kimi Code injects the hook's stdout as a user- message before the turn. Direct launches continue to use the existing- single-use handoff path.+ message before the turn. A pending single-use handoff remains additive:+ it is placed before the managed packet, and both delivery claims commit+ together only after the full handoff/packet/brief response is assembled.+ Direct launches continue to use the same handoff path without a managed+ packet.4. When the child exits, ai-memory reads the native transcript store withoutmodifying it. Visible user/assistant messages, completed tool calls/results,compaction summaries, and a non-mutating Git checkpoint enter an append-only