Skip to content

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.md
index 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 the
existing `links.link_type` column (no schema migration). Declared
diff --git a/README.md b/README.md
index 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.rs
index 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.sql
new file mode 100644
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.md
new file mode 100644
index 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.