Skip to content

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.md
index 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.0
older 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.md
index 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`. |