Skip to content

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

Rust

feat(identity): route captures by the identity the client resolved (#708)

luisfnicolau2185d7411621
diff --git a/crates/ai-memory-consolidate/src/bootstrap.rs b/crates/ai-memory-consolidate/src/bootstrap.rs
index 4ea11c0d..ebbb4f70 100644
--- a/crates/ai-memory-consolidate/src/bootstrap.rs
+++ b/crates/ai-memory-consolidate/src/bootstrap.rs
@@ -734,6 +734,27 @@ pub fn discover_repo_root(start: &Path) -> Result<PathBuf, BootstrapError> {
.ok_or_else(|| BootstrapError::NotARepo(start.to_path_buf()))
}
+/// URLs of the `upstream` and `origin` remotes of the repository containing
+/// `start`, for resolving its repository identity (#708).
+///
+/// Only those two names are read. Remote names are personal, so picking some
+/// other one would give the same repository a different identity per person;
+/// see `ai_memory_core::repository_identity`. A linked worktree reads the
+/// main repository's remotes, which it shares. `(None, None)` when `start` is
+/// not inside a repository.
+#[must_use]
+pub fn read_identity_remotes(start: &Path) -> (Option<String>, Option<String>) {
+ let Ok(repo) = git2::Repository::discover(start) else {
+ return (None, None);
+ };
+ let url = |name: &str| {
+ repo.find_remote(name)
+ .ok()
+ .and_then(|remote| remote.url().ok().map(str::to_owned))
+ };
+ (url("upstream"), url("origin"))
+}
+
/// Like [`discover_repo_root`], but when `start` is inside a git
/// worktree the function follows the `.git` commondir pointer back to
/// the **main** repository root rather than returning the worktree's
diff --git a/crates/ai-memory-consolidate/src/lib.rs b/crates/ai-memory-consolidate/src/lib.rs
index 783d1ad7..1156c977 100644
--- a/crates/ai-memory-consolidate/src/lib.rs
+++ b/crates/ai-memory-consolidate/src/lib.rs
@@ -56,7 +56,7 @@ pub use bootstrap::{
Bootstrap, BootstrapConfig, BootstrapError, BootstrapOutcome, BootstrapSource,
DEFAULT_CHUNK_INPUT_TOKENS, ProjectNameStrategy, SourceCounts, SourceKind, collect_sources,
derive_project_name, discover_main_repo_root, discover_repo_root, effective_chunk_budget,
- plan_bootstrap_chunks, prune_sources_to_budget,
+ plan_bootstrap_chunks, prune_sources_to_budget, read_identity_remotes,
};
pub use cold_cluster::{adaptive_eps, cosine_distance, dbscan};
pub use compaction::build_compacted_markdown;
diff --git a/crates/ai-memory-hooks/src/payload.rs b/crates/ai-memory-hooks/src/payload.rs
index 275acc04..f18f1495 100644
--- a/crates/ai-memory-hooks/src/payload.rs
+++ b/crates/ai-memory-hooks/src/payload.rs
@@ -89,6 +89,14 @@ pub struct HookQuery {
/// `.ai-memory.toml` named it, `repo-root` when the host hook derived it
/// from the enclosing checkout. Absent on older clients (#394).
pub project_src: Option<String>,
+ /// Repository identity the client resolved for this checkout (#708):
+ /// an explicit marker `identity`, or a normalised git remote. Paired
+ /// with `identity_src`. Absent on older clients and for checkouts that
+ /// declare a `project`, which keep routing by name.
+ pub identity: Option<String>,
+ /// Which rung produced `identity`: `explicit` or `git_remote`. Anything
+ /// else, or a malformed identity, is ignored and the event routes by name.
+ pub identity_src: Option<String>,
}
/// Coalesced view of an incoming hook event after light parsing of the
@@ -117,6 +125,10 @@ pub struct HookEnvelope {
/// Where `project_override` came from. Always [`ProjectSource::Unspecified`]
/// when there is no override, so the two can never disagree (#394).
pub project_source: ProjectSource,
+ /// Repository identity from the client, already validated by
+ /// [`ai_memory_core::repository_identity::accept_wire_identity`]. `None`
+ /// routes by project name, as every event did before identities existed.
+ pub identity: Option<ai_memory_core::repository_identity::RepositoryIdentity>,
/// Whether this project opted into `drop_subagent_captures` via its
/// `.ai-memory.toml` (forwarded as the `drop_subagent` query flag). The
/// ingest router consults this per-event so the drop is scoped to the
@@ -164,6 +176,7 @@ impl std::fmt::Debug for HookEnvelope {
.field("workspace_override", &self.workspace_override)
.field("project_override", &self.project_override)
.field("project_strategy", &self.project_strategy)
+ .field("identity", &self.identity)
.field("drop_subagent_requested", &self.drop_subagent_requested)
.field(
"recall_default_global_requested",
@@ -502,6 +515,12 @@ impl HookEnvelope {
} else {
ProjectSource::Unspecified
};
+ let identity = match (query.identity.as_deref(), query.identity_src.as_deref()) {
+ (Some(identity), Some(source)) => {
+ ai_memory_core::repository_identity::accept_wire_identity(identity, source)
+ }
+ _ => None,
+ };
let drop_subagent_requested = query_flag_truthy(query.drop_subagent.as_deref());
let recall_default_global_requested = query_flag_truthy(query.default_global.as_deref());
let all_owners_requested = query_flag_truthy(query.all_owners.as_deref());
@@ -563,6 +582,7 @@ impl HookEnvelope {
project_override,
project_strategy,
project_source,
+ identity,
drop_subagent_requested,
recall_default_global_requested,
all_owners_requested,
diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rs
index 6df45395..18f4ead2 100644
--- a/crates/ai-memory-hooks/src/router.rs
+++ b/crates/ai-memory-hooks/src/router.rs
@@ -88,8 +88,8 @@ pub const DEFAULT_PROJECT_CACHE_MAX_ENTRIES: usize = 4096;
const SUBAGENT_SESSIONS_MAX: usize = 4096;
/// Resolved-project cache key:
-/// `(cwd, workspace_override, project_override, project_strategy)`.
-pub type ProjectCacheKey = (String, String, String, String);
+/// `(cwd, workspace_override, project_override, project_strategy, identity)`.
+pub type ProjectCacheKey = (String, String, String, String, String);
/// Shared bounded resolved-project cache.
pub type ProjectCache = Arc<tokio::sync::Mutex<ProjectCacheStore>>;
@@ -1191,6 +1191,7 @@ async fn should_drop_subagent(
env.workspace_override.as_deref(),
env.project_override.as_deref(),
env.project_strategy,
+ env.identity.as_ref(),
viewer,
)
.await
@@ -1267,6 +1268,24 @@ pub struct HandoffQuery {
pub managed_run: Option<String>,
/// Native session identifier observed in the SessionStart payload.
pub session_id: Option<String>,
+ /// Repository identity the client resolved (#708). Same contract as
+ /// [`crate::payload::HookQuery::identity`].
+ pub identity: Option<String>,
+ /// Rung that produced `identity`; see
+ /// [`crate::payload::HookQuery::identity_src`].
+ pub identity_src: Option<String>,
+}
+
+impl HandoffQuery {
+ /// The validated repository identity, or `None` to route by name.
+ fn repository_identity(
+ &self,
+ ) -> Option<ai_memory_core::repository_identity::RepositoryIdentity> {
+ ai_memory_core::repository_identity::accept_wire_identity(
+ self.identity.as_deref()?,
+ self.identity_src.as_deref()?,
+ )
+ }
}
/// Synchronous endpoint used by `session-start.sh` to discover any
@@ -1353,6 +1372,7 @@ async fn fetch_and_accept_handoff_at(
query.workspace.as_deref(),
query.project.as_deref(),
ProjectStrategy::parse(query.project_strategy.as_deref()),
+ query.repository_identity().as_ref(),
viewer,
)
.await?;
@@ -2091,12 +2111,19 @@ fn cache_key_for(
workspace_override: Option<&str>,
project_override: Option<&str>,
project_strategy: ProjectStrategy,
-) -> (String, String, String, String) {
+ identity: Option<&ai_memory_core::repository_identity::RepositoryIdentity>,
+) -> ProjectCacheKey {
(
cwd_norm.unwrap_or_default().to_string(),
workspace_override.unwrap_or_default().to_string(),
project_override.unwrap_or_default().to_string(),
project_strategy.as_str().to_string(),
+ // Two repositories can sit at the same path on two machines. Without
+ // the identity in the key, whichever resolved first would answer for
+ // both.
+ identity
+ .map(|i| format!("{}:{}", i.source.as_str(), i.identity))
+ .unwrap_or_default(),
)
}
@@ -2145,6 +2172,7 @@ async fn resolve_project_ids_inner(
workspace_override: Option<&str>,
project_override: Option<&str>,
project_strategy: ProjectStrategy,
+ identity: Option<&ai_memory_core::repository_identity::RepositoryIdentity>,
creator: Option<ai_memory_core::UserId>,
) -> anyhow::Result<(WorkspaceId, ProjectId)> {
let cwd_raw = cwd.filter(|s| !s.is_empty());
@@ -2156,11 +2184,15 @@ async fn resolve_project_ids_inner(
return Ok((state.workspace_id, state.project_id));
}
+ // Only the rungs that carry something a name does not route by identity:
+ // a declared `project` and a folder name keep routing by name.
+ let identity = identity.filter(|i| i.source.routes_by_identity());
let cache_key = cache_key_for(
cwd_norm.as_deref(),
workspace_override,
project_override,
project_strategy,
+ identity,
);
{
@@ -2343,17 +2375,44 @@ async fn resolve_project_ids_inner(
// The match is keyed on the actual cwd (`cwd_norm`), not the stored
// `repo_path`: `repo_path` is now the git root or None (issue #103),
// whereas cwd->parent matching needs the full deep path.
- let proj = if project_override.is_none()
- && let Some(rp) = cwd_norm.as_deref().filter(|s| !s.is_empty())
- && let Some((parent_id, parent_name)) = state
+ let parent = match cwd_norm.as_deref().filter(|s| !s.is_empty()) {
+ Some(rp) if project_override.is_none() => state
.reader
.find_project_by_cwd_prefix(ws, rp.to_string(), state.home_dir.as_deref())
.await
- .map_err(|e| anyhow::anyhow!("find_project_by_cwd_prefix: {e}"))?
+ .map_err(|e| anyhow::anyhow!("find_project_by_cwd_prefix: {e}"))?,
+ _ => None,
+ };
+ let proj = if let Some(identity) = identity {
+ // A repository identity decides the project before any name does: the
+ // project already carrying it wins, whatever it is called, and the
+ // name (or the cwd-prefix parent) is only the candidate for a project
+ // that has not been claimed yet. One writer transaction, so two
+ // captures racing on a new repository cannot both create it.
+ let (proj, resolution) = state
+ .writer
+ .resolve_project_by_identity(
+ ws,
+ identity.clone(),
+ project_name,
+ repo_path,
+ parent.map(|(parent_id, _)| parent_id),
+ creator,
+ )
+ .await
+ .map_err(|e| anyhow::anyhow!("resolve_project_by_identity: {e}"))?;
+ debug!(
+ identity = %identity.identity,
+ source = identity.source.as_str(),
+ ?resolution,
+ "hook router: resolved project by repository identity"
+ );
+ proj
+ } else if let Some((parent_id, parent_name)) = parent
&& parent_name != project_name
{
debug!(
- cwd = rp,
+ cwd = ?cwd_norm,
derived = %project_name,
parent = %parent_name,
"hook router: cwd inside existing project — using parent instead of \
@@ -2397,6 +2456,7 @@ async fn resolve_project_ids(
project_override,
project_strategy,
None,
+ None,
)
.await?;
if has_publishable_scope_hint(cwd, project_override) {
@@ -2763,6 +2823,7 @@ async fn process_authorized(
env.workspace_override.as_deref(),
env.project_override.as_deref(),
env.project_strategy,
+ env.identity.as_ref(),
viewer,
)
.await?
@@ -2849,6 +2910,7 @@ async fn process_authorized(
env.workspace_override.as_deref(),
env.project_override.as_deref(),
env.project_strategy,
+ env.identity.as_ref(),
);
let mut attempts = 0;
// Keep the successful keyed-ingest gate until every downstream effect has
@@ -2912,6 +2974,7 @@ async fn process_authorized(
env.workspace_override.as_deref(),
env.project_override.as_deref(),
env.project_strategy,
+ env.identity.as_ref(),
viewer,
)
.await?;
@@ -3846,6 +3909,8 @@ mod tests {
briefing_budget: None,
managed_run: None,
session_id: None,
+ identity: None,
+ identity_src: None,
}
}
@@ -4300,6 +4365,178 @@ mod tests {
);
}
+ /// Session start routes by the same identity a capture does, so its
+ /// handoff and briefing come from the project the captures land in. Same
+ /// validation: a rung that routes by name, or a malformed value, is `None`.
+ #[test]
+ fn handoff_query_accepts_identity_on_the_same_terms_as_a_capture() {
+ let query = |identity: &str, source: &str| HandoffQuery {
+ identity: Some(identity.to_owned()),
+ identity_src: Some(source.to_owned()),
+ ..Default::default()
+ };
+ let got = query("github.com/orga/api", "git_remote")
+ .repository_identity()
+ .unwrap();
+ assert_eq!(got.identity, "github.com/orga/api");
+ assert!(
+ query("github.com/orga/api", "manifest")
+ .repository_identity()
+ .is_none()
+ );
+ assert!(
+ query("GitHub.com/Orga/API", "git_remote")
+ .repository_identity()
+ .is_none()
+ );
+ assert!(HandoffQuery::default().repository_identity().is_none());
+ }
+
+ /// A capture that carries the repository identity its client resolved.
+ async fn capture_with_identity(
+ state: &HookState,
+ cwd: &std::path::Path,
+ session: &str,
+ identity: Option<(&str, &str)>,
+ ) -> ProjectId {
+ let env = HookEnvelope::from_query_and_body(
+ HookQuery {
+ event: "user-prompt-submit".into(),
+ agent: Some("claude-code".into()),
+ identity: identity.map(|(identity, _)| identity.to_owned()),
+ identity_src: identity.map(|(_, source)| source.to_owned()),
+ ..Default::default()
+ },
+ serde_json::json!({
+ "session_id": session,
+ "cwd": cwd.to_string_lossy(),
+ "prompt": "hello",
+ }),
+ );
+ process_authorized(
+ state,
+ env,
+ None,
+ ai_memory_core::AuthLevel::User,
+ Vec::new(),
+ None,
+ )
+ .await
+ .unwrap();
+ state
+ .reader
+ .observations_for_session(session.parse().unwrap())
+ .await
+ .unwrap()[0]
+ .project_id
+ }
+
+ /// #708's collision, end to end: two unrelated repositories both checked
+ /// out as `api/` used to land in one project. With the client's identity
+ /// they land in two, and the same repository under a different folder name
+ /// lands back in its own. The two `api/` checkouts share a folder name and
+ /// nothing else, so the path-keyed project cache must not answer for both.
+ #[tokio::test]
+ async fn two_api_checkouts_with_different_remotes_get_two_projects() {
+ let tmp = TempDir::new().unwrap();
+ let state = make_state(&tmp).await;
+ let org_a = tmp.path().join("org-a").join("api");
+ let org_b = tmp.path().join("org-b").join("api");
+ let clone = tmp.path().join("elsewhere").join("acme-api");
+ for dir in [&org_a, &org_b, &clone] {
+ std::fs::create_dir_all(dir).unwrap();
+ }
+ let a = capture_with_identity(
+ &state,
+ &org_a,
+ &SessionId::new().to_string(),
+ Some(("github.com/orga/api", "git_remote")),
+ )
+ .await;
+ let b = capture_with_identity(
+ &state,
+ &org_b,
+ &SessionId::new().to_string(),
+ Some(("github.com/orgb/api", "git_remote")),
+ )
+ .await;
+ assert_ne!(a, b, "unrelated repositories must not share a project");
+ assert_eq!(
+ state
+ .reader
+ .project_name_by_id(state.workspace_id, b)
+ .await
+ .unwrap(),
+ Some("orgb-api".to_owned())
+ );
+ let again = capture_with_identity(
+ &state,
+ &clone,
+ &SessionId::new().to_string(),
+ Some(("github.com/orga/api", "git_remote")),
+ )
+ .await;
+ assert_eq!(again, a, "one repository, one project, whatever the folder");
+
+ // A client that sends nothing, or a rung that routes by name, keeps
+ // today's routing: the folder name.
+ let plain = tmp.path().join("plain").join("api");
+ std::fs::create_dir_all(&plain).unwrap();
+ let by_name =
+ capture_with_identity(&state, &plain, &SessionId::new().to_string(), None).await;
+ assert_eq!(
+ by_name, a,
+ "no identity routes by the folder name, as before"
+ );
+ let declared = capture_with_identity(
+ &state,
+ &plain,
+ &SessionId::new().to_string(),
+ Some(("github.com/orgc/api", "manifest")),
+ )
+ .await;
+ assert_eq!(declared, a, "a manifest identity is ignored on the wire");
+ }
+
+ /// Two machines sharing one server can hold unrelated repositories at the
+ /// same path (`~/src/api` on each). The project cache is keyed by path, so
+ /// without the identity in its key whichever resolved first would answer
+ /// for both, and the second machine's captures would land in the first's
+ /// project.
+ #[tokio::test]
+ async fn one_path_with_two_remotes_is_two_projects() {
+ let tmp = TempDir::new().unwrap();
+ let state = make_state(&tmp).await;
+ let shared = tmp.path().join("src").join("api");
+ std::fs::create_dir_all(&shared).unwrap();
+
+ let first = capture_with_identity(
+ &state,
+ &shared,
+ &SessionId::new().to_string(),
+ Some(("github.com/orga/api", "git_remote")),
+ )
+ .await;
+ let second = capture_with_identity(
+ &state,
+ &shared,
+ &SessionId::new().to_string(),
+ Some(("github.com/orgb/api", "git_remote")),
+ )
+ .await;
+ assert_ne!(first, second, "the cache answered for the wrong repository");
+
+ // Control: the same repository at that path keeps resolving to its own.
+ let again = capture_with_identity(
+ &state,
+ &shared,
+ &SessionId::new().to_string(),
+ Some(("github.com/orga/api", "git_remote")),
+ )
+ .await;
+ assert_eq!(again, first);
+ }
+
/// A capture, with the viewer it is authenticated as.
async fn capture_as(
state: &HookState,
@@ -7781,10 +8018,11 @@ mod tests {
String::new(),
String::new(),
ProjectStrategy::Basename.as_str().to_string(),
+ String::new(),
);
assert!(
cache.contains_key(&key),
- "cache keyed by (cwd, ws_override, proj_override, project_strategy)"
+ "cache keyed by (cwd, ws_override, proj_override, project_strategy, identity)"
);
}
@@ -7811,9 +8049,27 @@ mod tests {
#[test]
fn project_cache_store_evicts_oldest_untouched_entry() {
let mut cache = ProjectCacheStore::new(2);
- let key_a = ("/a".into(), String::new(), String::new(), "basename".into());
- let key_b = ("/b".into(), String::new(), String::new(), "basename".into());
- let key_c = ("/c".into(), String::new(), String::new(), "basename".into());
+ let key_a = (
+ "/a".into(),
+ String::new(),
+ String::new(),
+ "basename".into(),
+ String::new(),
+ );
+ let key_b = (
+ "/b".into(),
+ String::new(),
+ String::new(),
+ "basename".into(),
+ String::new(),
+ );
+ let key_c = (
+ "/c".into(),
+ String::new(),
+ String::new(),
+ "basename".into(),
+ String::new(),
+ );
cache.insert(key_a.clone(), (WorkspaceId::new(), ProjectId::new()));
cache.insert(key_b.clone(), (WorkspaceId::new(), ProjectId::new()));
@@ -7834,8 +8090,20 @@ mod tests {
let mut cache = ProjectCacheStore::new(4);
let doomed_ws = WorkspaceId::new();
let kept_ws = WorkspaceId::new();
- let key_a = ("/a".into(), String::new(), String::new(), "basename".into());
- let key_b = ("/b".into(), String::new(), String::new(), "basename".into());
+ let key_a = (
+ "/a".into(),
+ String::new(),
+ String::new(),
+ "basename".into(),
+ String::new(),
+ );
+ let key_b = (
+ "/b".into(),
+ String::new(),
+ String::new(),
+ "basename".into(),
+ String::new(),
+ );
cache.insert(key_a.clone(), (doomed_ws, ProjectId::new()));
cache.insert(key_b.clone(), (kept_ws, ProjectId::new()));
@@ -8096,6 +8364,7 @@ mod tests {
Some("default"),
Some("scratch"),
ProjectStrategy::Basename,
+ None,
);
let mut cache = state.project_cache.lock().await;
assert_eq!(cache.get(&cache_key), Some((cached_ws, cached_proj)));
@@ -10028,6 +10297,8 @@ mod tests {
briefing_budget: None,
managed_run: None,
session_id: None,
+ identity: None,
+ identity_src: None,
}),
Some(axum::Extension(ai_memory_core::ActorContext {
issuer: Some("https://idp.example".into()),
@@ -10638,6 +10909,8 @@ mod tests {
briefing_budget: None,
managed_run: None,
session_id: None,
+ identity: None,
+ identity_src: None,
};
let state = Arc::new(state);
let session_start = |viewer: Option<ai_memory_core::UserId>| {
@@ -10719,6 +10992,8 @@ mod tests {
briefing_budget: None,
managed_run: None,
session_id: None,
+ identity: None,
+ identity_src: None,
};
let state = Arc::new(state);
@@ -10893,6 +11168,8 @@ mod tests {
briefing_budget: None,
managed_run: None,
session_id: None,
+ identity: None,
+ identity_src: None,
}),
None,
None,
@@ -11709,6 +11986,8 @@ mod tests {
briefing_budget: None,
managed_run: None,
session_id: None,
+ identity: None,
+ identity_src: None,
},
None,
Vec::new(),
@@ -11783,6 +12062,8 @@ mod tests {
briefing_budget: None,
managed_run: None,
session_id: None,
+ identity: None,
+ identity_src: None,
},
None,
Vec::new(),
@@ -11850,6 +12131,8 @@ mod tests {
briefing_budget: None,
managed_run: None,
session_id: Some(session_id.into()),
+ identity: None,
+ identity_src: None,
};
let empty_sid = "empty-native-session";
let rendered = fetch_and_accept_handoff(&state, query(empty_sid), None, Vec::new(), None)
@@ -11987,6 +12270,8 @@ mod tests {
briefing_budget: None,
managed_run: Some(run.run_id.to_string()),
session_id: Some("native-2".into()),
+ identity: None,
+ identity_src: None,
};
let rendered = fetch_and_accept_handoff(&state, query.clone(), None, Vec::new(), None)
.await
@@ -12092,6 +12377,8 @@ mod tests {
briefing_budget: None,
managed_run: None,
session_id: None,
+ identity: None,
+ identity_src: None,
};
let named = ai_memory_core::ActorContext {
@@ -12168,6 +12455,8 @@ mod tests {
briefing_budget: None,
managed_run: None,
session_id: None,
+ identity: None,
+ identity_src: None,
};
let rendered =
@@ -12228,6 +12517,8 @@ mod tests {
briefing_budget: None,
managed_run: None,
session_id: None,
+ identity: None,
+ identity_src: None,
};
// Non-truthy opt-in: no handoff pending, nothing to inject.
@@ -12374,6 +12665,8 @@ mod tests {
briefing_budget: None,
managed_run: Some(kimi.run_id.to_string()),
session_id: Some("kimi-session".into()),
+ identity: None,
+ identity_src: None,
};
let rendered =
@@ -12586,6 +12879,8 @@ mod tests {
briefing_budget: None,
managed_run: None,
session_id: None,
+ identity: None,
+ identity_src: None,
},
None,
Vec::new(),
@@ -12710,6 +13005,7 @@ mod tests {
String::new(),
String::new(),
strat.clone(),
+ String::new(),
)),
"cache key must remain case-folded for #806 stickiness"
);
@@ -12719,6 +13015,7 @@ mod tests {
String::new(),
String::new(),
strat,
+ String::new(),
)),
"cache key must not carry the original-case basename"
);