Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(hooks): accept workspace/project query-string overrides
Pablo Winter2a73c5689f91
diff --git a/crates/ai-memory-hooks/src/payload.rs b/crates/ai-memory-hooks/src/payload.rsindex 7181ee71..f0252bee 100644--- a/crates/ai-memory-hooks/src/payload.rs+++ b/crates/ai-memory-hooks/src/payload.rs@@ -4,12 +4,24 @@ use ai_memory_core::{AgentKind, ObservationKind};use serde::{Deserialize, Serialize};/// Query-string parameters on `POST /hook`.-#[derive(Debug, Clone, Deserialize)]+#[derive(Debug, Clone, Default, Deserialize)]pub struct HookQuery {/// Lifecycle event identifier (kebab-case or snake_case).pub event: String,/// Agent CLI identifier (`claude-code`, `codex`, `open-code`, `omp`).pub agent: Option<String>,+ /// Working directory of the agent at the time the hook fired.+ /// Most agents put this in the JSON body, but accepting it on the+ /// query string too lets `curl` / tests / non-Claude bridges+ /// populate it without constructing a body envelope.+ pub cwd: Option<String>,+ /// Workspace name override (typically declared by the agent's+ /// host-side hook via a `.ai-memory.toml` walk-up). When `None`+ /// the server falls back to `DEFAULT_WORKSPACE_NAME`.+ pub workspace: Option<String>,+ /// Project name override (same source as `workspace`). When+ /// `None` the server falls back to `basename(cwd)`.+ pub project: Option<String>,}/// Coalesced view of an incoming hook event after light parsing of the@@ -26,6 +38,12 @@ pub struct HookEnvelope {pub session_id: Option<String>,/// Current working directory at the time of the event.pub cwd: Option<String>,+ /// Workspace name override declared by the hook (via marker file+ /// walk-up). Empty / `None` defers to `DEFAULT_WORKSPACE_NAME`.+ pub workspace_override: Option<String>,+ /// Project name override declared by the hook. Empty / `None`+ /// defers to `basename(cwd)`.+ pub project_override: Option<String>,/// Optional title hint extracted from the body.pub title_hint: Option<String>,/// Optional body excerpt extracted from the agent's raw payload.@@ -135,7 +153,7 @@ impl HookEnvelope {],)});- let cwd = extract_string(&raw, &["cwd", "current_dir", "working_dir", "directory"])+ let body_cwd = extract_string(&raw, &["cwd", "current_dir", "working_dir", "directory"]).or_else(|| {extract_string_path(&raw,@@ -150,6 +168,12 @@ impl HookEnvelope {],)});+ // Body cwd wins over the query-string fallback: the body is+ // what agent CLIs natively send, so any query-string `cwd` is+ // a bridge / test override that should defer to live data.+ let cwd = body_cwd.or_else(|| query.cwd.filter(|s| !s.is_empty()));+ let workspace_override = query.workspace.filter(|s| !s.is_empty());+ let project_override = query.project.filter(|s| !s.is_empty());let title_hint = best_title_hint(event, &raw);let body_excerpt = best_body_excerpt(event, &raw);Self {@@ -157,6 +181,8 @@ impl HookEnvelope {agent,session_id,cwd,+ workspace_override,+ project_override,title_hint,body_excerpt,raw,@@ -311,6 +337,7 @@ mod tests {let q = HookQuery {event: "session-start".into(),agent: Some("claude-code".into()),+ ..Default::default()};let raw = serde_json::json!({"session_id": "abc-123",@@ -333,6 +360,7 @@ mod tests {let q = HookQuery {event: "post-tool-use".into(),agent: Some("open-code".into()),+ ..Default::default()};let raw = serde_json::json!({"sessionID": "ses_abc123",@@ -352,6 +380,7 @@ mod tests {let q = HookQuery {event: "post-tool-use".into(),agent: Some("open-code".into()),+ ..Default::default()};let raw = serde_json::json!({"hook_event_name": "post-tool-use",@@ -384,6 +413,7 @@ mod tests {let q = HookQuery {event: "session-start".into(),agent: Some("open-code".into()),+ ..Default::default()};let raw = serde_json::json!({"event": {@@ -436,6 +466,7 @@ mod tests {let q = HookQuery {event: "stop".into(),agent: Some("claude-code".into()),+ ..Default::default()};let env = HookEnvelope::from_query_and_body(q, serde_json::json!({}));assert_eq!(env.event, HookEvent::Stop);@@ -452,6 +483,7 @@ mod tests {let q = HookQuery {event: "user-prompt".into(),agent: Some("claude-code".into()),+ ..Default::default()};let raw = serde_json::json!({ "garbage": 42 });let env = HookEnvelope::from_query_and_body(q, raw);@@ -469,6 +501,7 @@ mod tests {let q = HookQuery {event: "post-tool-use".into(),agent: Some("claude-code".into()),+ ..Default::default()};for raw in [serde_json::json!(null),@@ -493,6 +526,7 @@ mod tests {let q = HookQuery {event: "session-end".into(),agent: None,+ ..Default::default()};let env = HookEnvelope::from_query_and_body(q, serde_json::json!({}));assert_eq!(env.agent, AgentKind::Other);@@ -507,6 +541,7 @@ mod tests {let q = HookQuery {event: "user-prompt".into(),agent: Some("claude-code".into()),+ ..Default::default()};// Multi-line prompt → title is the first line only.let env = HookEnvelope::from_query_and_body(@@ -528,6 +563,7 @@ mod tests {let q = HookQuery {event: "post-tool-use".into(),agent: Some("claude-code".into()),+ ..Default::default()};let output = format!("{}é", "x".repeat(1_999));let env = HookEnvelope::from_query_and_body(diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rsindex f1df717f..309e3256 100644--- a/crates/ai-memory-hooks/src/router.rs+++ b/crates/ai-memory-hooks/src/router.rs@@ -33,6 +33,12 @@ use crate::log;use crate::payload::{HookEnvelope, HookEvent, HookQuery, parse_agent};use crate::synth::synthesize_session_page;+/// Resolved-project cache: `(cwd, workspace_override, project_override)`+/// keyed map, shared behind a Tokio mutex so the router can be cloned+/// freely without losing the in-flight cache hits.+pub type ProjectCache =+ Arc<tokio::sync::Mutex<HashMap<(String, String, String), (WorkspaceId, ProjectId)>>>;+/// Shared state passed to the hook handler.#[derive(Clone)]pub struct HookState {@@ -55,11 +61,12 @@ pub struct HookState {/// the store. Same handle is also held by the wiki and consolidator/// so scrubbing happens at every write boundary.pub sanitizer: Sanitizer,- /// Cache of `cwd → (workspace_id, project_id)` resolved on first- /// sight. Avoids a SQLite round-trip for every hook event from the- /// same agent session. Keyed by the raw cwd string; no- /// canonicalisation — two symlinked paths are separate buckets.- pub project_cache: Arc<tokio::sync::Mutex<HashMap<String, (WorkspaceId, ProjectId)>>>,+ /// Cache of `(cwd, workspace_override, project_override) → ids`.+ /// The composite key avoids poisoning between callers that resolve+ /// the same `cwd` with and without an override during a hook-script+ /// upgrade window. Each tuple element defaults to the empty string+ /// when absent so missing overrides collapse into a single slot.+ pub project_cache: ProjectCache,/// Pointer shared with the MCP server. Every cwd-resolved event/// publishes its project here so the read tools (which have no cwd/// of their own) default to the project the user is actually in@@ -87,7 +94,7 @@ async fn handle_hook(}/// Query params for `GET /handoff`.-#[derive(Debug, Clone, Deserialize)]+#[derive(Debug, Clone, Default, Deserialize)]pub struct HandoffQuery {/// Identifier of the agent fetching the handoff. Used to mark the/// handoff as accepted-by; defaults to `Other` if unrecognised.@@ -96,6 +103,14 @@ pub struct HandoffQuery {/// cwd matches this string are returned. Note: the cwd string is/// not canonicalized; symlinked paths must match byte-for-byte.pub cwd: Option<String>,+ /// Workspace override (mirror of `HookQuery.workspace`). Lets the+ /// `session-start` hook fetch the handoff for the same `(workspace,+ /// project)` pair the marker file declared, without depending on+ /// the MCP `active_project` cache (which only populates after the+ /// first hook event of the session).+ pub workspace: Option<String>,+ /// Project override (mirror of `HookQuery.project`).+ pub project: Option<String>,}/// Synchronous endpoint used by `session-start.sh` to discover any@@ -126,7 +141,13 @@ async fn fetch_and_accept_handoff(query: HandoffQuery,) -> anyhow::Result<Option<String>> {let agent = query.agent.as_deref().map_or(AgentKind::Other, parse_agent);- let (ws, proj) = resolve_project_ids(state, query.cwd.as_deref()).await?;+ let (ws, proj) = resolve_project_ids(+ state,+ query.cwd.as_deref(),+ query.workspace.as_deref(),+ query.project.as_deref(),+ )+ .await?;let handoff = state.reader.latest_open_handoff(ws, proj, query.cwd)@@ -202,20 +223,38 @@ fn render_handoff_markdown(h: &Handoff) -> String {/// Resolve the `(workspace_id, project_id)` pair for a hook event.///-/// When `cwd` is present, derives `project_name = basename(cwd)` and-/// upserts it under the `default` workspace (cached to avoid a SQLite-/// round-trip per event). Falls back to the server's default IDs when-/// `cwd` is `None` or empty.+/// Precedence:+/// 1. `workspace_override` (typically declared by the agent's host-side+/// hook via a `.ai-memory.toml` walk-up) OR `DEFAULT_WORKSPACE_NAME`.+/// 2. `project_override` OR `basename(cwd)` OR fallback to+/// `state.project_id` (when `cwd` is also unavailable).+///+/// Cache key is `(cwd, workspace_override, project_override)` so the+/// same `cwd` resolved with and without an override (e.g. during a+/// hook-script upgrade window) doesn't poison each other's slot.async fn resolve_project_ids(state: &HookState,cwd: Option<&str>,+ workspace_override: Option<&str>,+ project_override: Option<&str>,) -> anyhow::Result<(WorkspaceId, ProjectId)> {- let Some(cwd) = cwd.filter(|s| !s.is_empty()) else {+ let cwd_norm = cwd.filter(|s| !s.is_empty()).map(str::to_string);++ // Without cwd AND without a project override, there's nothing to+ // resolve — fall through to the server defaults.+ if cwd_norm.is_none() && project_override.is_none() {return Ok((state.workspace_id, state.project_id));- };+ }++ let cache_key = (+ cwd_norm.clone().unwrap_or_default(),+ workspace_override.unwrap_or("").to_string(),+ project_override.unwrap_or("").to_string(),+ );+{let cache = state.project_cache.lock().await;- if let Some(ids) = cache.get(cwd) {+ if let Some(ids) = cache.get(&cache_key) {// Republish on every hit: a cache hit still means the agent// is active in this project *now*, which is exactly what the// MCP read tools need as their default.@@ -223,35 +262,44 @@ async fn resolve_project_ids(return Ok(*ids);}}- let Some(project_name) = std::path::Path::new(cwd)- .file_name()- .and_then(|s| s.to_str())- .map(str::to_string)- .filter(|s| !s.is_empty())- else {- // Defensive: if basename derivation fails (e.g. cwd is "/"),- // fall back to the server defaults rather than hard-erroring.- state- .active_project- .set(state.workspace_id, state.project_id);- return Ok((state.workspace_id, state.project_id));++ let workspace_name = workspace_override+ .unwrap_or(DEFAULT_WORKSPACE_NAME)+ .to_string();++ let project_name = match (project_override, cwd_norm.as_deref()) {+ (Some(p), _) => p.to_string(),+ (None, Some(c)) => match std::path::Path::new(c)+ .file_name()+ .and_then(|s| s.to_str())+ .map(str::to_string)+ .filter(|s| !s.is_empty())+ {+ Some(name) => name,+ None => {+ // Defensive: basename derivation failed (e.g. cwd is "/").+ // Fall back to server defaults rather than hard-erroring.+ state+ .active_project+ .set(state.workspace_id, state.project_id);+ return Ok((state.workspace_id, state.project_id));+ }+ },+ (None, None) => unreachable!("guarded above by the early return"),};+let ws = state.writer- .get_or_create_workspace(DEFAULT_WORKSPACE_NAME.to_string())+ .get_or_create_workspace(workspace_name).await.map_err(|e| anyhow::anyhow!("get_or_create_workspace: {e}"))?;let proj = state.writer- .get_or_create_project(ws, project_name, Some(cwd.to_string()))+ .get_or_create_project(ws, project_name, cwd_norm.clone()).await.map_err(|e| anyhow::anyhow!("get_or_create_project: {e}"))?;let ids = (ws, proj);- state- .project_cache- .lock()- .await- .insert(cwd.to_string(), ids);+ state.project_cache.lock().await.insert(cache_key, ids);state.active_project.set(ws, proj);Ok(ids)}@@ -264,7 +312,13 @@ async fn process_envelope(state: Arc<HookState>, env: HookEnvelope) {async fn process(state: &HookState, env: HookEnvelope) -> anyhow::Result<()> {let session_id = resolve_session_id(&env)?;- let (ws, proj) = resolve_project_ids(state, env.cwd.as_deref()).await?;+ let (ws, proj) = resolve_project_ids(+ state,+ env.cwd.as_deref(),+ env.workspace_override.as_deref(),+ env.project_override.as_deref(),+ )+ .await?;// Hooks are fire-and-forget and may arrive out of order. Begin the// session idempotently before every observation so a resumed agent@@ -586,13 +640,15 @@ mod tests {let state = make_state(&tmp).await;// Event from /home/user/project-alpha.- let (ws_a, proj_a) = resolve_project_ids(&state, Some("/home/user/project-alpha"))- .await- .unwrap();+ let (ws_a, proj_a) =+ resolve_project_ids(&state, Some("/home/user/project-alpha"), None, None)+ .await+ .unwrap();// Event from /home/user/project-beta.- let (ws_b, proj_b) = resolve_project_ids(&state, Some("/home/user/project-beta"))- .await- .unwrap();+ let (ws_b, proj_b) =+ resolve_project_ids(&state, Some("/home/user/project-beta"), None, None)+ .await+ .unwrap();// Projects must be distinct; workspace is the same (`default`).assert_ne!(proj_a, proj_b, "different cwds → different projects");@@ -613,12 +669,14 @@ mod tests {let tmp = TempDir::new().unwrap();let state = make_state(&tmp).await;- let (ws, proj) = resolve_project_ids(&state, None).await.unwrap();+ let (ws, proj) = resolve_project_ids(&state, None, None, None).await.unwrap();assert_eq!(ws, state.workspace_id);assert_eq!(proj, state.project_id);// Likewise for an empty string.- let (ws2, proj2) = resolve_project_ids(&state, Some("")).await.unwrap();+ let (ws2, proj2) = resolve_project_ids(&state, Some(""), None, None)+ .await+ .unwrap();assert_eq!(ws2, state.workspace_id);assert_eq!(proj2, state.project_id);@@ -633,7 +691,9 @@ mod tests {let tmp = TempDir::new().unwrap();let state = make_state(&tmp).await;- let (ws, proj) = resolve_project_ids(&state, Some("/")).await.unwrap();+ let (ws, proj) = resolve_project_ids(&state, Some("/"), None, None)+ .await+ .unwrap();assert_eq!(ws, state.workspace_id);assert_eq!(proj, state.project_id);assert_eq!(state.active_project.get(), Some((ws, proj)));@@ -645,6 +705,7 @@ mod tests {HookQuery {event: "post-tool-use".into(),agent: Some("opencode".into()),+ ..Default::default()},serde_json::json!({ "sessionID": "opencode-session-123" }),);@@ -665,17 +726,25 @@ mod tests {let cwd = "/home/user/cached-project";// First call — populates the cache.- let (_, proj_first) = resolve_project_ids(&state, Some(cwd)).await.unwrap();+ let (_, proj_first) = resolve_project_ids(&state, Some(cwd), None, None)+ .await+ .unwrap();// Inspect the cache: should have exactly one entry.{let cache = state.project_cache.lock().await;assert_eq!(cache.len(), 1, "cache has one entry after first call");- assert!(cache.contains_key(cwd), "cache keyed by raw cwd");+ let key = (cwd.to_string(), String::new(), String::new());+ assert!(+ cache.contains_key(&key),+ "cache keyed by (cwd, ws_override, proj_override)"+ );}// Second call — must return the same IDs from the cache.- let (_, proj_second) = resolve_project_ids(&state, Some(cwd)).await.unwrap();+ let (_, proj_second) = resolve_project_ids(&state, Some(cwd), None, None)+ .await+ .unwrap();assert_eq!(proj_first, proj_second, "cache must return identical IDs");// Cache must still have exactly one entry (no duplicate insert).@@ -697,6 +766,7 @@ mod tests {HookQuery {event: "session-start".into(),agent: Some("claude-code".into()),+ ..Default::default()},serde_json::json!({"session_id": "test-session-cwd-routing",@@ -708,9 +778,10 @@ mod tests {// The observation must be in the project derived from the cwd,// not in the server-default `scratch` project.- let (_, expected_proj) = resolve_project_ids(&state, Some("/home/user/my-project"))- .await- .unwrap();+ let (_, expected_proj) =+ resolve_project_ids(&state, Some("/home/user/my-project"), None, None)+ .await+ .unwrap();assert_ne!(expected_proj, state.project_id,"routing must not use server-default project"@@ -726,6 +797,7 @@ mod tests {HookQuery {event: "user-prompt".into(),agent: Some("opencode".into()),+ ..Default::default()},serde_json::json!({"sessionID": "opencode-resumed-session",@@ -740,4 +812,112 @@ mod tests {assert_eq!(counts.sessions, 1);assert_eq!(counts.observations, 1);}++ /// `.ai-memory.toml` walk-up declares `workspace = "movvia"`. The hook+ /// forwards it as a query param, so the same `cwd` ends up in a+ /// distinct workspace from the default-buckets resolver path.+ #[tokio::test]+ async fn workspace_override_yields_distinct_workspace() {+ let tmp = TempDir::new().unwrap();+ let state = make_state(&tmp).await;++ let (ws_default, _) = resolve_project_ids(&state, Some("/home/u/repo"), None, None)+ .await+ .unwrap();+ let (ws_movvia, _) =+ resolve_project_ids(&state, Some("/home/u/repo"), Some("movvia"), None)+ .await+ .unwrap();++ assert_ne!(+ ws_default, ws_movvia,+ "marker-declared workspace must not collide with the default"+ );+ }++ /// A marker file with `project = "pe-portais"` replaces the+ /// basename-derived project name for every descendant `cwd`.+ #[tokio::test]+ async fn project_override_replaces_basename() {+ let tmp = TempDir::new().unwrap();+ let state = make_state(&tmp).await;++ let (_, proj_basename) = resolve_project_ids(&state, Some("/home/u/api"), None, None)+ .await+ .unwrap();+ let (_, proj_override) =+ resolve_project_ids(&state, Some("/home/u/api"), None, Some("pe-portais"))+ .await+ .unwrap();++ assert_ne!(+ proj_basename, proj_override,+ "project override must produce a different ProjectId than basename(cwd)"+ );+ }++ /// Two events resolved with overrides land in the same `(ws, proj)`+ /// pair as long as the override names match — even if the `cwd`+ /// differs. Confirms the override is the source of truth.+ #[tokio::test]+ async fn matching_overrides_collapse_to_same_pair() {+ let tmp = TempDir::new().unwrap();+ let state = make_state(&tmp).await;++ let (ws_a, proj_a) = resolve_project_ids(&state, Some("/x"), Some("acme"), Some("api"))+ .await+ .unwrap();+ let (ws_b, proj_b) = resolve_project_ids(&state, Some("/y"), Some("acme"), Some("api"))+ .await+ .unwrap();++ assert_eq!(ws_a, ws_b);+ assert_eq!(proj_a, proj_b);+ }++ /// During a hook-script upgrade window, the same `cwd` may resolve+ /// with and without an override in the same process. The composite+ /// cache key keeps both rows isolated; otherwise the first one+ /// "wins" and the second silently inherits its `ProjectId`.+ #[tokio::test]+ async fn cache_does_not_poison_across_override_variants() {+ let tmp = TempDir::new().unwrap();+ let state = make_state(&tmp).await;+ let cwd = "/home/u/poison-test";++ let (ws_default, _) = resolve_project_ids(&state, Some(cwd), None, None)+ .await+ .unwrap();+ let (ws_movvia, _) = resolve_project_ids(&state, Some(cwd), Some("movvia"), None)+ .await+ .unwrap();++ assert_ne!(+ ws_default, ws_movvia,+ "cache must distinguish override variants"+ );++ let cache = state.project_cache.lock().await;+ assert_eq!(+ cache.len(),+ 2,+ "two distinct cache entries for same cwd with different overrides"+ );+ }++ /// With no `cwd` but with both overrides, the resolver still produces+ /// a real `(ws, proj)` pair — covers handoff fetches issued before+ /// any hook event has populated the cwd cache.+ #[tokio::test]+ async fn overrides_resolve_without_cwd() {+ let tmp = TempDir::new().unwrap();+ let state = make_state(&tmp).await;++ let (ws, proj) = resolve_project_ids(&state, None, Some("acme"), Some("api"))+ .await+ .unwrap();++ assert_ne!(ws, state.workspace_id);+ assert_ne!(proj, state.project_id);+ }}