Skip to content

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

Rust

fix(store): pin the by-agent capture probe to the session index (#1257)

João Carlos Magalhães de Castro8bb8a41c62c6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index efbd8bbc..4d8ef3d4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,18 @@ and [0.x](docs/changelog/0.x.md).
## [Unreleased]
+### Fixed
+
+- Fixed `GET /admin/sessions/by-agent`, and so `ai-memory doctor` and
+ `ai-memory backfill`, taking minutes on a large project (178 s for 780
+ sessions over 185k observations). Without planner statistics SQLite
+ answered each session's capture probe from the project-wide index and
+ rescanned the whole project once per session; the probe now always uses the
+ session index (0.3 s on the same store). The store also refreshes SQLite's
+ planner statistics on every start (`PRAGMA optimize`), which it had never
+ done. The first start of an existing store analyzes it once (about 12 s for
+ a 1.6 GB store); later starts only check table sizes. (#1257)
+
## [2.6.7] - 2026-10-13
### Deprecated
diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rs
index 0468fc38..0869145b 100644
--- a/crates/ai-memory-store/src/lib.rs
+++ b/crates/ai-memory-store/src/lib.rs
@@ -200,6 +200,19 @@ impl Store {
);
}
+ // Refresh planner statistics, as SQLite recommends for a long-lived
+ // connection. Without `sqlite_stat1` the planner ranks indexes by
+ // equality-column count alone and can pick one that scans a whole
+ // project per row. This analyzes only tables lacking statistics or
+ // grown/shrunk tenfold since the last run, each capped by SQLite's
+ // built-in optimize analysis limit: the first open of a never-analyzed
+ // store pays once (about 12 s for a 1.6 GB store on an ARM VM), later
+ // opens are a size check per table. It runs here, not on a timer,
+ // because ANALYZE does not bump the schema cookie: pooled read
+ // connections keep the statistics they loaded when they opened, and
+ // they all open after this point.
+ conn.execute_batch("PRAGMA optimize=0x10002;")?;
+
let writer = WriterHandle::spawn(conn);
let reader = ReaderPool::new(&db_path, READER_POOL_SOFT_CAP)?;
Ok(Self {
diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rs
index 26ba2701..a3f7108d 100644
--- a/crates/ai-memory-store/src/reader.rs
+++ b/crates/ai-memory-store/src/reader.rs
@@ -3294,7 +3294,8 @@ impl ReaderPool {
/// `since_us` is an inclusive lower bound on `started_at`; `None` counts
/// the project's whole history. The scan rides
/// `idx_sessions_recent (workspace_id, project_id, started_at DESC)`, so
- /// it stays bounded by scope rather than table-wide.
+ /// it stays bounded by scope rather than table-wide, and the per-session
+ /// capture probe is pinned to `idx_observations_session`.
///
/// Ordering is count-descending with an agent-name tiebreak, so equal
/// counts do not reorder between calls.
@@ -3309,31 +3310,7 @@ impl ReaderPool {
since_us: Option<i64>,
) -> StoreResult<Vec<AgentSessionCount>> {
self.with_conn(move |conn| {
- // Same reasoning as `open_sessions_for_scope_agent`: without the
- // owner predicate a shared server reports a teammate's activity as
- // the caller's own.
- let owner_clause = match &owner_filter {
- OwnerFilter::Any => "",
- OwnerFilter::User(_) => " AND (actor_user IS NULL OR actor_user = :actor)",
- OwnerFilter::Unattributed => " AND actor_user IS NULL",
- };
- let since_clause = if since_us.is_some() {
- " AND started_at >= :since"
- } else {
- ""
- };
- let sql = format!(
- "SELECT agent_kind, COUNT(*) AS n, \
- SUM((SELECT COUNT(DISTINCT CASE WHEN o.extension IS NULL \
- THEN 'native' ELSE 'extension:' || o.extension END) \
- FROM observations o WHERE o.session_id = sessions.id \
- AND o.workspace_id = :ws AND o.project_id = :proj) > 1) \
- FROM sessions \
- WHERE workspace_id = :ws AND project_id = :proj\
- {since_clause}{owner_clause} \
- GROUP BY agent_kind \
- ORDER BY n DESC, agent_kind ASC"
- );
+ let sql = session_counts_by_agent_sql(since_us.is_some(), &owner_filter);
let mut stmt = conn.prepare_cached(&sql)?;
let ws_bytes = workspace_id.as_bytes();
let proj_bytes = project_id.as_bytes();
@@ -10420,6 +10397,47 @@ impl ReaderPool {
}
}
+/// Build the per-agent session count query for one scope.
+///
+/// The capture probe keeps its workspace/project predicates because one
+/// session id can carry observations in several projects, and only the
+/// counted project's rows may decide whether a session mixed capture paths.
+/// Those same predicates match the leading columns of
+/// `idx_observations_project_created`, and without `sqlite_stat1` the planner
+/// prefers that two-column equality over the one-column session index. It
+/// then rescans the whole project's observations once per session: 144 s for
+/// 780 sessions over 185k observations, against 0.3 s through the session
+/// index. `INDEXED BY` pins the probe to the index that bounds it by session
+/// whatever the statistics say.
+fn session_counts_by_agent_sql(has_since: bool, owner_filter: &OwnerFilter) -> String {
+ // Same reasoning as `open_sessions_for_scope_agent`: without the owner
+ // predicate a shared server reports a teammate's activity as the
+ // caller's own.
+ let owner_clause = match owner_filter {
+ OwnerFilter::Any => "",
+ OwnerFilter::User(_) => " AND (actor_user IS NULL OR actor_user = :actor)",
+ OwnerFilter::Unattributed => " AND actor_user IS NULL",
+ };
+ let since_clause = if has_since {
+ " AND started_at >= :since"
+ } else {
+ ""
+ };
+ format!(
+ "SELECT agent_kind, COUNT(*) AS n, \
+ SUM((SELECT COUNT(DISTINCT CASE WHEN o.extension IS NULL \
+ THEN 'native' ELSE 'extension:' || o.extension END) \
+ FROM observations o INDEXED BY idx_observations_session \
+ WHERE o.session_id = sessions.id \
+ AND o.workspace_id = :ws AND o.project_id = :proj) > 1) \
+ FROM sessions \
+ WHERE workspace_id = :ws AND project_id = :proj\
+ {since_clause}{owner_clause} \
+ GROUP BY agent_kind \
+ ORDER BY n DESC, agent_kind ASC"
+ )
+}
+
/// Build the bounded history query and its optional owner binding.
///
/// A named operator reads two disjoint ranges: shared (`NULL`) and their own
@@ -11678,6 +11696,56 @@ mod tests {
);
}
+ #[test]
+ fn session_counts_by_agent_probes_observations_through_the_session_index() {
+ // A fresh store has no `sqlite_stat1`, the same state in which a
+ // production store picked the project index and rescanned the whole
+ // project per session.
+ let tmp = tempfile::TempDir::new().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let conn = rusqlite::Connection::open(store.db_path()).unwrap();
+ let ws = WorkspaceId::new();
+ let proj = ProjectId::new();
+ let (ws_bytes, proj_bytes) = (ws.as_bytes(), proj.as_bytes());
+ let (since, actor) = (0_i64, "user:alice");
+ let owners = [
+ OwnerFilter::Any,
+ OwnerFilter::User(actor.into()),
+ OwnerFilter::Unattributed,
+ ];
+ for has_since in [false, true] {
+ for owner in &owners {
+ let sql = super::session_counts_by_agent_sql(has_since, owner);
+ let mut stmt = conn.prepare(&format!("EXPLAIN QUERY PLAN {sql}")).unwrap();
+ let mut named: Vec<(&str, &dyn rusqlite::ToSql)> =
+ vec![(":ws", &ws_bytes), (":proj", &proj_bytes)];
+ if has_since {
+ named.push((":since", &since));
+ }
+ if matches!(owner, OwnerFilter::User(_)) {
+ named.push((":actor", &actor));
+ }
+ let details = stmt
+ .query_map(named.as_slice(), |row| row.get::<_, String>(3))
+ .unwrap()
+ .collect::<Result<Vec<_>, _>>()
+ .unwrap();
+ let probes: Vec<&String> = details
+ .iter()
+ .filter(|detail| detail.starts_with("SEARCH o "))
+ .collect();
+ assert!(
+ !probes.is_empty()
+ && probes
+ .iter()
+ .all(|detail| detail.contains("idx_observations_session")),
+ "since={has_since} owner={owner:?}: the capture probe must be bounded \
+ by session, not by project: {details:?}"
+ );
+ }
+ }
+ }
+
#[test]
fn authority_candidate_window_is_bounded_and_saturating() {
use super::authority_candidate_limit;
diff --git a/crates/ai-memory-store/tests/suite/session_observations.rs b/crates/ai-memory-store/tests/suite/session_observations.rs
index a7f53461..2334a9ec 100644
--- a/crates/ai-memory-store/tests/suite/session_observations.rs
+++ b/crates/ai-memory-store/tests/suite/session_observations.rs
@@ -765,3 +765,24 @@ async fn mixed_capture_count_scopes_observations_and_preserves_owner_and_window(
.is_empty()
);
}
+
+/// Nothing else ever runs ANALYZE, so a store that never refreshed planner
+/// statistics on open kept none for its whole life, and the planner then
+/// rescanned a project's observations once per session for the per-agent
+/// counts. Reopening a populated store must leave statistics for the index
+/// that bounds those probes.
+#[test]
+fn reopening_a_populated_store_records_planner_statistics() {
+ let (tmp, store) = open_seeded();
+ drop(store);
+ let store = Store::open(tmp.path()).unwrap();
+ let conn = Connection::open(store.db_path()).unwrap();
+ let analyzed: i64 = conn
+ .query_row(
+ "SELECT COUNT(*) FROM sqlite_stat1 WHERE idx = 'idx_observations_session'",
+ [],
+ |row| row.get(0),
+ )
+ .unwrap();
+ assert_eq!(analyzed, 1);
+}
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index a7e353d1..7191668e 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -394,7 +394,10 @@ prunable rather than only after it ages in place.
reconciles outside edits.
* `<data_dir>/db/memory.sqlite`: derived index. WAL mode. One
writer actor owns the writer `Connection`; reads go through a
- cloneable read-only pool.
+ cloneable read-only pool. Every open runs `PRAGMA optimize=0x10002`
+ before the pool opens, so planner statistics exist and follow tenfold
+ table growth; the first open of a never-analyzed store pays a one-time
+ limited ANALYZE.
* `<data_dir>/raw/`: immutable sanitized managed-workstream JSONL segments.
Legacy raw fallback recall searches the durable `observations` table via
FTS5; lifecycle HookEnvelope JSON is not a complete transcript archive.