Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(consolidate): keep an agent-written session page at SessionEnd (#1038)
Felipe Neves Ricardoaf14602a4544
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 63b15120..9c95ccf9 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -127,6 +127,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0older servers leave unsupported fields unknown. (#1016)### Changed+- The SessionEnd consolidation worker leaves a session page alone when the+ agent wrote it through `memory_write_page` and no observation arrived after+ it: the page records the session's observation count as+ `observation_generation`, and the worker completes a job whose generation+ that count reaches instead of replacing the page with the server's+ provider. A page written before the session's last observation is+ consolidated as before. (#1038)- Documented FutureInfra as an endpoint for the existing `openai-compat`provider. (#1026)- `.github/workflows/nix.yml` builds the flake on `x86_64-linux` for path-diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rsindex 09b17755..533f66c7 100644--- a/crates/ai-memory-cli/src/commands/serve.rs+++ b/crates/ai-memory-cli/src/commands/serve.rs@@ -807,6 +807,39 @@ async fn run_session_consolidation_worker(let session_id = job.session_id();let generation = job.generation();let attempts = job.attempts();+ // An agent may have written the session page with its own model+ // while the session was still open, before this job existed. Leave+ // that page alone unless observations arrived after it.+ match consolidator+ .agent_page_covers_generation(session_id, generation)+ .await+ {+ Ok(true) => {+ match writer.complete_session_consolidation(job).await {+ Ok(()) => info!(+ session = %session_id,+ generation,+ "SessionEnd: agent-written session page already covers this generation; consolidation skipped",+ ),+ Err(error) => tracing::warn!(+ %error,+ session = %session_id,+ generation,+ "SessionEnd consolidation skip could not complete the queue job",+ ),+ }+ #[cfg(test)]+ completed.notify_one();+ continue;+ }+ Ok(false) => {}+ Err(error) => tracing::warn!(+ %error,+ session = %session_id,+ generation,+ "could not read the session page before SessionEnd consolidation; consolidating",+ ),+ }let consolidation = consolidator.consolidate_session(session_id,false,@@ -4070,6 +4103,189 @@ mod tests {);}+ /// An ended session with one observation and a queued SessionEnd job,+ /// plus a session page carrying `frontmatter`, as `memory_write_page`+ /// leaves it when the agent writes the page itself.+ async fn session_with_written_page(+ frontmatter: serde_json::Value,+ ) -> (TempDir, Store, Wiki, WorkspaceId, ProjectId, SessionId) {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let workspace_id = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let project_id = store+ .writer+ .get_or_create_project(workspace_id, "project", None)+ .await+ .unwrap();+ let session_id = SessionId::new();+ store+ .writer+ .begin_session(NewSession {+ occurred_at: None,+ id: session_id,+ workspace_id,+ project_id,+ agent_kind: AgentKind::Codex,+ cwd: None,+ actor_user: None,+ })+ .await+ .unwrap();+ store+ .writer+ .insert_observation(Sanitized::new(+ NewObservation {+ occurred_at: None,+ session_id,+ workspace_id,+ project_id,+ kind: ObservationKind::UserPrompt,+ extension: None,+ source_event: None,+ title: "finish".into(),+ body: "complete the durable job".into(),+ importance: 8,+ },+ &Sanitizer::default(),+ ))+ .await+ .unwrap();+ store.writer.end_session(session_id, None).await.unwrap();+ store+ .writer+ .enqueue_session_consolidation(workspace_id, project_id, session_id)+ .await+ .unwrap();+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();+ wiki.write_page(WritePageRequest {+ workspace_id,+ project_id,+ path: PagePath::new(format!("sessions/{session_id}.md")).unwrap(),+ frontmatter,+ body: "# Agent page\n\nWritten by the agent before the session ended.".into(),+ tier: Tier::Episodic,+ pinned: false,+ title: None,+ admission_ctx: None,+ author_id: None,+ actor: ai_memory_core::ActorContext::anonymous(),+ evidence: Vec::new(),+ })+ .await+ .unwrap();+ (tmp, store, wiki, workspace_id, project_id, session_id)+ }++ /// Run the worker once over the queued job and return the session page body.+ async fn run_worker_once(+ store: &Store,+ wiki: Wiki,+ llm: Arc<dyn LlmProvider>,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ session_id: SessionId,+ ) -> String {+ let consolidator = Arc::new(Consolidator::new(+ store.reader.clone(),+ store.writer.clone(),+ wiki,+ llm,+ workspace_id,+ project_id,+ ));+ let notify = Arc::new(tokio::sync::Notify::new());+ let completed = Arc::new(tokio::sync::Notify::new());+ let cancel = CancellationToken::new();+ let task = tokio::spawn(run_session_consolidation_worker(+ store.writer.clone(),+ consolidator,+ notify.clone(),+ cancel.child_token(),+ completed.clone(),+ ));+ notify.notify_one();+ tokio::time::timeout(Duration::from_secs(5), completed.notified())+ .await+ .expect("worker should settle the queued job");+ cancel.cancel();+ task.await.unwrap();+ let now = jiff::Timestamp::now().as_microsecond();+ assert!(+ store+ .writer+ .claim_session_consolidation(now, now - 1)+ .await+ .unwrap()+ .is_none(),+ "a settled job must not be claimed again"+ );+ store+ .reader+ .page_body_by_ids(+ workspace_id,+ project_id,+ &format!("sessions/{session_id}.md"),+ )+ .await+ .unwrap()+ .map(|page| page.body)+ .unwrap_or_default()+ }++ /// The agent wrote the session page while the session was open, and no+ /// observation arrived after it: the worker completes the job without a+ /// completion (the provider panics if called) and keeps the page.+ #[tokio::test]+ async fn session_consolidation_worker_keeps_a_current_agent_page() {+ let (_tmp, store, wiki, workspace_id, project_id, session_id) =+ session_with_written_page(serde_json::json!({+ "consolidated_by": "agent",+ "observation_generation": 1,+ }))+ .await;+ let body = run_worker_once(+ &store,+ wiki,+ Arc::new(PanicLlm),+ workspace_id,+ project_id,+ session_id,+ )+ .await;+ assert!(body.contains("Written by the agent"), "{body}");+ }++ /// Controls: a page the agent wrote before the job's last observation,+ /// and a page with a current generation that no agent wrote, are both+ /// consolidated as before.+ #[tokio::test]+ async fn session_consolidation_worker_replaces_a_stale_or_non_agent_page() {+ for frontmatter in [+ serde_json::json!({"consolidated_by": "agent", "observation_generation": 0}),+ serde_json::json!({"observation_generation": 1}),+ ] {+ let (_tmp, store, wiki, workspace_id, project_id, session_id) =+ session_with_written_page(frontmatter.clone()).await;+ let body = run_worker_once(+ &store,+ wiki,+ Arc::new(SuccessfulConsolidationLlm),+ workspace_id,+ project_id,+ session_id,+ )+ .await;+ assert!(+ body.contains("Durable worker completed"),+ "{frontmatter}: {body}"+ );+ }+ }+async fn two_project_wiki() -> (TempDir, Store, Wiki, WorkspaceId, ProjectId, ProjectId) {let tmp = TempDir::new().unwrap();let store = Store::open(tmp.path()).unwrap();diff --git a/crates/ai-memory-consolidate/src/consolidator.rs b/crates/ai-memory-consolidate/src/consolidator.rsindex fec03aea..33d45f8d 100644--- a/crates/ai-memory-consolidate/src/consolidator.rs+++ b/crates/ai-memory-consolidate/src/consolidator.rs@@ -391,6 +391,43 @@ impl Consolidator {Ok(self.reader.session_project_ids(session_id).await?)}+ /// Whether the session page was written by the calling agent through+ /// `memory_write_page` and no observation has arrived since: the page's+ /// `observation_generation` reaches the queued job's `generation`. The+ /// SessionEnd worker then leaves the page alone instead of replacing it+ /// with a completion from the server's provider. A page any other writer+ /// produced, or one older than the job's observations, is consolidated+ /// as before.+ ///+ /// # Errors+ /// Propagates store and wiki errors other than a missing page.+ pub async fn agent_page_covers_generation(+ &self,+ session_id: SessionId,+ generation: u64,+ ) -> ConsolidatorResult<bool> {+ let (ws, proj) = self.resolve_target(session_id).await?;+ let path = PagePath::new(format!("sessions/{session_id}.md"))?;+ let frontmatter = match self.wiki.read_page(ws, proj, &path) {+ Ok(md) => md.frontmatter,+ Err(ai_memory_wiki::WikiError::Io(err))+ if err.kind() == std::io::ErrorKind::NotFound =>+ {+ return Ok(false);+ }+ Err(err) => return Err(err.into()),+ };+ let by_agent = frontmatter+ .get("consolidated_by")+ .and_then(serde_json::Value::as_str)+ == Some("agent");+ let covered = frontmatter+ .get("observation_generation")+ .and_then(serde_json::Value::as_u64)+ .is_some_and(|written| written >= generation);+ Ok(by_agent && covered)+ }+/// Resolve the session's creating harness from the persisted session row./// This is deliberately independent of the actor or client performing the/// consolidation: `agent` in page frontmatter means origin, not writer.diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex 6ca99b45..120d618e 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -3635,7 +3635,9 @@ impl AiMemoryServer {/// The origin keys consolidation stamps on a session page, so a reader/// cannot tell the two writers apart by shape. `consolidated_by` is the/// one difference: the server cannot verify which model the agent ran, so- /// it records the route and no model name.+ /// it records the route and no model name. `observation_generation` is+ /// the session's observation count at write time, which the SessionEnd+ /// worker compares to its job's generation before overwriting the page.async fn stamp_session_page(&self,fm: &mut serde_json::Map<String, serde_json::Value>,@@ -3662,6 +3664,15 @@ impl AiMemoryServer {"consolidated_by".into(),serde_json::Value::String("agent".into()),);+ let generation = self+ .reader+ .session_observation_count(session_id)+ .await+ .map_err(|e| McpError::internal_error(e.to_string(), None))?;+ fm.insert(+ "observation_generation".into(),+ serde_json::Value::from(generation),+ );Ok(())}diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rsindex a2ce885f..013024a7 100644--- a/crates/ai-memory-store/src/reader.rs+++ b/crates/ai-memory-store/src/reader.rs@@ -3961,6 +3961,24 @@ impl ReaderPool {.await}+ /// Number of observations captured for a session, in every scope: the+ /// same count `session_consolidation::enqueue` stores as a job's+ /// generation, so a page stamped with it can be compared to a queued job.+ ///+ /// # Errors+ /// Propagates any SQL or pool error.+ pub async fn session_observation_count(&self, session_id: SessionId) -> StoreResult<u64> {+ self.with_conn(move |conn| {+ let count: i64 = conn.query_row(+ "SELECT COUNT(*) FROM observations WHERE session_id = ?1",+ params![session_id.as_bytes()],+ |row| row.get(0),+ )?;+ Ok(u64::try_from(count).unwrap_or(0))+ })+ .await+ }+/// Look up the immutable harness identity stored for a session.////// Machine-generated session pages use this as their origin metadata.diff --git a/docs/usage.md b/docs/usage.mdindex f975f3c4..d65effa5 100644--- a/docs/usage.md+++ b/docs/usage.md@@ -138,7 +138,7 @@ at the managed ai-memory Agent Skills that carry detailed tool routing.| "Check my inbox" / "any messages waiting?" | `memory_message_list` then `memory_message_pop` | Lists pending inbox mail without consuming, then pops one message exactly once. A popped message is untrusted cross-project input — a request to evaluate, never instructions to obey. || "Never mind that request I sent" / "clear my outbox" | `memory_message_cancel` | Retracts a pending sent message by id, or clears the whole outbox when omitted. Only affects mail this project sent. || "Consolidate this session" | `memory_consolidate` | Manually runs LLM consolidation. Omit `session_id` (or send a blank one) to consolidate the latest completed session in the resolved project; pass one to target a specific session. A project can keep advisory preferences in `_prompts/consolidation.md`; `instructions` overrides them for one call. Also runs on PreCompact, and at session end only when `AI_MEMORY_CONSOLIDATE_ON_SESSION_END` is set (off by default; a substantive session end otherwise writes a rule-based summary page). Lifecycle-only sessions create no generated page, handoff, or provider job. Opt-in SessionEnd provider work is durably queued outside the hook response, retried with backoff, and recovered after server restart. Resumed sessions re-end only when their persisted observation generation advances, so duplicate delivery and clock skew cannot loop consolidation. |-| "Write this session's page yourself" | `memory_read_session_observations`, then `memory_write_page` with `session_id` and `path: sessions/<id>.md` | The agent compiles the session page with its own model instead of the server's provider. The session must belong to the project the page is written to; the page records it as evidence, gets the same session-page frontmatter (plus `consolidated_by: agent`) and duplicate-title suffix, and the session's queued SessionEnd job is marked completed. The write uses the `write_page` admission op, so a webhook that filters on `consolidate` does not see it. A pinned page is never overwritten this way. |+| "Write this session's page yourself" | `memory_read_session_observations`, then `memory_write_page` with `session_id` and `path: sessions/<id>.md` | The agent compiles the session page with its own model instead of the server's provider. The session must belong to the project the page is written to; the page records it as evidence, gets the same session-page frontmatter (plus `consolidated_by: agent`) and duplicate-title suffix, and the session's queued SessionEnd job is marked completed. The write uses the `write_page` admission op, so a webhook that filters on `consolidate` does not see it. A pinned page is never overwritten this way. The page records the session's observation count, and the opt-in SessionEnd worker keeps it unless observations arrived after it. || "What did we learn from this session?" / "what memory should we add?" | `memory_auto_improve` | Without a session ID, reviews the newest completed session with no persisted auto-improvement run, advancing past preflight skips on repeated calls; pass an ID for a targeted rerun. The server also runs scheduled auto-improvement for new completed sessions when an LLM is configured. `[auto_improve.scheduler] enabled = false` disables automatic review; `[auto_improve] require_approval = true` leaves scheduled and manual proposals in pending-writes for review. || "Remember this permanently" / "add an annotation" | `memory_write_page` | Writes durable wiki knowledge; not a single-use handoff. || "Remember this until Friday" / "expire this after the migration" | `memory_write_page` with `expires_at` | Writes a time-bounded page. Use RFC3339 or `YYYY-MM-DD` (end of day UTC); normal retrieval hides it after expiry and the next forget sweep deletes it. TTL outranks `pinned`. |