Skip to content

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

Rust

fix(scope): keep the startup seed out of the write path (#678)

rafaelkenedyd38452efb4c1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1ae5eaa7..0fcdcff7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,11 +24,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
unscoped read then resolved through the baked default scope and answered
zero counts through the success path, with nothing in the log to
distinguish "scope unresolved" from "project genuinely empty". `serve` now
- seeds the shared fallback slot at startup from the most recently active
- project recorded in the database, bounded by the same TTL as a per-key
- entry, so a keyed miss right after a restart degrades to real data. Keyed
- per-actor entries are never reconstructed and the first hook event
- publishes over the seed, so pre-publish and eviction reads keep degrading
+ seeds a read-side fallback at startup from the most recently active project
+ recorded in the database, bounded by the same TTL as a per-key entry, so a
+ keyed miss right after a restart degrades to real data. The seed serves
+ reads only: keyed per-actor entries are never reconstructed, an unscoped
+ write resolves exactly where it did before, and the first hook event
+ supersedes the seed — so pre-publish and eviction reads keep degrading
exactly as they do today (#678).
- The from-source AUR `PKGBUILD` now builds and tests on constrained AUR
builders. Release LTO was disabled (`options=('!debug' '!lto')`) so the
diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rs
index 1da598f6..e0e88fd5 100644
--- a/crates/ai-memory-cli/src/commands/serve.rs
+++ b/crates/ai-memory-cli/src/commands/serve.rs
@@ -2139,7 +2139,7 @@ fn host_allowed(host: &str, allowed_hosts: &[String]) -> bool {
})
}
-/// Seed the single-slot active-project fallback from the most recently active
+/// Seed the read-side active-project fallback from the most recently active
/// project already on disk.
///
/// The pointer lives only in process memory, so restarting the daemon
@@ -2152,11 +2152,13 @@ fn host_allowed(host: &str, allowed_hosts: &[String]) -> bool {
/// fire-and-forget) and of TTL/cap eviction, both of which must keep
/// degrading gracefully.
///
-/// So make the degraded answer a real one. Only the shared slot is seeded, so
-/// a keyed hit still wins and the first hook event publishes straight over it.
-/// The recency bound is the pointer's own per-key TTL: activity older than
-/// that would have aged out of a live pointer anyway. Non-fatal — a server
-/// that cannot read this starts exactly as it does today.
+/// So make the degraded answer a real one. The seed lands in a slot only READS
+/// consult: a keyed hit still wins, an unscoped write from an unrecognized
+/// caller still fails closed rather than being attributed to a reconstructed
+/// project, and the first hook event publishes straight over it. The recency
+/// bound is the pointer's own per-key TTL: activity older than that would have
+/// aged out of a live pointer anyway. Non-fatal — a server that cannot read
+/// this starts exactly as it does today.
async fn seed_active_project_fallback(reader: &ReaderPool, active_project: &ActiveProject) {
if active_project.get().is_some() {
return;
@@ -2167,7 +2169,7 @@ async fn seed_active_project_fallback(reader: &ReaderPool, active_project: &Acti
.saturating_sub(ttl_us);
match reader.most_recently_active_scope(since).await {
Ok(Some((workspace_id, project_id))) => {
- active_project.set(workspace_id, project_id);
+ active_project.seed_read_fallback(workspace_id, project_id);
let workspace = reader
.workspace_name_by_id(workspace_id)
.await
@@ -3047,9 +3049,14 @@ mod tests {
let active_project = ActiveProject::new();
seed_active_project_fallback(&store.reader, &active_project).await;
assert_eq!(
- active_project.get(),
+ active_project.seeded(),
Some((workspace_id, worked_in)),
- "the shared slot must name the project the last activity landed in"
+ "the seed must name the project the last activity landed in"
+ );
+ assert_eq!(
+ active_project.get(),
+ None,
+ "a reconstruction is not a publish: the shared slot stays empty"
);
// The live session's keyed entry died with the process, so its read
@@ -3068,6 +3075,22 @@ mod tests {
(workspace_id, worked_in),
"an unscoped read after a restart must not silently answer for the baked default"
);
+
+ // ...while an unscoped WRITE from a caller the pointer cannot place is
+ // untouched by the seed: it resolves exactly where it did before, so a
+ // page is never attributed to a project reconstructed from a session
+ // that is not this caller's.
+ let written = ai_memory_store::ScopeResolver::new(&store.reader, workspace_id, scratch)
+ .with_writer(&store.writer)
+ .with_active_project(&active_project)
+ .resolve_write_args(None, None, &actor)
+ .await
+ .unwrap();
+ assert_eq!(
+ written.as_tuple(),
+ (workspace_id, scratch),
+ "the seed must not retarget unscoped writes"
+ );
}
#[tokio::test]
@@ -3084,6 +3107,44 @@ mod tests {
.get_or_create_project(workspace_id, "published", None)
.await
.unwrap();
+ // Activity in a DIFFERENT project, or the seed no-ops and this test
+ // passes with the guard deleted.
+ let elsewhere = store
+ .writer
+ .get_or_create_project(workspace_id, "elsewhere", None)
+ .await
+ .unwrap();
+ let session_id = SessionId::new();
+ store
+ .writer
+ .begin_session(NewSession {
+ id: session_id,
+ workspace_id,
+ project_id: elsewhere,
+ agent_kind: AgentKind::ClaudeCode,
+ cwd: None,
+ actor_user: None,
+ })
+ .await
+ .unwrap();
+ store
+ .writer
+ .insert_observation(Sanitized::new(
+ NewObservation {
+ session_id,
+ workspace_id,
+ project_id: elsewhere,
+ kind: ObservationKind::UserPrompt,
+ extension: None,
+ source_event: None,
+ title: "work".into(),
+ body: "activity the seed would otherwise reach for".into(),
+ importance: 5,
+ },
+ &Sanitizer::default(),
+ ))
+ .await
+ .unwrap();
let active_project = ActiveProject::new();
active_project.set(workspace_id, published);
@@ -3094,6 +3155,11 @@ mod tests {
Some((workspace_id, published)),
"a live pointer outranks anything the DB remembers"
);
+ assert_eq!(
+ active_project.seeded(),
+ None,
+ "no seed is taken while a real publish already stands"
+ );
}
#[tokio::test]
diff --git a/crates/ai-memory-core/src/active_project.rs b/crates/ai-memory-core/src/active_project.rs
index 10589f1c..d765564d 100644
--- a/crates/ai-memory-core/src/active_project.rs
+++ b/crates/ai-memory-core/src/active_project.rs
@@ -365,6 +365,23 @@ pub struct ActiveProject {
/// Never reset: an install that once had hook activity is not hookless
/// again just because entries aged out of the TTL map.
ever_keyed: Arc<AtomicBool>,
+ /// A startup reconstruction of the shared slot, consulted by READS only.
+ ///
+ /// The pointer is process memory, so a restart mid-session empties it and
+ /// unscoped reads answered for the baked default scope — zero counts for a
+ /// project full of observations, through the success path (#678). `serve`
+ /// fills this slot at startup from the most recently active project on
+ /// disk so those reads degrade to real data instead.
+ ///
+ /// It is deliberately NOT the single slot. A seeded value is a
+ /// reconstruction, not an observed publish: writing it to `single` would
+ /// make [`Self::lookup_for`] answer `Resolved` for every caller until the
+ /// first hook event lands, including one whose coordinate matches nothing
+ /// — and an unscoped write would then be attributed to a project the
+ /// caller never named, possibly another operator's. That is exactly the
+ /// misfiling the `Mismatch`/`Unset` split exists to prevent, so the write
+ /// path never sees this slot.
+ seeded: Arc<RwLock<Option<(WorkspaceId, ProjectId)>>>,
}
impl Default for ActiveProject {
@@ -405,6 +422,7 @@ impl ActiveProject {
single_default_global: Arc::new(RwLock::new(false)),
per_actor: Arc::new(RwLock::new(PerActorMap::new(ttl, max_entries))),
ever_keyed: Arc::new(AtomicBool::new(false)),
+ seeded: Arc::new(RwLock::new(None)),
}
}
@@ -532,6 +550,30 @@ impl ActiveProject {
}
}
+ /// Read-path resolution: [`Self::get_for`], plus the startup seed for a
+ /// caller the pointer holds no information about.
+ ///
+ /// Only [`ActiveProjectLookup::Unset`] consults the seed — the state a
+ /// fresh process is in before the first hook event lands, which is
+ /// precisely the restart window that made `memory_status` answer an empty
+ /// default (#678). A [`ActiveProjectLookup::Mismatch`] still resolves to
+ /// nothing: hooks are live there and this coordinate matched none of them,
+ /// so the caller's own default is the honest answer.
+ ///
+ /// Reads only. The write path stays on [`Self::lookup_for`] so an unscoped
+ /// write from an unrecognized caller keeps failing closed instead of being
+ /// attributed to a project reconstructed from someone else's history.
+ #[must_use]
+ pub fn get_for_read(&self, actor: &ActorKey) -> Option<(WorkspaceId, ProjectId)> {
+ match self.lookup_for(actor) {
+ ActiveProjectLookup::Resolved(workspace_id, project_id) => {
+ Some((workspace_id, project_id))
+ }
+ ActiveProjectLookup::Unset => self.read_seeded(),
+ ActiveProjectLookup::Mismatch => None,
+ }
+ }
+
/// Same resolution as [`Self::get_for`], but says *why* it failed.
///
/// `get_for` collapses two very different outcomes into `None`, which is fine
@@ -630,6 +672,11 @@ impl ActiveProject {
*guard
}
+ fn read_seeded(&self) -> Option<(WorkspaceId, ProjectId)> {
+ let guard = self.seeded.read().unwrap_or_else(|e| e.into_inner());
+ *guard
+ }
+
fn write_single_default_global(&self, value: bool) {
let mut guard = self
.single_default_global
@@ -659,6 +706,24 @@ impl ActiveProject {
self.read_single()
}
+ /// Publish the read-side startup seed (#678). Called once by `serve`,
+ /// from the project the database says was active most recently.
+ ///
+ /// Touches neither the single slot nor the per-key map, so it cannot make
+ /// an unscoped write resolve anywhere new; see the `seeded` field for why
+ /// that separation is load-bearing. A real publish supersedes it for every
+ /// caller the moment the first hook event arrives.
+ pub fn seed_read_fallback(&self, workspace_id: WorkspaceId, project_id: ProjectId) {
+ let mut guard = self.seeded.write().unwrap_or_else(|e| e.into_inner());
+ *guard = Some((workspace_id, project_id));
+ }
+
+ /// The startup seed, if one was published.
+ #[must_use]
+ pub fn seeded(&self) -> Option<(WorkspaceId, ProjectId)> {
+ self.read_seeded()
+ }
+
/// Forget the active project. Called after an admin operation invalidates
/// the published pointer (e.g. a `move-project` whose copy-purge path
/// gives the project a NEW id, so the old pointer no longer resolves).
@@ -669,6 +734,10 @@ impl ActiveProject {
let mut guard = self.single.write().unwrap_or_else(|e| e.into_inner());
*guard = None;
}
+ {
+ let mut guard = self.seeded.write().unwrap_or_else(|e| e.into_inner());
+ *guard = None;
+ }
let mut guard = self.per_actor.write().unwrap_or_else(|e| e.into_inner());
guard.entries.clear();
}
@@ -677,8 +746,8 @@ impl ActiveProject {
/// the project id. Used after a lossless cross-workspace move where the
/// project row survives and only its workspace changes.
pub fn retarget_project_workspace(&self, project_id: ProjectId, workspace_id: WorkspaceId) {
- {
- let mut guard = self.single.write().unwrap_or_else(|e| e.into_inner());
+ for slot in [&self.single, &self.seeded] {
+ let mut guard = slot.write().unwrap_or_else(|e| e.into_inner());
if let Some((ws, proj)) = guard.as_mut()
&& *proj == project_id
{
@@ -691,8 +760,8 @@ impl ActiveProject {
/// Clear every active entry whose project id matches `project_id`.
pub fn clear_project(&self, project_id: ProjectId) {
- {
- let mut guard = self.single.write().unwrap_or_else(|e| e.into_inner());
+ for slot in [&self.single, &self.seeded] {
+ let mut guard = slot.write().unwrap_or_else(|e| e.into_inner());
if guard.map(|(_, proj)| proj) == Some(project_id) {
*guard = None;
}
@@ -703,8 +772,8 @@ impl ActiveProject {
/// Clear every active entry whose workspace id matches `workspace_id`.
pub fn clear_workspace(&self, workspace_id: WorkspaceId) {
- {
- let mut guard = self.single.write().unwrap_or_else(|e| e.into_inner());
+ for slot in [&self.single, &self.seeded] {
+ let mut guard = slot.write().unwrap_or_else(|e| e.into_inner());
if guard.map(|(ws, _)| ws) == Some(workspace_id) {
*guard = None;
}
@@ -716,7 +785,9 @@ impl ActiveProject {
/// Whether any live active entry references `project_id`.
#[must_use]
pub fn contains_project(&self, project_id: ProjectId) -> bool {
- if self.read_single().map(|(_, proj)| proj) == Some(project_id) {
+ if self.read_single().map(|(_, proj)| proj) == Some(project_id)
+ || self.read_seeded().map(|(_, proj)| proj) == Some(project_id)
+ {
return true;
}
let mut guard = self.per_actor.write().unwrap_or_else(|e| e.into_inner());
@@ -726,7 +797,9 @@ impl ActiveProject {
/// Whether any live active entry references `workspace_id`.
#[must_use]
pub fn contains_workspace(&self, workspace_id: WorkspaceId) -> bool {
- if self.read_single().map(|(ws, _)| ws) == Some(workspace_id) {
+ if self.read_single().map(|(ws, _)| ws) == Some(workspace_id)
+ || self.read_seeded().map(|(ws, _)| ws) == Some(workspace_id)
+ {
return true;
}
let mut guard = self.per_actor.write().unwrap_or_else(|e| e.into_inner());
@@ -799,6 +872,95 @@ mod tests {
(WorkspaceId::new(), ProjectId::new())
}
+ /// #678: the startup seed serves reads, and ONLY reads.
+ ///
+ /// Seeding the single slot instead would make this same lookup answer
+ /// `Resolved` for an actor that never published — `ever_keyed` is false for
+ /// the whole window between a restart and the first hook event — and
+ /// `resolve_write_args` consumes `Resolved` directly. A foreign caller's
+ /// unscoped write would then be attributed to whichever project the
+ /// database remembered, which is the misfiling #564 closed.
+ #[test]
+ fn a_seeded_fallback_serves_reads_without_placing_a_foreign_actor() {
+ let ap = per_actor();
+ let (ws, proj) = ids(1);
+ ap.seed_read_fallback(ws, proj);
+ let stranger = key_actor("bob", "s-bob-never-published");
+
+ assert_eq!(
+ ap.lookup_for(&stranger),
+ ActiveProjectLookup::Unset,
+ "the write path must still see no pointer for this caller"
+ );
+ assert_eq!(
+ ap.get_for(&stranger),
+ None,
+ "the seed is not a publish, so `get_for` must not report one"
+ );
+ assert_eq!(
+ ap.get_for_read(&stranger),
+ Some((ws, proj)),
+ "the read path degrades to the seed instead of an empty default"
+ );
+ assert_eq!(
+ ap.get(),
+ None,
+ "the shared publish slot stays empty until a hook fills it"
+ );
+ }
+
+ /// A keyed hit outranks the seed, and a real publish supersedes it for
+ /// every caller — the seed is only ever the answer of last resort.
+ #[test]
+ fn a_published_pointer_outranks_the_seed() {
+ let ap = per_actor();
+ let (ws, seeded_proj) = ids(1);
+ let (_, own_proj) = ids(2);
+ ap.seed_read_fallback(ws, seeded_proj);
+
+ let alice = key_actor("alice", "s-alice");
+ ap.set_for(&alice, ws, own_proj, false);
+ assert_eq!(ap.get_for_read(&alice), Some((ws, own_proj)));
+
+ // And once anything is keyed, a stranger is a mismatch again: hooks are
+ // live, so the honest answer is the caller's own default, not the seed.
+ let stranger = key_actor("bob", "s-bob");
+ assert_eq!(ap.lookup_for(&stranger), ActiveProjectLookup::Mismatch);
+ assert_eq!(ap.get_for_read(&stranger), None);
+ }
+
+ /// An admin op that invalidates the pointer must reach the seed too, or a
+ /// purged project keeps answering reads from a slot nothing can clear.
+ #[test]
+ fn invalidations_reach_the_seed() {
+ let (ws, proj) = ids(1);
+ let (other_ws, _) = ids(2);
+ let stranger = key_actor("bob", "s-bob");
+
+ let ap = per_actor();
+ ap.seed_read_fallback(ws, proj);
+ assert!(ap.contains_project(proj));
+ assert!(ap.contains_workspace(ws));
+ ap.clear_project(proj);
+ assert_eq!(ap.get_for_read(&stranger), None);
+
+ let ap = per_actor();
+ ap.seed_read_fallback(ws, proj);
+ ap.clear_workspace(ws);
+ assert_eq!(ap.get_for_read(&stranger), None);
+
+ let ap = per_actor();
+ ap.seed_read_fallback(ws, proj);
+ ap.clear();
+ assert_eq!(ap.get_for_read(&stranger), None);
+
+ // A lossless cross-workspace move keeps the project and moves it.
+ let ap = per_actor();
+ ap.seed_read_fallback(ws, proj);
+ ap.retarget_project_workspace(proj, other_ws);
+ assert_eq!(ap.get_for_read(&stranger), Some((other_ws, proj)));
+ }
+
/// The scenario the default must not break: one operator, one harness, and
/// an MCP-only install with no lifecycle hooks feeding the pointer.
///
diff --git a/crates/ai-memory-store/src/scope.rs b/crates/ai-memory-store/src/scope.rs
index db096672..8b36f6cb 100644
--- a/crates/ai-memory-store/src/scope.rs
+++ b/crates/ai-memory-store/src/scope.rs
@@ -388,7 +388,13 @@ impl<'a> ScopeResolver<'a> {
explicit_project: Option<&str>,
actor: &ActorKey,
) -> Result<ResolvedScope, ScopeResolutionError> {
- let active = self.active_project.and_then(|a| a.get_for(actor));
+ // Read path, so `get_for_read`: it adds the startup seed for a caller
+ // the pointer knows nothing about, which is every caller in the window
+ // between a restart and the first hook event (#678). `resolve_write_args`
+ // below deliberately stays on `get_for` / `lookup_for` — a write must
+ // not be attributed to a project reconstructed from history the caller
+ // never named.
+ let active = self.active_project.and_then(|a| a.get_for_read(actor));
if let Some(project) = trimmed_opt(explicit_project) {
if let Some((active_ws, _)) = active
&& let Some(project_id) = self
@@ -1142,4 +1148,63 @@ mod tests {
.unwrap();
assert_eq!(scope.as_tuple(), (default_ws, default_proj));
}
+
+ #[tokio::test]
+ async fn the_startup_seed_answers_reads_and_never_retargets_a_write() {
+ // #678: after a restart the pointer is empty, so an unscoped read
+ // resolved through the baked default and reported an empty project.
+ // The seed fixes the read. It must not follow into the write path:
+ // `resolve_write_args` still resolves as if nothing were published, so
+ // no page is attributed to a project rebuilt from someone else's
+ // history.
+ let tmp = tempfile::TempDir::new().unwrap();
+ let (store, default_ws, default_proj, team_ws, team_proj) = scoped_fixture(&tmp).await;
+
+ let active_project = ActiveProject::new();
+ active_project.seed_read_fallback(team_ws, team_proj);
+
+ for actor in [
+ // The session that outlived the daemon: coordinate intact, keyed
+ // entry gone with the process.
+ ActorKey {
+ user: Some("alice".into()),
+ session_id: Some("s1".into()),
+ },
+ // And a caller with no coordinate at all.
+ ActorKey::default(),
+ ] {
+ let read = ScopeResolver::new(&store.reader, default_ws, default_proj)
+ .with_active_project(&active_project)
+ .resolve_read_args(None, None, &actor)
+ .await
+ .unwrap();
+ assert_eq!(
+ read.as_tuple(),
+ (team_ws, team_proj),
+ "read must degrade to the seeded scope, not the empty default"
+ );
+
+ let write = ScopeResolver::new(&store.reader, default_ws, default_proj)
+ .with_writer(&store.writer)
+ .with_active_project(&active_project)
+ .resolve_write_args(None, None, &actor)
+ .await
+ .unwrap();
+ assert_eq!(
+ write.as_tuple(),
+ (default_ws, default_proj),
+ "write target must be exactly what it was before the seed existed"
+ );
+ }
+
+ // A named project still resolves inside the workspace the seed points
+ // at — that is a find-only read, and cross-workspace isolation holds:
+ // `real-work` exists only in `team`.
+ let named = ScopeResolver::new(&store.reader, default_ws, default_proj)
+ .with_active_project(&active_project)
+ .resolve_read_args(None, Some("real-work"), &ActorKey::default())
+ .await
+ .unwrap();
+ assert_eq!(named.as_tuple(), (team_ws, team_proj));
+ }
}
diff --git a/docs/auto-scope.md b/docs/auto-scope.md
index dfbb9c26..0bf71852 100644
--- a/docs/auto-scope.md
+++ b/docs/auto-scope.md
@@ -202,19 +202,25 @@ default scope and report an empty project through the success path. Nothing in
the answer or the log said "scope unresolved", so an agent asking "what do we
have here?" was told "nothing" while thousands of observations sat in the DB.
-`serve` therefore seeds the **shared slot** at startup from the most recently
-active project already recorded in SQLite, so a keyed miss right after a
-restart degrades to real data instead of an empty default. Three bounds keep
+`serve` therefore seeds a **read-side fallback slot** at startup from the most
+recently active project already recorded in SQLite, so a keyed miss right after
+a restart degrades to real data instead of an empty default. Four bounds keep
that narrow:
-- Only the shared fallback slot is seeded. Keyed entries are never
- reconstructed, so a keyed hit still wins and per-actor isolation is
- unchanged.
-- The seed is bounded by the same TTL as a per-key entry (`session_ttl_secs`,
- default one hour). Activity older than that would have aged out of a live
- pointer, so a server that was down overnight starts with no fallback at all.
-- The first foreground hook event publishes straight over it, exactly as it
- overwrites any other shared-slot value.
+- **Reads only.** The seed is a reconstruction, not an observed publish, so it
+ lives in its own slot. An unscoped **write** still resolves as if nothing
+ were published — it fails closed on a genuine mismatch and otherwise uses the
+ configured default, exactly as before. Nothing in a restart should retarget
+ where a page lands.
+- **Keyed entries are never reconstructed**, so a keyed hit still wins and
+ per-actor isolation is unchanged.
+- **Bounded by the same TTL as a per-key entry** (`session_ttl_secs`, default
+ one hour). Activity older than that would have aged out of a live pointer, so
+ a server that was down overnight starts with no fallback at all.
+- **The first foreground hook event supersedes it** for every caller, exactly
+ as it overwrites any other shared-slot value. Admin invalidations
+ (`purge-project`, `move-project`, workspace removal) reach the seed too, so a
+ scope that no longer exists cannot keep answering from it.
Reads deliberately do **not** fail closed on an unresolved pointer. A keyed
miss is also the normal shape of the pre-publish window (hooks are