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.mdindex 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### Deprecateddiff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rsindex 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.rsindex 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.rsindex 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.mdindex 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. Onewriter 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 viaFTS5; lifecycle HookEnvelope JSON is not a complete transcript archive.