Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(temporal): ingestion-time validity on entity links + as_of queries
AkitaOnRails5e45413ddc15
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex a1b5ca91..edd9b6eb 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Added+- The entity index carries ingestion-time validity windows+ (bi-temporal-lite): entity links open at their page version's creation+ and close when the version is superseded, backfilled for existing+ stores by an additive migration. `memory_query` gains an `as_of`+ ISO-8601 argument that turns the call into an entity-timeline lookup —+ "what did we know about X then" — returning the page versions valid at+ that instant, including ones superseded since. Ingestion time only,+ documented honestly as such. See `docs/temporal.md`.- Pages can declare typed relation edges in `relations:` frontmatter —a closed `causes` / `fixes` / `contradicts` vocabulary riding theexisting `links.link_type` column (no schema migration). Declareddiff --git a/README.md b/README.mdindex 5ab37b53..bbecc672 100644--- a/README.md+++ b/README.md@@ -346,6 +346,7 @@ diagram, crate breakdown, schema notes, and invariants.- [`docs/ROADMAP-2.0.md`](docs/ROADMAP-2.0.md) - the plan for the 2.0 release, one item at a time.- [`docs/okf.md`](docs/okf.md) - the wiki is natively an Open Knowledge Format (OKF v0.2) bundle; design and field mapping.- [`docs/typed-edges.md`](docs/typed-edges.md) - typed relation edges (`causes` / `fixes` / `contradicts`) and how lint uses them.+- [`docs/temporal.md`](docs/temporal.md) - ingestion-time validity on the entity index and `as_of` time-travel queries.- [`docs/MIGRATION-2.0.md`](docs/MIGRATION-2.0.md) - upgrading an existing store to 2.0: the backup-gated automatic migration and how to restore.- [`docs/benchmarks/`](docs/benchmarks/README.md) - published retrieval-quality numbers with provenance, reproducible from the in-repo harness.- [`docs/ROADMAP-2.0.md`](docs/ROADMAP-2.0.md) - the 2.0 plan.diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex 6a378025..db2028d7 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -320,7 +320,10 @@ search EVERY project in EVERY workspace at once when you don't know \where the knowledge lives — each hit then carries its workspace + \project name. `global=true` cannot be combined with \`scopes`/`project`/`workspace`. Don't conclude 'we never recorded \-it' after one project misses. Note also that `memory_query` returns \+it' after one project misses. For \"what did we know about X back \+then\" questions, pass `as_of` (ISO-8601 instant) — the query becomes \+an entity-timeline lookup returning the page versions valid at that \+moment, including ones superseded since. Note also that `memory_query` returns \SNIPPETS, not full page bodies — an empty or short snippet does NOT \mean the page is empty (a large page can match outside the snippet \window); to read the whole page use `memory_read_page` (by `path`, \@@ -507,6 +510,15 @@ struct QueryArgs {/// Default false.#[serde(default)]explain: Option<bool>,+ /// Time-travel: an ISO-8601 instant (e.g. `2026-06-01T00:00:00Z`).+ /// When set, the query becomes an ENTITY-TIMELINE lookup: it returns+ /// the page versions whose entity-link validity windows contained+ /// that instant — what the store knew about the named entities then,+ /// including versions superseded since (docs/temporal.md). FTS /+ /// vector / graph streams are skipped in this mode; cannot be+ /// combined with `global` or `scopes`. Omit for a normal search.+ #[serde(default)]+ as_of: Option<String>,}#[derive(Debug, Serialize, Deserialize, schemars::JsonSchema)]@@ -1906,6 +1918,46 @@ impl AiMemoryServer {));}+ // Time-travel entity lookup (docs/temporal.md): entity stream+ // only, against the ingestion-time validity windows.+ if let Some(raw_as_of) = args.as_of.as_deref().filter(|s| !s.trim().is_empty()) {+ if args.global.unwrap_or(false) || !args.scopes.is_empty() {+ return Err(McpError::internal_error(+ "as_of cannot be combined with global or scopes",+ None,+ ));+ }+ let instant: jiff::Timestamp = raw_as_of.trim().parse().map_err(|e| {+ McpError::internal_error(format!("as_of must be an ISO-8601 instant: {e}"), None)+ })?;+ let (ws, proj) = self+ .effective_ids_for_read_args_with_actor(+ args.workspace.as_deref(),+ args.project.as_deref(),+ &aps_actor,+ )+ .await?;+ let hits = self+ .reader+ .entity_hits_for_project_at(+ ws,+ proj,+ &args.query,+ limit,+ None,+ Some(instant.as_microsecond()),+ )+ .await+ .map_err(|e| McpError::internal_error(e.to_string(), None))?;+ return ok_json(&MemoryQueryResponse {+ hits: hits.into_iter().map(|h| QueryHit::from(h.hit)).collect(),+ raw_hits: Vec::new(),+ global_hits: Vec::new(),+ global_scope_hits: Vec::new(),+ streams_active: explain.then(|| vec!["entity"]),+ });+ }+let query = args.query.clone();let query_vec = self.embed_query(&args.query).await;let candidate_limit = self.rerank_fetch_limit(limit);@@ -4902,6 +4954,7 @@ mod tests {global: None,include_expired: None,explain: Some(true),+ as_of: None,}),test_optional_parts(),)@@ -4932,6 +4985,7 @@ mod tests {global: Some(true),include_expired: None,explain: None,+ as_of: None,}),test_optional_parts(),)@@ -6354,6 +6408,102 @@ mod tests {);}+ /// `as_of` turns memory_query into an entity-timeline lookup+ /// (docs/temporal.md): a superseded version answers for the instant+ /// it was valid, the current version answers for now, and the mode+ /// refuses to combine with global/scopes.+ #[tokio::test]+ async fn memory_query_as_of_travels_the_entity_timeline() {+ let (_tmp, store, server, ws, proj) = setup_server().await;+ let mut v1 = ai_memory_core::NewPage {+ workspace_id: ws,+ project_id: proj,+ path: ai_memory_core::PagePath::new("notes/db.md").unwrap(),+ title: "DB".into(),+ body: "we use postgres".into(),+ tier: ai_memory_core::Tier::Semantic,+ frontmatter_json: serde_json::json!({}),+ pinned: false,+ links: Vec::new(),+ author_id: None,+ expires_at: None,+ entities: vec!["postgres".into()],+ };+ store.writer.upsert_page(v1.clone()).await.unwrap();+ let between = jiff::Timestamp::now().to_string();+ tokio::time::sleep(std::time::Duration::from_millis(5)).await;+ v1.body = "we migrated".into();+ v1.entities = vec!["sqlite".into()];+ store.writer.upsert_page(v1).await.unwrap();++ let args = |as_of: Option<String>, global: Option<bool>| QueryArgs {+ query: "postgres".into(),+ limit: Some(5),+ project: Some("scratch".into()),+ scopes: Vec::new(),+ workspace: Some("default".into()),+ global,+ include_expired: None,+ explain: Some(true),+ as_of,+ };++ // Historical instant → the superseded version answers.+ let result = server+ .memory_query(+ Parameters(args(Some(between), None)),+ OptionalParts(test_parts_default()),+ )+ .await+ .unwrap();+ let text = result+ .content+ .first()+ .and_then(|c| c.as_text())+ .unwrap()+ .text+ .clone();+ assert!(text.contains("notes/db.md"), "{text}");+ assert!(text.contains("\"entity\""), "entity-only mode: {text}");++ // Same query without as_of → no postgres hit anymore... the FTS+ // stream may still match old text? No: default searches latest+ // pages only, whose body says "we migrated".+ let now_result = server+ .memory_query(+ Parameters(args(None, None)),+ OptionalParts(test_parts_default()),+ )+ .await+ .unwrap();+ let now_text = now_result+ .content+ .first()+ .and_then(|c| c.as_text())+ .unwrap()+ .text+ .clone();+ assert!(!now_text.contains("notes/db.md"), "{now_text}");++ // Refusal: as_of + global is ambiguous.+ let err = server+ .memory_query(+ Parameters(args(Some("2026-06-01T00:00:00Z".into()), Some(true))),+ OptionalParts(test_parts_default()),+ )+ .await;+ assert!(err.is_err(), "as_of+global must be refused");++ // Garbage instant is a clear error, not a silent default.+ let bad = server+ .memory_query(+ Parameters(args(Some("not-a-time".into()), None)),+ OptionalParts(test_parts_default()),+ )+ .await;+ assert!(bad.is_err());+ }+#[tokio::test]async fn memory_query_returns_hits_via_tool_method() {let (_tmp, _store, server, _ws, _pj) = setup_server().await;@@ -6368,6 +6518,7 @@ mod tests {global: None,include_expired: None,explain: None,+ as_of: None,}),OptionalParts(test_parts_default()),)@@ -6392,6 +6543,7 @@ mod tests {global: None,include_expired: None,explain: Some(true),+ as_of: None,}),OptionalParts(test_parts_default()),)@@ -6482,6 +6634,7 @@ mod tests {global: None,include_expired: None,explain: Some(true),+ as_of: None,}),OptionalParts(test_parts_default()),)@@ -6567,6 +6720,7 @@ mod tests {global: None,include_expired: None,explain: None,+ as_of: None,};let result = server@@ -6643,6 +6797,7 @@ mod tests {global: None,include_expired: None,explain: None,+ as_of: None,}),OptionalParts(test_parts_default()),)@@ -6770,6 +6925,7 @@ mod tests {global: None,include_expired: None,explain: None,+ as_of: None,}),OptionalParts(test_parts_default()),)@@ -6848,6 +7004,7 @@ mod tests {global: None,include_expired: None,explain: None,+ as_of: None,}),test_optional_parts(),)@@ -6942,6 +7099,7 @@ mod tests {global: None,include_expired: None,explain: None,+ as_of: None,}),test_optional_parts(),)@@ -7007,6 +7165,7 @@ mod tests {global: None,include_expired: None,explain: None,+ as_of: None,}),test_optional_parts(),)@@ -7048,6 +7207,7 @@ mod tests {global: None,include_expired: None,explain: None,+ as_of: None,}),test_optional_parts(),)@@ -7121,6 +7281,7 @@ mod tests {global: None,include_expired: None,explain: None,+ as_of: None,}),test_optional_parts(),)@@ -7185,6 +7346,7 @@ mod tests {global: None,include_expired: None,explain: None,+ as_of: None,}),OptionalParts(test_parts_default()),)@@ -8196,6 +8358,7 @@ mod tests {global: None,include_expired: None,explain: Some(true),+ as_of: None,}),OptionalParts(test_parts_default()),)@@ -8302,6 +8465,7 @@ mod tests {global: Some(true),include_expired: None,explain: Some(true),+ as_of: None,}),OptionalParts(test_parts_default()),)@@ -8348,6 +8512,7 @@ mod tests {global: Some(true),include_expired: Some(true),explain: None,+ as_of: None,}),OptionalParts(test_parts_default()),)@@ -8426,6 +8591,7 @@ mod tests {global: None,include_expired: None,explain: None,+ as_of: None,}),OptionalParts(test_parts_default()),)@@ -8457,6 +8623,7 @@ mod tests {global: None,include_expired: None,explain: None,+ as_of: None,}),OptionalParts(test_parts_default()),)@@ -8492,6 +8659,7 @@ mod tests {global: Some(true),include_expired: None,explain: None,+ as_of: None,}),OptionalParts(test_parts_default()),)@@ -10934,6 +11102,7 @@ mod tests {global: None,include_expired: None,explain: None,+ as_of: None,}),OptionalParts(test_parts_default()),)@@ -10967,6 +11136,7 @@ mod tests {global: None,include_expired: None,explain: None,+ as_of: None,}),OptionalParts(test_parts_default()),)diff --git a/crates/ai-memory-store/migrations/V56__entity_link_validity.sql b/crates/ai-memory-store/migrations/V56__entity_link_validity.sqlnew file mode 100644index 00000000..70dca240--- /dev/null+++ b/crates/ai-memory-store/migrations/V56__entity_link_validity.sql@@ -0,0 +1,24 @@+-- Bi-temporal-lite (2.0 item 4, docs/temporal.md): entity links inherit+-- their page version's ingestion-time timeline. Additive columns ++-- one-shot backfill; no row is deleted or rewritten beyond the two new+-- columns.+--+-- valid_from = created_at of the page version the link belongs to+-- superseded_at = created_at of the version that superseded it+-- (NULL while the version is latest)++ALTER TABLE entity_page_links ADD COLUMN valid_from INTEGER;+ALTER TABLE entity_page_links ADD COLUMN superseded_at INTEGER;++UPDATE entity_page_links+SET valid_from = (SELECT p.created_at FROM pages p WHERE p.id = page_id);++UPDATE entity_page_links+SET superseded_at = (+ SELECT p2.created_at FROM pages p2 WHERE p2.supersedes = page_id+)+WHERE page_id IN (SELECT id FROM pages WHERE is_latest = 0);++-- The as_of window scan: (entity, window) probes ride this.+CREATE INDEX idx_entity_page_links_validity+ ON entity_page_links(entity_id, valid_from, superseded_at);diff --git a/crates/ai-memory-store/src/api_credentials.rs b/crates/ai-memory-store/src/api_credentials.rsindex 5ad79b3f..1c098b75 100644--- a/crates/ai-memory-store/src/api_credentials.rs+++ b/crates/ai-memory-store/src/api_credentials.rs@@ -398,7 +398,9 @@ mod tests {}#[test]- fn schema_stops_at_v55_rollback_bridge() {+ fn schema_top_version_is_pinned() {+ // Deliberate pin: bumping it is part of adding a migration, so a+ // stray or duplicate version number fails loudly here.let mut conn = Connection::open_in_memory().unwrap();conn.pragma_update(None, "foreign_keys", "ON").unwrap();crate::migrations::run(&mut conn).unwrap();@@ -409,7 +411,7 @@ mod tests {|row| row.get(0),).unwrap();- assert_eq!(version, 55);+ assert_eq!(version, 56, "update the pin when adding a migration");let cols: i64 = conn.query_row("SELECT COUNT(*) FROM pragma_table_info('users') WHERE name = 'token_hash'",diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rsindex 8c6ab7d5..7c00b06a 100644--- a/crates/ai-memory-store/src/lib.rs+++ b/crates/ai-memory-store/src/lib.rs@@ -6331,6 +6331,212 @@ mod tests {"active");}+ /// Bi-temporal-lite (docs/temporal.md): entity-link windows follow+ /// page supersession, and `as_of` returns what the store knew at+ /// that instant — including versions that have since been replaced.+ #[tokio::test]+ async fn as_of_returns_the_version_that_was_valid_then() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "temporal", None)+ .await+ .unwrap();++ // v1 carries the entity.+ let mut v1 = sample_page(ws, proj, "notes/db.md", "we use postgres");+ v1.entities = vec!["postgres".into()];+ let v1_id = store.writer.upsert_page(v1).await.unwrap();+ let between = jiff::Timestamp::now().as_microsecond();+ tokio::time::sleep(std::time::Duration::from_millis(5)).await;++ // v2 supersedes; the entity moved on.+ let mut v2 = sample_page(ws, proj, "notes/db.md", "we migrated to sqlite");+ v2.entities = vec!["sqlite".into()];+ let v2_id = store.writer.upsert_page(v2).await.unwrap();+ assert_ne!(v1_id, v2_id);++ // Current query: postgres is gone.+ let now_hits = store+ .reader+ .entity_hits_for_project(ws, proj, "postgres", 10, None)+ .await+ .unwrap();+ assert!(now_hits.is_empty(), "{now_hits:?}");++ // as_of between v1 and v2: the superseded version answers.+ let then_hits = store+ .reader+ .entity_hits_for_project_at(ws, proj, "postgres", 10, None, Some(between))+ .await+ .unwrap();+ assert_eq!(then_hits.len(), 1, "{then_hits:?}");+ assert_eq!(then_hits[0].hit.id, v1_id);++ // as_of now: identical to the default view for the new entity.+ let sqlite_now = store+ .reader+ .entity_hits_for_project_at(+ ws,+ proj,+ "sqlite",+ 10,+ None,+ Some(jiff::Timestamp::now().as_microsecond()),+ )+ .await+ .unwrap();+ assert_eq!(sqlite_now.len(), 1);+ assert_eq!(sqlite_now[0].hit.id, v2_id);++ // And before v1 existed: nothing was known.+ let before = store+ .reader+ .entity_hits_for_project_at(ws, proj, "postgres", 10, None, Some(1))+ .await+ .unwrap();+ assert!(before.is_empty(), "{before:?}");+ }++ /// The windows themselves: insert opens at the version's+ /// `created_at`; supersession closes the old version's links.+ #[tokio::test]+ async fn supersession_closes_the_entity_link_window() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "temporal2", None)+ .await+ .unwrap();+ let mut v1 = sample_page(ws, proj, "notes/x.md", "v1");+ v1.entities = vec!["thing".into()];+ let v1_id = store.writer.upsert_page(v1).await.unwrap();+ let mut v2 = sample_page(ws, proj, "notes/x.md", "v2");+ v2.entities = vec!["thing".into()];+ store.writer.upsert_page(v2).await.unwrap();++ let db = rusqlite::Connection::open(tmp.path().join("db").join("memory.sqlite")).unwrap();+ let rows: Vec<(Vec<u8>, i64, Option<i64>)> = db+ .prepare(+ "SELECT page_id, valid_from, superseded_at FROM entity_page_links \+ ORDER BY valid_from",+ )+ .unwrap()+ .query_map([], |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?)))+ .unwrap()+ .collect::<Result<_, _>>()+ .unwrap();+ assert_eq!(rows.len(), 2, "{rows:?}");+ assert_eq!(rows[0].0, v1_id.as_bytes().to_vec());+ assert!(+ rows[0].2.is_some(),+ "superseded version's window must be closed"+ );+ assert!(rows[1].2.is_none(), "latest version's window stays open");+ assert!(+ rows[0].2.unwrap() >= rows[0].1,+ "window must not be inverted"+ );+ }++ /// The V56 backfill reconstructs the same windows the write path+ /// produces: `valid_from` from each version's `created_at`,+ /// `superseded_at` from the superseding version, NULL for latest.+ #[tokio::test]+ async fn v56_backfill_reconstructs_the_windows() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "backfill", None)+ .await+ .unwrap();+ for body in ["v1", "v2", "v3"] {+ let mut page = sample_page(ws, proj, "notes/x.md", body);+ page.entities = vec!["thing".into()];+ store.writer.upsert_page(page).await.unwrap();+ tokio::time::sleep(std::time::Duration::from_millis(3)).await;+ }++ let db = rusqlite::Connection::open(tmp.path().join("db").join("memory.sqlite")).unwrap();+ let live: Vec<(Vec<u8>, Option<i64>, Option<i64>)> = db+ .prepare(+ "SELECT page_id, valid_from, superseded_at FROM entity_page_links \+ ORDER BY valid_from",+ )+ .unwrap()+ .query_map([], |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?)))+ .unwrap()+ .collect::<Result<_, _>>()+ .unwrap();+ assert_eq!(live.len(), 3);++ // Fabricate the pre-V56 state, then replay the migration's+ // backfill statements.+ db.execute(+ "UPDATE entity_page_links SET valid_from = NULL, superseded_at = NULL",+ [],+ )+ .unwrap();+ db.execute_batch(+ "UPDATE entity_page_links \+ SET valid_from = (SELECT p.created_at FROM pages p WHERE p.id = page_id); \+ UPDATE entity_page_links \+ SET superseded_at = ( \+ SELECT p2.created_at FROM pages p2 WHERE p2.supersedes = page_id \+ ) \+ WHERE page_id IN (SELECT id FROM pages WHERE is_latest = 0);",+ )+ .unwrap();+ let backfilled: Vec<(Vec<u8>, Option<i64>, Option<i64>)> = db+ .prepare(+ "SELECT page_id, valid_from, superseded_at FROM entity_page_links \+ ORDER BY valid_from",+ )+ .unwrap()+ .query_map([], |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?)))+ .unwrap()+ .collect::<Result<_, _>>()+ .unwrap();+ // Same shape: two closed windows, one open; same version order.+ assert_eq!(backfilled.len(), 3);+ for (i, (live_row, back_row)) in live.iter().zip(backfilled.iter()).enumerate() {+ assert_eq!(live_row.0, back_row.0, "row {i} page id");+ assert_eq!(+ live_row.2.is_some(),+ back_row.2.is_some(),+ "row {i} open/closed"+ );+ assert_eq!(back_row.1, {+ let created: i64 = db+ .query_row(+ "SELECT created_at FROM pages WHERE id = ?1",+ rusqlite::params![back_row.0],+ |r| r.get(0),+ )+ .unwrap();+ Some(created)+ });+ }+ }+#[tokio::test]async fn entity_stream_finds_and_weights_pages() {let tmp = TempDir::new().unwrap();diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rsindex 2aa3a9e9..d2a3df54 100644--- a/crates/ai-memory-store/src/ops.rs+++ b/crates/ai-memory-store/src/ops.rs@@ -767,6 +767,13 @@ pub(crate) fn upsert_page_in_tx("UPDATE pages SET is_latest = 0 WHERE id = ?1",params![&existing.id],)?;+ // Close the superseded version's entity-link windows at the new+ // version's birth instant (docs/temporal.md).+ tx.execute(+ "UPDATE entity_page_links SET superseded_at = ?2 \+ WHERE page_id = ?1 AND superseded_at IS NULL",+ params![&existing.id, now],+ )?;tx.execute("INSERT INTO pages \(id, workspace_id, project_id, path, path_search, title, tier, body, body_sha256, \@@ -792,7 +799,7 @@ pub(crate) fn upsert_page_in_tx(],)?;replace_links_in_tx(tx, &new_id, page)?;- attach_entities_in_tx(tx, &new_id, page)?;+ attach_entities_in_tx(tx, &new_id, page, now)?;refresh_incoming_links_for_path(tx, page, &new_id)?;audit(tx,@@ -832,7 +839,7 @@ pub(crate) fn upsert_page_in_tx(],)?;replace_links_in_tx(tx, &new_id, page)?;- attach_entities_in_tx(tx, &new_id, page)?;+ attach_entities_in_tx(tx, &new_id, page, now)?;refresh_incoming_links_for_path(tx, page, &new_id)?;audit(tx,@@ -855,6 +862,7 @@ fn attach_entities_in_tx(tx: &rusqlite::Transaction<'_>,page_id: &PageId,page: &NewPage,+ version_created_at: i64,) -> StoreResult<()> {if page.entities.is_empty() {return Ok(());@@ -877,10 +885,14 @@ fn attach_entities_in_tx(],|row| row.get(0),)?;+ // Bi-temporal-lite (docs/temporal.md): the link's window opens+ // when its page version was created and stays open until the+ // version is superseded (closed in `upsert_page_in_tx`).tx.execute(- "INSERT INTO entity_page_links (entity_id, page_id) VALUES (?1, ?2) \+ "INSERT INTO entity_page_links (entity_id, page_id, valid_from) \+ VALUES (?1, ?2, ?3) \ON CONFLICT (entity_id, page_id) DO NOTHING",- params![entity_id, page_id.as_bytes()],+ params![entity_id, page_id.as_bytes(), version_created_at],)?;}Ok(())diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rsindex 0b3541df..b44e35ba 100644--- a/crates/ai-memory-store/src/reader.rs+++ b/crates/ai-memory-store/src/reader.rs@@ -378,13 +378,13 @@ pub struct FeedbackFinding {/// A page matched by the entity stream, with the inverse-frequency/// weight that ranked it and the entity names that matched.#[derive(Debug, Clone)]-pub(crate) struct EntityHit {+pub struct EntityHit {/// The matched page.- pub(crate) hit: PageHit,+ pub hit: PageHit,/// Sum of `1 / pages_carrying_entity` over the matched entities.- pub(crate) weight: f64,+ pub weight: f64,/// Entity names that matched the query.- pub(crate) matched: Vec<String>,+ pub matched: Vec<String>,}/// Escape a literal for use inside a SQL `LIKE` pattern with@@ -3414,6 +3414,32 @@ impl ReaderPool {query: &str,limit: usize,expiry_cutoff_us: Option<i64>,+ ) -> StoreResult<Vec<EntityHit>> {+ self.entity_hits_for_project_at(+ workspace_id,+ project_id,+ query,+ limit,+ expiry_cutoff_us,+ None,+ )+ .await+ }++ /// Entity hits with an optional ingestion-time instant+ /// (docs/temporal.md). `as_of_us: None` = current knowledge (latest+ /// versions, expiry honoured). `Some(T)` = the page versions whose+ /// entity-link windows contain `T` — expiry is deliberately ignored+ /// there: a page valid at `T` that has since expired was still what+ /// we knew at `T`.+ pub async fn entity_hits_for_project_at(+ &self,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ query: &str,+ limit: usize,+ expiry_cutoff_us: Option<i64>,+ as_of_us: Option<i64>,) -> StoreResult<Vec<EntityHit>> {let tokens = entity_query_tokens(query);if tokens.is_empty() || limit == 0 {@@ -3447,10 +3473,23 @@ impl ReaderPool {}sql_params.push(Value::Blob(workspace_id.as_bytes().to_vec()));sql_params.push(Value::Blob(project_id.as_bytes().to_vec()));- sql_params.push(Value::Integer(cutoff));- sql_params.push(Value::Blob(workspace_id.as_bytes().to_vec()));- sql_params.push(Value::Blob(project_id.as_bytes().to_vec()));- sql_params.push(Value::Integer(cutoff));+ match as_of_us {+ Some(t) => {+ // freq window + outer window: two params each.+ sql_params.push(Value::Integer(t));+ sql_params.push(Value::Integer(t));+ sql_params.push(Value::Blob(workspace_id.as_bytes().to_vec()));+ sql_params.push(Value::Blob(project_id.as_bytes().to_vec()));+ sql_params.push(Value::Integer(t));+ sql_params.push(Value::Integer(t));+ }+ None => {+ sql_params.push(Value::Integer(cutoff));+ sql_params.push(Value::Blob(workspace_id.as_bytes().to_vec()));+ sql_params.push(Value::Blob(project_id.as_bytes().to_vec()));+ sql_params.push(Value::Integer(cutoff));+ }+ }sql_params.push(Value::Integer(i64::try_from(limit).unwrap_or(i64::MAX)));let mut sql = String::with_capacity(placeholders.len() + 1_200);@@ -3468,8 +3507,8 @@ impl ReaderPool {SELECT m.entity_id, m.name, COUNT(*) AS pages \FROM matched m \JOIN entity_page_links l ON l.entity_id = m.entity_id \- JOIN pages p ON p.id = l.page_id AND p.is_latest = 1 \- WHERE 1 = 1{freq_not_expired} \+ JOIN pages p ON p.id = l.page_id \+ WHERE 1 = 1{freq_version_filter} \GROUP BY m.entity_id, m.name \) \SELECT pg.id, pg.path, pg.title, {descriptor} AS snippet, \@@ -3479,13 +3518,26 @@ impl ReaderPool {FROM freq f \JOIN entity_page_links l ON l.entity_id = f.entity_id \JOIN pages pg ON pg.id = l.page_id \- WHERE pg.workspace_id = ? AND pg.project_id = ? AND pg.is_latest = 1{not_expired} \+ WHERE pg.workspace_id = ? AND pg.project_id = ?{version_filter} \GROUP BY pg.id, pg.path, pg.title \ORDER BY weight DESC, matches DESC, pg.path ASC \LIMIT ?",descriptor = page_descriptor_expr("pg.body", "pg.frontmatter_json"),- not_expired = not_expired("pg", "?"),- freq_not_expired = not_expired("p", "?"),+ version_filter = if as_of_us.is_some() {+ // Window containment (docs/temporal.md); no expiry.+ " AND l.valid_from <= ? \+ AND (l.superseded_at IS NULL OR l.superseded_at > ?)"+ .to_string()+ } else {+ format!(" AND pg.is_latest = 1{}", not_expired("pg", "?"))+ },+ freq_version_filter = if as_of_us.is_some() {+ " AND l.valid_from <= ? \+ AND (l.superseded_at IS NULL OR l.superseded_at > ?)"+ .to_string()+ } else {+ format!(" AND p.is_latest = 1{}", not_expired("p", "?"))+ },).expect("writing SQL into String cannot fail");diff --git a/docs/temporal.md b/docs/temporal.mdnew file mode 100644index 00000000..540276f4--- /dev/null+++ b/docs/temporal.md@@ -0,0 +1,51 @@+# Temporal validity (bi-temporal-lite)++*2.0 item 4.* The entity index carries an **ingestion-time** validity+window, so "what did we know about X as of June" is answerable from+the store — the one mainstream graph-camp mechanism (Zep/Graphiti)+worth having at our scale.++## Honest scope++- **Ingestion time only.** `valid_from` / `superseded_at` record when+ ai-memory *learned* and *replaced* a fact, not when it was true in+ the world. A world-time split (Graphiti's `valid_at`/`invalid_at`+ extracted by an LLM) is deliberately out of scope: it requires+ trusting an LLM to date facts, and our zero-LLM default path could+ never populate it.+- **Entity links only.** Page versions already form a timeline+ (`supersedes` + `created_at`); entity links now inherit it. Typed+ relation edges (item 3) die with their page version, which is+ already a timeline — no extra columns needed there yet.+- **Deletion is deletion.** Purged pages cascade their entity links+ away; the timeline does not survive an explicit purge (that is what+ purge means here — see the purge docs).++## Schema++`entity_page_links` gains two additive columns:++| column | meaning |+|---|---|+| `valid_from` | `created_at` of the page version the link belongs to |+| `superseded_at` | `created_at` of the version that superseded it; `NULL` while the version is latest |++Backfill is a one-shot data migration inside refinery: `valid_from`+from the linked version's `created_at`; `superseded_at` from the+superseding version's `created_at` (found via `pages.supersedes`),+`NULL` for latest versions. New writes populate `valid_from` at+insert, and the supersede path closes the outgoing version's windows+in the same transaction — a link's window can never be open-ended in+a superseded version.++## Query++`memory_query` accepts `as_of` (ISO-8601). When present the query is+a **time-travel entity lookup**: the entity stream runs alone against+links whose window contains the instant+(`valid_from <= T AND (superseded_at IS NULL OR superseded_at > T)`),+returning the page versions that carried the matched entities at that+time. FTS / vector / graph streams are deliberately skipped — mixing+"current text relevance" with "historical entity validity" in one+ranked list would answer neither question honestly. Omit `as_of` and+nothing changes.