Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

feat: report session consolidation job state

Éverton Toffanetto5d90d09f2cfd
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4ce62d08..83ccff79 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Added
+- Added the latest scoped consolidation job's state and attempt count to HTTP
+ session summaries and MCP `memory_read_session_observations`. The field is
+ `null` when no job exists; provider errors remain private and existing session
+ ownership filters are preserved. (#1010)
+
## [2.5.2] - 2026-10-01
### Added
diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rs
index 08284fcd..ab8e5a67 100644
--- a/crates/ai-memory-store/src/lib.rs
+++ b/crates/ai-memory-store/src/lib.rs
@@ -80,9 +80,9 @@ pub use reader::{
ObservationPageResult, ObservationRecord, OpenSession, PageAuthor, PageHit, PageHitWithMeta,
PageLinks, PageMeta, PageSummary, ProjectSummary, RELATED_WALK_MAX_DEPTH,
RELATED_WALK_MAX_NODES, ReaderPool, ReindexTargetStatus, RelatedNode, RelatedPage,
- RrfContributions, ScopeRow, SearchExplain, SessionDependentRows, SessionEndDisposition,
- SessionSummary, SettledPage, StatusCounts, StorageStatus, StoredEmbedding, StoredPageBody,
- WorkspaceScopeRow, WorkspaceSummary, f32_vec_to_bytes,
+ RrfContributions, ScopeRow, SearchExplain, SessionConsolidationSummary, SessionDependentRows,
+ SessionEndDisposition, SessionSummary, SettledPage, StatusCounts, StorageStatus,
+ StoredEmbedding, StoredPageBody, WorkspaceScopeRow, WorkspaceSummary, f32_vec_to_bytes,
};
pub use retrieval_tuning::{RetrievalTuning, is_session_recall_query};
pub use scope::{
diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rs
index 40136c20..25d02069 100644
--- a/crates/ai-memory-store/src/reader.rs
+++ b/crates/ai-memory-store/src/reader.rs
@@ -837,6 +837,15 @@ pub struct OpenSession {
pub cwd: Option<String>,
}
+/// Public state and attempt count for the latest scoped consolidation job.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct SessionConsolidationSummary {
+ /// Latest generation state, without provider diagnostics.
+ pub state: String,
+ /// Provider attempts spent on this generation.
+ pub attempts: u32,
+}
+
/// One session as listed from a scope by [`ReaderPool::sessions_for_scope`]
/// and [`ReaderPool::session_summary_scoped`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
@@ -856,6 +865,8 @@ pub struct SessionSummary {
pub observation_count: u64,
/// Operator the session belongs to, as stored on the `sessions` row.
pub actor_user: Option<String>,
+ /// Latest consolidation generation in the requested scope, if present.
+ pub consolidation: Option<SessionConsolidationSummary>,
}
/// Aggregate MCP tool-call counts for one client, from
@@ -3473,8 +3484,14 @@ impl ReaderPool {
"SELECT s.id, s.cwd, s.agent_kind, s.started_at, s.ended_at, s.actor_user, \
(SELECT COUNT(*) FROM observations o \
WHERE o.session_id = s.id \
- AND o.workspace_id = :ws AND o.project_id = :proj) AS n \
+ AND o.workspace_id = :ws AND o.project_id = :proj) AS n, \
+ j.state, j.attempts \
FROM sessions s \
+ LEFT JOIN session_consolidation_jobs j ON j.session_id = s.id \
+ AND j.workspace_id = :ws AND j.project_id = :proj \
+ AND j.generation = (SELECT MAX(latest.generation) \
+ FROM session_consolidation_jobs latest WHERE latest.session_id = s.id \
+ AND latest.workspace_id = :ws AND latest.project_id = :proj) \
WHERE 1 = 1{membership}{owner_clause}{ended_clause} \
ORDER BY s.started_at DESC, s.id DESC \
LIMIT :limit OFFSET :offset"
@@ -3506,12 +3523,30 @@ impl ReaderPool {
let actor_user: Option<String> = row.get(5)?;
let n: i64 = row.get(6)?;
Ok((
- id_bytes, cwd, agent_kind, started_us, ended_us, actor_user, n,
+ id_bytes,
+ cwd,
+ agent_kind,
+ started_us,
+ ended_us,
+ actor_user,
+ n,
+ row.get::<_, Option<String>>(7)?,
+ row.get::<_, Option<u32>>(8)?,
))
})?;
let mut out = Vec::new();
for row in rows {
- let (id_bytes, cwd, agent_kind, started_us, ended_us, actor_user, n) = row?;
+ let (
+ id_bytes,
+ cwd,
+ agent_kind,
+ started_us,
+ ended_us,
+ actor_user,
+ n,
+ state,
+ attempts,
+ ) = row?;
let started_at = jiff::Timestamp::from_microsecond(started_us)
.map(|ts| ts.to_string())
.unwrap_or_default();
@@ -3526,6 +3561,9 @@ impl ReaderPool {
ended_at,
observation_count: u64::try_from(n).unwrap_or(0),
actor_user,
+ consolidation: state
+ .zip(attempts)
+ .map(|(state, attempts)| SessionConsolidationSummary { state, attempts }),
});
}
Ok(out)
diff --git a/crates/ai-memory-store/tests/suite/session_observations.rs b/crates/ai-memory-store/tests/suite/session_observations.rs
index 8a13f3ff..0d22b40a 100644
--- a/crates/ai-memory-store/tests/suite/session_observations.rs
+++ b/crates/ai-memory-store/tests/suite/session_observations.rs
@@ -566,3 +566,60 @@ async fn session_summary_scoped_narrows_the_listing_predicates() {
"unknown id",
);
}
+
+#[tokio::test]
+async fn consolidation_summary_latest_generation_is_scope_and_owner_bound() {
+ let (_tmp, store) = open_seeded();
+ let conn = Connection::open(store.db_path()).unwrap();
+ for (sid, proj, generation, state, attempts) in [
+ (10, proj_a(), 1, "superseded", 1),
+ (10, proj_a(), 2, "pending", 2),
+ (12, proj_b(), 1, "completed", 1),
+ ] {
+ conn.execute("INSERT INTO session_consolidation_jobs
+ (session_id, workspace_id, project_id, generation, state, requested_at, next_attempt_at, attempts)
+ VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?6, ?7)",
+ params![session(sid).as_bytes(), ws().as_bytes(), proj.as_bytes(), generation, state, NOW, attempts]).unwrap();
+ }
+ let summary = store
+ .reader
+ .session_summary_scoped(ws(), proj_a(), session(10), OwnerFilter::Any)
+ .await
+ .unwrap()
+ .unwrap();
+ let job = summary.consolidation.unwrap();
+ assert_eq!((job.state.as_str(), job.attempts), ("pending", 2));
+ let summary = store
+ .reader
+ .session_summary_scoped(ws(), proj_a(), session(12), filter_for("alice"))
+ .await
+ .unwrap()
+ .unwrap();
+ assert!(
+ summary.consolidation.is_none(),
+ "foreign job must not leak through cross-project observations"
+ );
+ assert!(
+ store
+ .reader
+ .session_summary_scoped(ws(), proj_a(), session(12), filter_for("bob"))
+ .await
+ .unwrap()
+ .is_none()
+ );
+ assert!(
+ store
+ .reader
+ .session_summary_scoped(ws(), proj_b(), session(13), OwnerFilter::Any)
+ .await
+ .unwrap()
+ .is_none()
+ );
+ let summary = store
+ .reader
+ .session_summary_scoped(ws(), proj_b(), session(12), filter_for("alice"))
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(summary.consolidation.unwrap().state, "completed");
+}
diff --git a/crates/ai-memory-web/tests/suite/routes.rs b/crates/ai-memory-web/tests/suite/routes.rs
index ccc8c010..2e174762 100644
--- a/crates/ai-memory-web/tests/suite/routes.rs
+++ b/crates/ai-memory-web/tests/suite/routes.rs
@@ -1271,6 +1271,32 @@ async fn api_sessions_lists_completed_sessions_for_the_scope() {
assert_eq!(sessions[0]["session_id"], completed.to_string());
assert_eq!(sessions[0]["observation_count"], 1);
assert!(sessions[0]["ended_at"].is_string());
+ assert!(
+ sessions[0]
+ .get("consolidation")
+ .is_some_and(serde_json::Value::is_null)
+ );
+
+ store
+ .writer
+ .enqueue_session_consolidation(ws, proj, completed)
+ .await
+ .unwrap();
+ let resp = app
+ .clone()
+ .oneshot(
+ Request::builder()
+ .uri("/workspaces/default/projects/scratch/sessions")
+ .body(Body::empty())
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ let with_job = json_body(resp).await;
+ assert_eq!(
+ with_job["sessions"][0]["consolidation"],
+ serde_json::json!({"state":"pending","attempts":0})
+ );
let resp = app
.oneshot(
@@ -1339,6 +1365,11 @@ async fn api_session_observations_pages_orders_and_caps() {
);
let json = json_body(resp).await;
assert_eq!(json["session"]["session_id"], session_id.to_string());
+ assert!(
+ json["session"]
+ .get("consolidation")
+ .is_some_and(serde_json::Value::is_null)
+ );
assert_eq!(json["total"], 3);
assert_eq!(json["limit"], 2);
assert_eq!(json["offset"], 0);
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 05fd1c36..fd321d71 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -250,6 +250,11 @@ for provenance and stable, namespaced `ingest_key` values for retries. See the
[external capture contract](external-lifecycle.md) for batching, identity and
the limits of this cooperative process-scoped mode.
+Session summaries expose the latest consolidation generation's state and
+attempt count, selected in the same scoped, owner-filtered query. HTTP session
+reads and MCP `memory_read_session_observations` share that summary type; neither
+response includes provider diagnostics.
+
Lifecycle bodies have content limits independent of the 10 MiB HTTP request
limit. User prompts and post-compaction summaries are capped UTF-8-safely at
16 KiB; notification and tool excerpts are capped at 2 KB. Native
diff --git a/docs/frontend-api.md b/docs/frontend-api.md
index d803d403..23c865f4 100644
--- a/docs/frontend-api.md
+++ b/docs/frontend-api.md
@@ -476,12 +476,19 @@ an unnamed caller sees unattributed ones only. Never cached (`no-store`).
"started_at": "2026-08-16T09:12:03.412Z",
"ended_at": "2026-08-16T10:47:55.001Z",
"observation_count": 143,
- "actor_user": null
+ "actor_user": null,
+ "consolidation": {"state": "completed", "attempts": 1}
}
]
}
```
+`consolidation` is `null` when no job exists for that session in the requested
+project. Otherwise it contains the latest generation's state (`pending`,
+`running`, `completed`, `failed` or `superseded`) and attempt count. Jobs are
+selected in the same scope and query as the owner-filtered sessions; provider
+errors are omitted. This reports the job state, not every page's freshness.
+
### 4.12 Session observations
```http
@@ -516,7 +523,8 @@ historical text. Never cached (`no-store`). Same payload as the MCP tool
"started_at": "2026-08-16T09:12:03.412Z",
"ended_at": "2026-08-16T10:47:55.001Z",
"observation_count": 143,
- "actor_user": null
+ "actor_user": null,
+ "consolidation": null
},
"observations": [
{
diff --git a/docs/security-boundaries.md b/docs/security-boundaries.md
index 9027f977..8c651d8d 100644
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@ -22,7 +22,7 @@ boundary not yet built.
| # | Boundary | Enforcing code | Adversarial test(s) | Coverage |
|---|----------|----------------|---------------------|----------|
-| 1 | Per-project isolation (3-tuple) | `ai-memory-store/src/scope.rs` `ScopeResolver::resolve_read_args`/`resolve_write_args`, no-create `lookup_existing_scope`; reader queries filter by `(workspace_id, project_id)` | `store` `scope.rs` read-resolution table tests; `tests/suite/multi_session.rs` | STRONG |
+| 1 | Per-project isolation (3-tuple) | `ai-memory-store/src/scope.rs` `ScopeResolver::resolve_read_args`/`resolve_write_args`, no-create `lookup_existing_scope`; reader queries filter by `(workspace_id, project_id)`; `reader.rs` `sessions_for_scope_filtered` joins only consolidation jobs in the requested workspace and project | `store` `scope.rs` read-resolution table tests; `tests/suite/multi_session.rs`; `session_observations.rs` `consolidation_summary_latest_generation_is_scope_and_owner_bound` (a foreign-scope job is absent; the own latest generation and owner controls pass) | STRONG |
| 1b | Reserved `_global` scope union never leaks a foreign project (#930) | `ai-memory-mcp/src/server.rs` `memory_query` — the union runs for single-project queries (`scopes` empty) and searches **only** `lookup_global_scope`'s reserved `(workspace_id, project_id)`, never an arbitrary project; the double-search guard resolves the *queried* project (named or active) so it can't be tricked into skipping | `server.rs` `global_union_never_leaks_a_foreign_projects_pages` (a third real project's page must not surface via the union; reserved page must), `single_project_query_unions_global_scope_and_multi_scope_skips_it` | STRONG |
| 2 | Workspace isolation | same as #1; same-named project → distinct ids per workspace | `scope.rs` cross-workspace resolution rows; `multi_scope` dedup/validate | STRONG |
| 3 | Multi-user auth ladder | `ai-memory-core/src/actor.rs` `AuthLevel::authorize`; `ai-memory-mcp/src/auth.rs` middleware; `admin.rs` `require_root_for_multiuser_admin` / `require_root` | `admin.rs` `multiuser_admin_routes_reject_db_user_tier` / `…reject_anonymous` / `create_user_as_user_tier_returns_403`; `auth.rs` unknown-bearer 401; `actor.rs` `skip_admission_chain_rejects_db_users` | STRONG |