Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(hooks): make repo-root project identity opt-in
AkitaOnRailsfd63f5ce31f2
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 16b0888d..441a0c26 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -19,8 +19,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0`workspace` (required) and `project` (optional) without depending on`basename($cwd)`. Lifecycle hook scripts walk up from `cwd` to findthe closest marker and forward `cwd` plus the declared names as- query params on `POST /hook` and `GET /handoff`. Server accepts the- new params as optional overrides;+ query params on `POST /hook` and `GET /handoff`. Markers can also set+ `project_strategy = "repo-root"` to derive project identity from the+ main git repository root, so linked worktrees share one project. Server+ accepts the new params as optional overrides;absent marker means the previous behaviour (`workspace = "default"`,`project = basename(cwd)`) — fully backward compatible. See[`docs/marker-file.md`](docs/marker-file.md).diff --git a/README.md b/README.mdindex 96db6054..ddcd1567 100644--- a/README.md+++ b/README.md@@ -60,8 +60,9 @@ priors are at the [bottom](#influences-and-prior-art).`<wiki_root>/<workspace_id>/<project_id>/…` keyed by stable UUIDs.By default `workspace = "default"` and `project = basename($cwd)`.Drop a [`.ai-memory.toml` marker file](docs/marker-file.md) in any- ancestor directory to override either — perfect for multi-client- consultancies, work/personal split, or mono-repos.+ ancestor directory to override either or opt into repo-root project+ identity — perfect for multi-client consultancies, work/personal split,+ mono-repos, or linked git worktrees.Same page path can exist in two projects without collision; arename is one column update; a purge is one `rm -rf`.- **Karpathy-style LLM wiki.** Pages are compiled from observations@@ -308,7 +309,7 @@ diagram, crate breakdown, schema notes, and invariants.|---|---|| [`docs/install.md`](docs/install.md) | **Installation cookbook.** Every agent CLI, every alternative (curl, source build, no-docker, no-auth), and the server-on-a-different-machine (homelab/LAN) walkthrough. Read after the Quick start if your setup doesn't match the happy path. || [`docs/usage.md`](docs/usage.md) | Handoffs, proactive memory queries, routing snippet, web UI, raw-wiki inspection, and rules-vs-facts workflow. |-| [`docs/marker-file.md`](docs/marker-file.md) | `.ai-memory.toml` workspace/project routing for multi-client trees, mono-repos, and work/personal separation. |+| [`docs/marker-file.md`](docs/marker-file.md) | `.ai-memory.toml` workspace/project routing for multi-client trees, mono-repos, worktrees, and work/personal separation. || [`docs/windows.md`](docs/windows.md) | Windows install modes: full WSL2, native Windows with Docker Desktop, native source builds, and current hook/MCP harness caveats. || [`docs/mcp-install.md`](docs/mcp-install.md) | Per-client MCP and lifecycle notes (Cursor, Claude Desktop, Gemini CLI, Antigravity CLI, OpenClaw, OMP). || [`docs/deploy.md`](docs/deploy.md) | Homelab deploy: bin/deploy, bearer-token auth, TLS via cloudflared. |diff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rsindex 7dabf8b8..5a5f8679 100644--- a/crates/ai-memory-cli/src/commands/install_hooks.rs+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs@@ -582,8 +582,10 @@ function applyMarkerParams(url: URL, cwd: string | undefined): void {{const body = readFileSync(marker, "utf8");const workspace = tomlKey(body, "workspace");const project = tomlKey(body, "project");+ const projectStrategy = tomlKey(body, "project_strategy");if (workspace) url.searchParams.set("workspace", workspace);if (project) url.searchParams.set("project", project);+ if (projectStrategy) url.searchParams.set("project_strategy", projectStrategy);}} catch (_e) {{}}}}@@ -869,8 +871,10 @@ function applyMarkerParams(url: URL, cwd: string | undefined): void {{const body = readFileSync(marker, "utf8");const workspace = tomlKey(body, "workspace");const project = tomlKey(body, "project");+ const projectStrategy = tomlKey(body, "project_strategy");if (workspace) url.searchParams.set("workspace", workspace);if (project) url.searchParams.set("project", project);+ if (projectStrategy) url.searchParams.set("project_strategy", projectStrategy);}} catch (_e) {{}}}}@@ -1531,6 +1535,8 @@ mod tests {assert!(plugin.contains("function applyMarkerParams"));assert!(plugin.contains("readFileSync(marker, \"utf8\")"));assert!(plugin.contains("text.split(/\\r?\\n/)"));+ assert!(plugin.contains("tomlKey(body, \"project_strategy\")"));+ assert!(plugin.contains("url.searchParams.set(\"project_strategy\", projectStrategy)"));assert!(plugin.contains("applyMarkerParams(url, typeof payload.cwd === \"string\" ? payload.cwd : undefined);"));@@ -1584,6 +1590,8 @@ mod tests {assert!(extension.contains("function applyMarkerParams"));assert!(extension.contains("readFileSync(marker, \"utf8\")"));assert!(extension.contains("text.split(/\\r?\\n/)"));+ assert!(extension.contains("tomlKey(body, \"project_strategy\")"));+ assert!(extension.contains("url.searchParams.set(\"project_strategy\", projectStrategy)"));assert!(extension.contains("applyMarkerParams(url, typeof payload.cwd === \"string\" ? payload.cwd : undefined);"));diff --git a/crates/ai-memory-hooks/src/payload.rs b/crates/ai-memory-hooks/src/payload.rsindex 51d46ec1..b3a33599 100644--- a/crates/ai-memory-hooks/src/payload.rs+++ b/crates/ai-memory-hooks/src/payload.rs@@ -22,6 +22,10 @@ pub struct HookQuery {/// Project name override (same source as `workspace`). When/// `None` the server falls back to `basename(cwd)`.pub project: Option<String>,+ /// Optional project derivation strategy from `.ai-memory.toml`.+ /// `repo-root` makes the server derive project identity from the+ /// main git repository root instead of `basename(cwd)`.+ pub project_strategy: Option<String>,/// Optional third-party extension namespace. When present, ai-memory/// preserves a validated source event name without expanding the/// closed core event vocabulary.@@ -52,6 +56,8 @@ pub struct HookEnvelope {/// Project name override declared by the hook. Empty / `None`/// defers to `basename(cwd)`.pub project_override: Option<String>,+ /// Project derivation strategy declared by the hook marker.+ pub project_strategy: ProjectStrategy,/// Optional third-party extension namespace.pub extension: Option<String>,/// Optional source event name from the extension vocabulary.@@ -64,6 +70,39 @@ pub struct HookEnvelope {pub raw: serde_json::Value,}+/// How the hook router derives a project name when no explicit+/// `project` override is present.+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize)]+#[serde(rename_all = "kebab-case")]+pub enum ProjectStrategy {+ /// Preserve v1 behavior: `project = basename(cwd)`.+ #[default]+ Basename,+ /// Opt-in marker behavior: `project = basename(main git repo root)`.+ RepoRoot,+}++impl ProjectStrategy {+ /// Parse a query-string marker value. Unknown values are ignored so a+ /// typo cannot route sessions into surprising new buckets.+ #[must_use]+ pub fn parse(value: Option<&str>) -> Self {+ match value {+ Some("repo-root" | "repo_root") => Self::RepoRoot,+ _ => Self::Basename,+ }+ }++ /// Stable cache-key representation.+ #[must_use]+ pub const fn as_str(self) -> &'static str {+ match self {+ Self::Basename => "basename",+ Self::RepoRoot => "repo-root",+ }+ }+}+/// Discriminator for the lifecycle event that triggered the hook.#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]#[serde(rename_all = "kebab-case")]@@ -199,6 +238,7 @@ impl HookEnvelope {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 project_strategy = ProjectStrategy::parse(query.project_strategy.as_deref());let extension = normalize_extension_name(query.extension.as_deref());let source_event = extension.as_ref().and_then(|_| {let raw_source = query@@ -229,6 +269,7 @@ impl HookEnvelope {cwd,workspace_override,project_override,+ project_strategy,extension,source_event,title_hint,@@ -551,6 +592,20 @@ mod tests {assert_eq!(env.title_hint.as_deref(), Some("claude-sonnet-4-6"));}+ #[test]+ fn envelope_parses_project_strategy_query() {+ let env = HookEnvelope::from_query_and_body(+ HookQuery {+ event: "session-start".into(),+ project_strategy: Some("repo-root".into()),+ ..Default::default()+ },+ serde_json::json!({}),+ );++ assert_eq!(env.project_strategy, ProjectStrategy::RepoRoot);+ }+/// Antigravity CLI identifies the conversation as `conversationId`/// and reports cwd-like routing through `workspacePaths`.#[test]diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rsindex 80732f0b..ac9b4f75 100644--- a/crates/ai-memory-hooks/src/router.rs+++ b/crates/ai-memory-hooks/src/router.rs@@ -31,7 +31,7 @@ use tracing::{debug, info, warn};use uuid::Uuid;use crate::log;-use crate::payload::{HookEnvelope, HookEvent, HookQuery, parse_agent};+use crate::payload::{HookEnvelope, HookEvent, HookQuery, ProjectStrategy, parse_agent};use crate::synth::synthesize_session_page;/// Default maximum number of hook events allowed to be processing at once.@@ -41,11 +41,11 @@ use crate::synth::synthesize_session_page;/// callers can drop or retry instead of growing memory without bound.pub const DEFAULT_HOOK_INGEST_MAX_IN_FLIGHT: usize = 1024;-/// Resolved-project cache: `(cwd, workspace_override, project_override)`+/// Resolved-project cache: `(cwd, workspace_override, project_override, project_strategy)`/// 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)>>>;+ Arc<tokio::sync::Mutex<HashMap<(String, String, String, String), (WorkspaceId, ProjectId)>>>;/// Shared state passed to the hook handler.#[derive(Clone)]@@ -69,7 +69,7 @@ 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_override, project_override) → ids`.+ /// Cache of `(cwd, workspace_override, project_override, project_strategy) → 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@@ -129,6 +129,8 @@ pub struct HandoffQuery {pub workspace: Option<String>,/// Project override (mirror of `HookQuery.project`).pub project: Option<String>,+ /// Project strategy (mirror of `HookQuery.project_strategy`).+ pub project_strategy: Option<String>,}/// Synchronous endpoint used by `session-start.sh` to discover any@@ -164,6 +166,7 @@ async fn fetch_and_accept_handoff(query.cwd.as_deref(),query.workspace.as_deref(),query.project.as_deref(),+ ProjectStrategy::parse(query.project_strategy.as_deref()),).await?;let handoff = state@@ -244,10 +247,11 @@ fn render_handoff_markdown(h: &Handoff) -> String {/// 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).+/// 2. `project_override` OR marker-selected project strategy OR+/// `basename(cwd)` OR fallback to `state.project_id` (when `cwd` is+/// also unavailable).///-/// Cache key is `(cwd, workspace_override, project_override)` so the+/// Cache key is `(cwd, workspace_override, project_override, project_strategy)` 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(@@ -255,6 +259,7 @@ async fn resolve_project_ids(cwd: Option<&str>,workspace_override: Option<&str>,project_override: Option<&str>,+ project_strategy: ProjectStrategy,) -> anyhow::Result<(WorkspaceId, ProjectId)> {let cwd_norm = cwd.filter(|s| !s.is_empty()).map(str::to_string);@@ -268,6 +273,7 @@ async fn resolve_project_ids(cwd_norm.clone().unwrap_or_default(),workspace_override.unwrap_or("").to_string(),project_override.unwrap_or("").to_string(),+ project_strategy.as_str().to_string(),);{@@ -285,34 +291,17 @@ async fn resolve_project_ids(.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)) => {- let path = std::path::Path::new(c);- // Resolve git repo root first — handles worktrees by following- // the .git gitdir pointer back to the main repository.- match ai_memory_consolidate::discover_main_repo_root(path)- .ok()- .and_then(|root| {- root.file_name()- .and_then(|s| s.to_str())- .map(str::to_string)- })- .or_else(|| {- path.file_name()- .and_then(|s| s.to_str())- .map(str::to_string)- .filter(|s| !s.is_empty())- }) {- Some(name) => name,- None => {- state- .active_project- .set(state.workspace_id, state.project_id);- return Ok((state.workspace_id, state.project_id));- }+ let (project_name, repo_path) = match (project_override, cwd_norm.as_deref()) {+ (Some(p), _) => (p.to_string(), cwd_norm.clone()),+ (None, Some(c)) => match derive_project_from_cwd(c, project_strategy) {+ Some(resolved) => resolved,+ None => {+ state+ .active_project+ .set(state.workspace_id, state.project_id);+ return Ok((state.workspace_id, state.project_id));}- }+ },(None, None) => {// The early-return at the top of the function guards// against this branch; the explicit fallback here keeps@@ -327,6 +316,27 @@ async fn resolve_project_ids(}};+ fn derive_project_from_cwd(+ cwd: &str,+ strategy: ProjectStrategy,+ ) -> Option<(String, Option<String>)> {+ let path = std::path::Path::new(cwd);+ if matches!(strategy, ProjectStrategy::RepoRoot)+ && let Ok(root) = ai_memory_consolidate::discover_main_repo_root(path)+ && let Some(name) = basename(&root)+ {+ return Some((name, Some(root.to_string_lossy().into_owned())));+ }+ basename(path).map(|name| (name, Some(cwd.to_string())))+ }++ fn basename(path: &std::path::Path) -> Option<String> {+ path.file_name()+ .and_then(|s| s.to_str())+ .map(str::to_string)+ .filter(|s| !s.is_empty())+ }+let ws = state.writer.get_or_create_workspace(workspace_name)@@ -334,7 +344,7 @@ async fn resolve_project_ids(.map_err(|e| anyhow::anyhow!("get_or_create_workspace: {e}"))?;let proj = state.writer- .get_or_create_project(ws, project_name, cwd_norm.clone())+ .get_or_create_project(ws, project_name, repo_path).await.map_err(|e| anyhow::anyhow!("get_or_create_project: {e}"))?;let ids = (ws, proj);@@ -356,6 +366,7 @@ async fn process(state: &HookState, env: HookEnvelope) -> anyhow::Result<()> {env.cwd.as_deref(),env.workspace_override.as_deref(),env.project_override.as_deref(),+ env.project_strategy,).await?;@@ -677,6 +688,21 @@ mod tests {}}+ fn init_repo_with_commit(path: &std::path::Path) -> git2::Repository {+ std::fs::create_dir_all(path).unwrap();+ let repo = git2::Repository::init(path).unwrap();+ let sig = repo+ .signature()+ .unwrap_or_else(|_| git2::Signature::now("test", "[email protected]").unwrap());+ let tree_id = repo.index().unwrap().write_tree().unwrap();+ {+ let tree = repo.find_tree(tree_id).unwrap();+ repo.commit(Some("HEAD"), &sig, &sig, "initial", &tree, &[])+ .unwrap();+ }+ repo+ }+/// Two hook events with distinct cwds must land in two distinct projects.#[tokio::test]async fn process_with_cwd_creates_new_project() {@@ -684,15 +710,25 @@ 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"), None, None)- .await- .unwrap();+ let (ws_a, proj_a) = resolve_project_ids(+ &state,+ Some("/home/user/project-alpha"),+ None,+ None,+ ProjectStrategy::Basename,+ )+ .await+ .unwrap();// Event from /home/user/project-beta.- let (ws_b, proj_b) =- resolve_project_ids(&state, Some("/home/user/project-beta"), None, None)- .await- .unwrap();+ let (ws_b, proj_b) = resolve_project_ids(+ &state,+ Some("/home/user/project-beta"),+ None,+ None,+ ProjectStrategy::Basename,+ )+ .await+ .unwrap();// Projects must be distinct; workspace is the same (`default`).assert_ne!(proj_a, proj_b, "different cwds → different projects");@@ -734,14 +770,17 @@ mod tests {let tmp = TempDir::new().unwrap();let state = make_state(&tmp).await;- let (ws, proj) = resolve_project_ids(&state, None, None, None).await.unwrap();+ let (ws, proj) = resolve_project_ids(&state, None, None, None, ProjectStrategy::Basename)+ .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(""), None, None)- .await- .unwrap();+ let (ws2, proj2) =+ resolve_project_ids(&state, Some(""), None, None, ProjectStrategy::Basename)+ .await+ .unwrap();assert_eq!(ws2, state.workspace_id);assert_eq!(proj2, state.project_id);@@ -756,9 +795,10 @@ mod tests {let tmp = TempDir::new().unwrap();let state = make_state(&tmp).await;- let (ws, proj) = resolve_project_ids(&state, Some("/"), None, None)- .await- .unwrap();+ let (ws, proj) =+ resolve_project_ids(&state, Some("/"), None, None, ProjectStrategy::Basename)+ .await+ .unwrap();assert_eq!(ws, state.workspace_id);assert_eq!(proj, state.project_id);assert_eq!(state.active_project.get(), Some((ws, proj)));@@ -791,25 +831,32 @@ mod tests {let cwd = "/home/user/cached-project";// First call — populates the cache.- let (_, proj_first) = resolve_project_ids(&state, Some(cwd), None, None)- .await- .unwrap();+ let (_, proj_first) =+ resolve_project_ids(&state, Some(cwd), None, None, ProjectStrategy::Basename)+ .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");- let key = (cwd.to_string(), String::new(), String::new());+ let key = (+ cwd.to_string(),+ String::new(),+ String::new(),+ ProjectStrategy::Basename.as_str().to_string(),+ );assert!(cache.contains_key(&key),- "cache keyed by (cwd, ws_override, proj_override)"+ "cache keyed by (cwd, ws_override, proj_override, project_strategy)");}// Second call — must return the same IDs from the cache.- let (_, proj_second) = resolve_project_ids(&state, Some(cwd), None, None)- .await- .unwrap();+ let (_, proj_second) =+ resolve_project_ids(&state, Some(cwd), None, None, ProjectStrategy::Basename)+ .await+ .unwrap();assert_eq!(proj_first, proj_second, "cache must return identical IDs");// Cache must still have exactly one entry (no duplicate insert).@@ -843,10 +890,15 @@ 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"), None, None)- .await- .unwrap();+ let (_, expected_proj) = resolve_project_ids(+ &state,+ Some("/home/user/my-project"),+ None,+ None,+ ProjectStrategy::Basename,+ )+ .await+ .unwrap();assert_ne!(expected_proj, state.project_id,"routing must not use server-default project"@@ -974,13 +1026,24 @@ mod tests {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();+ let (ws_default, _) = resolve_project_ids(+ &state,+ Some("/home/u/repo"),+ None,+ None,+ ProjectStrategy::Basename,+ )+ .await+ .unwrap();+ let (ws_movvia, _) = resolve_project_ids(+ &state,+ Some("/home/u/repo"),+ Some("movvia"),+ None,+ ProjectStrategy::Basename,+ )+ .await+ .unwrap();assert_ne!(ws_default, ws_movvia,@@ -994,9 +1057,15 @@ mod tests {let state = make_state(&tmp).await;let cwd = "/home/u/repo";- let (ws, proj) = resolve_project_ids(&state, Some(cwd), Some("acme"), None)- .await- .unwrap();+ let (ws, proj) = resolve_project_ids(+ &state,+ Some(cwd),+ Some("acme"),+ None,+ ProjectStrategy::Basename,+ )+ .await+ .unwrap();state.writer.insert_handoff(NewHandoff {@@ -1021,6 +1090,7 @@ mod tests {cwd: Some(cwd.into()),workspace: Some("acme".into()),project: None,+ project_strategy: None,},).await@@ -1039,13 +1109,24 @@ mod tests {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();+ let (_, proj_basename) = resolve_project_ids(+ &state,+ Some("/home/u/api"),+ None,+ None,+ ProjectStrategy::Basename,+ )+ .await+ .unwrap();+ let (_, proj_override) = resolve_project_ids(+ &state,+ Some("/home/u/api"),+ None,+ Some("pe-portais"),+ ProjectStrategy::Basename,+ )+ .await+ .unwrap();assert_ne!(proj_basename, proj_override,@@ -1061,12 +1142,24 @@ mod tests {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();+ let (ws_a, proj_a) = resolve_project_ids(+ &state,+ Some("/x"),+ Some("acme"),+ Some("api"),+ ProjectStrategy::Basename,+ )+ .await+ .unwrap();+ let (ws_b, proj_b) = resolve_project_ids(+ &state,+ Some("/y"),+ Some("acme"),+ Some("api"),+ ProjectStrategy::Basename,+ )+ .await+ .unwrap();assert_eq!(ws_a, ws_b);assert_eq!(proj_a, proj_b);@@ -1082,12 +1175,19 @@ mod tests {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();+ let (ws_default, _) =+ resolve_project_ids(&state, Some(cwd), None, None, ProjectStrategy::Basename)+ .await+ .unwrap();+ let (ws_movvia, _) = resolve_project_ids(+ &state,+ Some(cwd),+ Some("movvia"),+ None,+ ProjectStrategy::Basename,+ )+ .await+ .unwrap();assert_ne!(ws_default, ws_movvia,@@ -1110,16 +1210,147 @@ mod tests {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();+ let (ws, proj) = resolve_project_ids(+ &state,+ None,+ Some("acme"),+ Some("api"),+ ProjectStrategy::Basename,+ )+ .await+ .unwrap();assert_ne!(ws, state.workspace_id);assert_ne!(proj, state.project_id);}+ #[test]+ fn unknown_project_strategy_defaults_to_basename() {+ assert_eq!(+ ProjectStrategy::parse(Some("repo-root")),+ ProjectStrategy::RepoRoot+ );+ assert_eq!(+ ProjectStrategy::parse(Some("repo_root")),+ ProjectStrategy::RepoRoot+ );+ assert_eq!(+ ProjectStrategy::parse(Some("git-root")),+ ProjectStrategy::Basename+ );+ }++ #[tokio::test]+ async fn default_strategy_keeps_git_subdirs_as_basename_projects() {+ let tmp = TempDir::new().unwrap();+ let state = make_state(&tmp).await;++ let main_dir = tmp.path().join("my-project");+ init_repo_with_commit(&main_dir);+ let app_dir = main_dir.join("app");+ std::fs::create_dir_all(&app_dir).unwrap();+ let app_cwd = app_dir.to_str().unwrap();++ let (_, proj_basename) =+ resolve_project_ids(&state, Some(app_cwd), None, None, ProjectStrategy::Basename)+ .await+ .unwrap();+ let (_, proj_explicit_app) = resolve_project_ids(+ &state,+ Some(main_dir.to_str().unwrap()),+ None,+ Some("app"),+ ProjectStrategy::RepoRoot,+ )+ .await+ .unwrap();+ let (_, proj_repo_root) =+ resolve_project_ids(&state, Some(app_cwd), None, None, ProjectStrategy::RepoRoot)+ .await+ .unwrap();++ assert_eq!(+ proj_basename, proj_explicit_app,+ "default strategy must keep project = basename(cwd) inside git repos"+ );+ assert_ne!(+ proj_basename, proj_repo_root,+ "repo-root strategy is opt-in and must not affect the basename default"+ );+ }++ #[tokio::test]+ async fn project_override_wins_over_repo_root_strategy() {+ let tmp = TempDir::new().unwrap();+ let state = make_state(&tmp).await;++ let main_dir = tmp.path().join("repo");+ init_repo_with_commit(&main_dir);+ let app_dir = main_dir.join("app");+ std::fs::create_dir_all(&app_dir).unwrap();+ let app_cwd = app_dir.to_str().unwrap();++ let (_, proj_repo_root) =+ resolve_project_ids(&state, Some(app_cwd), None, None, ProjectStrategy::RepoRoot)+ .await+ .unwrap();+ let (_, proj_override_repo_root) = resolve_project_ids(+ &state,+ Some(app_cwd),+ None,+ Some("manual"),+ ProjectStrategy::RepoRoot,+ )+ .await+ .unwrap();+ let (_, proj_override_basename) = resolve_project_ids(+ &state,+ Some(app_cwd),+ None,+ Some("manual"),+ ProjectStrategy::Basename,+ )+ .await+ .unwrap();++ assert_eq!(proj_override_repo_root, proj_override_basename);+ assert_ne!(+ proj_override_repo_root, proj_repo_root,+ "explicit project override must beat repo-root derivation"+ );+ }++ #[tokio::test]+ async fn cache_does_not_poison_across_project_strategies() {+ let tmp = TempDir::new().unwrap();+ let state = make_state(&tmp).await;++ let main_dir = tmp.path().join("repo");+ init_repo_with_commit(&main_dir);+ let app_dir = main_dir.join("app");+ std::fs::create_dir_all(&app_dir).unwrap();+ let app_cwd = app_dir.to_str().unwrap();++ let (_, proj_basename) =+ resolve_project_ids(&state, Some(app_cwd), None, None, ProjectStrategy::Basename)+ .await+ .unwrap();+ let (_, proj_repo_root) =+ resolve_project_ids(&state, Some(app_cwd), None, None, ProjectStrategy::RepoRoot)+ .await+ .unwrap();++ assert_ne!(proj_basename, proj_repo_root);+ let cache = state.project_cache.lock().await;+ assert_eq!(+ cache.len(),+ 2,+ "same cwd must have isolated cache entries per project strategy"+ );+ }+/// A git worktree must resolve to the same project as the main- /// working directory — both share the same repository identity.+ /// working directory only when the marker opts into repo-root identity.#[tokio::test]async fn worktree_resolves_to_same_project_as_main_repo() {let tmp = TempDir::new().unwrap();@@ -1127,17 +1358,7 @@ mod tests {// Create a real git repo inside the temp dir.let main_dir = tmp.path().join("my-project");- std::fs::create_dir_all(&main_dir).unwrap();- let repo = git2::Repository::init(&main_dir).unwrap();-- // git2 requires at least one commit before creating a worktree.- let sig = repo- .signature()- .unwrap_or_else(|_| git2::Signature::now("test", "[email protected]").unwrap());- let tree_id = repo.index().unwrap().write_tree().unwrap();- let tree = repo.find_tree(tree_id).unwrap();- repo.commit(Some("HEAD"), &sig, &sig, "initial", &tree, &[])- .unwrap();+ let repo = init_repo_with_commit(&main_dir);// Create a worktree in a sibling directory.let wt_dir = tmp.path().join("my-project-feature-branch");@@ -1154,18 +1375,34 @@ mod tests {let main_cwd = main_dir.to_str().unwrap();let wt_cwd = wt_dir.to_str().unwrap();- let (ws_main, proj_main) = resolve_project_ids(&state, Some(main_cwd), None, None)- .await- .unwrap();- let (ws_wt, proj_wt) = resolve_project_ids(&state, Some(wt_cwd), None, None)- .await- .unwrap();+ let (ws_main, proj_main) = resolve_project_ids(+ &state,+ Some(main_cwd),+ None,+ None,+ ProjectStrategy::RepoRoot,+ )+ .await+ .unwrap();+ let (ws_wt, proj_wt) =+ resolve_project_ids(&state, Some(wt_cwd), None, None, ProjectStrategy::RepoRoot)+ .await+ .unwrap();assert_eq!(ws_main, ws_wt, "same workspace");assert_eq!(proj_main, proj_wt,"worktree must resolve to same project as main repo");++ let (_, proj_wt_basename) =+ resolve_project_ids(&state, Some(wt_cwd), None, None, ProjectStrategy::Basename)+ .await+ .unwrap();+ assert_ne!(+ proj_main, proj_wt_basename,+ "default strategy must not collapse worktrees into the main repo project"+ );}/// A directory that is NOT inside a git repo must still resolve@@ -1180,9 +1417,10 @@ mod tests {std::fs::create_dir_all(&plain_dir).unwrap();let cwd = plain_dir.to_str().unwrap();- let (_, proj) = resolve_project_ids(&state, Some(cwd), None, None)- .await- .unwrap();+ let (_, proj) =+ resolve_project_ids(&state, Some(cwd), None, None, ProjectStrategy::Basename)+ .await+ .unwrap();// Must NOT be the server-default scratch project.assert_ne!(proj, state.project_id);@@ -1191,9 +1429,15 @@ mod tests {// they produce distinct projects (basename-based).let other_dir = tmp.path().join("other-project");std::fs::create_dir_all(&other_dir).unwrap();- let (_, proj2) = resolve_project_ids(&state, Some(other_dir.to_str().unwrap()), None, None)- .await- .unwrap();+ let (_, proj2) = resolve_project_ids(+ &state,+ Some(other_dir.to_str().unwrap()),+ None,+ None,+ ProjectStrategy::Basename,+ )+ .await+ .unwrap();assert_ne!(proj, proj2, "different basenames → different projects");}@@ -1208,9 +1452,10 @@ mod tests {git2::Repository::init_bare(&bare_dir).unwrap();let cwd = bare_dir.to_str().unwrap();- let (_, proj) = resolve_project_ids(&state, Some(cwd), None, None)- .await- .unwrap();+ let (_, proj) =+ resolve_project_ids(&state, Some(cwd), None, None, ProjectStrategy::Basename)+ .await+ .unwrap();// Must NOT be the server-default scratch project — basename should work.assert_ne!(proj, state.project_id);@@ -1219,9 +1464,15 @@ mod tests {// To verify: resolve with a different bare repo name and confirm different project.let bare_dir2 = tmp.path().join("other-bare.git");git2::Repository::init_bare(&bare_dir2).unwrap();- let (_, proj2) = resolve_project_ids(&state, Some(bare_dir2.to_str().unwrap()), None, None)- .await- .unwrap();+ let (_, proj2) = resolve_project_ids(+ &state,+ Some(bare_dir2.to_str().unwrap()),+ None,+ None,+ ProjectStrategy::Basename,+ )+ .await+ .unwrap();assert_ne!(proj, proj2,"different bare repo basenames → different projects"diff --git a/docs/marker-file.md b/docs/marker-file.mdindex d4972081..e6d8fbc6 100644--- a/docs/marker-file.md+++ b/docs/marker-file.md@@ -32,8 +32,9 @@ handoff lookups.The marker path is shared by the POSIX/PowerShell hook scripts and thegenerated OpenCode / OMP TypeScript integrations. In all cases, hook-capture and handoff lookup send the same `cwd`, `workspace`, and-`project` query params to the server when a marker is present.+capture and handoff lookup send the same `cwd`, `workspace`, `project`,+and `project_strategy` query params to the server when a marker is+present.## Schema@@ -45,9 +46,15 @@ workspace = "movvia"# cwd inside this marker's tree. Omit it to let basename(cwd) drive# the project name.project = "pe-portais"++# Optional. Omit it to preserve project = basename(cwd). Set it to+# "repo-root" to derive project from the main git repository root, so+# linked worktrees and subdirectories share one project. Ignored when+# `project` is present.+project_strategy = "repo-root"```-**Naming rules**, validated server-side:+**Naming rules** for `workspace` and `project`, validated server-side:- Lowercase ASCII, digits, dots, dashes, underscores- Regex: `^[a-z0-9][a-z0-9._-]*$`@@ -56,7 +63,10 @@ Anything else is rejected at `get_or_create_workspace` / `_project`time, surfacing as a hook warning. The shell helper URL-encodesdefensively but the server's regex is the source of truth.-## Three canonical examples+`project_strategy` accepts `repo-root` (or `repo_root`) only. Unknown+values are ignored and behave like the default `basename(cwd)` strategy.++## Four canonical examples### Multi-client@@ -86,6 +96,22 @@ Outcome:- `~/projects/movvia/pe-portais/apps/web` → workspace = `movvia`, project = `pe-portais`(closer marker wins)+### Git worktrees / repo-root identity++```+~/projects/ai-memory/.ai-memory.toml → workspace = "oss"+ → project_strategy = "repo-root"+```++Outcome:++- `~/projects/ai-memory` → workspace = `oss`, project = `ai-memory`+- `~/projects/ai-memory/crates/cli` → workspace = `oss`, project = `ai-memory`+- `~/projects/ai-memory-feature-branch` → workspace = `oss`, project = `ai-memory`++Without `project_strategy = "repo-root"`, those same paths keep the+default behavior and resolve by their current directory basename.+### Single workspace, no per-repo overrides```@@ -112,6 +138,8 @@ ai-memory rename-project \- ❌ No glob patterns. Walk-up by literal ancestry only.- ❌ No merge of ancestor markers. Closest wins.- ❌ No automatic migration of `default`-workspace projects.+- ❌ No automatic repo-root collapsing. Worktrees and subdirectories only+ share a project when `project_strategy = "repo-root"` is explicitly set.- ❌ No env / auth / hook-url override. Use the existing env vars(`AI_MEMORY_AUTH_TOKEN`, `AI_MEMORY_HOOK_URL`) for those.@@ -127,6 +155,7 @@ ai-memory rename-project \markers in your tree.4. The workspace / project values match the regex above (lowercasealphanumerics, dots, dashes, underscores).+5. If you use `project_strategy`, it is exactly `repo-root`.Hook scripts run fire-and-forget by design, so they don't log onsuccess. To see what's actually being sent, run a hook script bydiff --git a/hooks/_lib.sh b/hooks/_lib.shindex 95612604..c2707ad6 100644--- a/hooks/_lib.sh+++ b/hooks/_lib.sh@@ -68,7 +68,8 @@ ai_memory_url_encode() {# Build a query-string suffix from the marker file walked up from "$1".# Returns the suffix (with the leading `&`) or nothing. `cwd` is included# whenever a marker exists so `GET /handoff` can resolve workspace-only-# markers by combining `workspace` with basename(cwd).+# markers by combining `workspace` with basename(cwd), or apply an opt-in+# project strategy.ai_memory_marker_qs() {cwd="$1"[ -z "$cwd" ] && return 0@@ -76,9 +77,11 @@ ai_memory_marker_qs() {[ -z "$marker" ] && return 0ws=$(ai_memory_parse_toml_key "$marker" workspace)pr=$(ai_memory_parse_toml_key "$marker" project)+ st=$(ai_memory_parse_toml_key "$marker" project_strategy)qs="&cwd=$(ai_memory_url_encode "$cwd")"[ -n "$ws" ] && qs="${qs}&workspace=$(ai_memory_url_encode "$ws")"[ -n "$pr" ] && qs="${qs}&project=$(ai_memory_url_encode "$pr")"+ [ -n "$st" ] && qs="${qs}&project_strategy=$(ai_memory_url_encode "$st")"printf '%s' "$qs"}diff --git a/hooks/claude-code/post-tool-use.sh b/hooks/claude-code/post-tool-use.shindex d5d483a1..2342eaa0 100755--- a/hooks/claude-code/post-tool-use.sh+++ b/hooks/claude-code/post-tool-use.sh@@ -2,8 +2,8 @@# Claude Code post-tool-use hook.# Forwards the event JSON to the ai-memory server, fire-and-forget.# Walks up from the payload's cwd for a .ai-memory.toml marker file;-# if found, appends `&workspace=X&project=Y` to the URL so the server-# routes the event to the declared workspace/project pair instead of+# if found, appends marker query params to the URL so the server+# applies the declared workspace/project/strategy instead of# bucketing by basename(cwd) under the default workspace.# At runtime (after `install-hooks --apply`) `_lib.sh` is staged# alongside this script. From the source tree it lives one dir up.diff --git a/hooks/claude-code/pre-compact.sh b/hooks/claude-code/pre-compact.shindex 1fe049e3..a73d46d6 100755--- a/hooks/claude-code/pre-compact.sh+++ b/hooks/claude-code/pre-compact.sh@@ -2,8 +2,8 @@# Claude Code pre-compact hook.# Forwards the event JSON to the ai-memory server, fire-and-forget.# Walks up from the payload's cwd for a .ai-memory.toml marker file;-# if found, appends `&workspace=X&project=Y` to the URL so the server-# routes the event to the declared workspace/project pair instead of+# if found, appends marker query params to the URL so the server+# applies the declared workspace/project/strategy instead of# bucketing by basename(cwd) under the default workspace.# At runtime (after `install-hooks --apply`) `_lib.sh` is staged# alongside this script. From the source tree it lives one dir up.diff --git a/hooks/claude-code/pre-tool-use.sh b/hooks/claude-code/pre-tool-use.shindex 8ab1a366..b0ec2594 100755--- a/hooks/claude-code/pre-tool-use.sh+++ b/hooks/claude-code/pre-tool-use.sh@@ -2,8 +2,8 @@# Claude Code pre-tool-use hook.# Forwards the event JSON to the ai-memory server, fire-and-forget.# Walks up from the payload's cwd for a .ai-memory.toml marker file;-# if found, appends `&workspace=X&project=Y` to the URL so the server-# routes the event to the declared workspace/project pair instead of+# if found, appends marker query params to the URL so the server+# applies the declared workspace/project/strategy instead of# bucketing by basename(cwd) under the default workspace.# At runtime (after `install-hooks --apply`) `_lib.sh` is staged# alongside this script. From the source tree it lives one dir up.diff --git a/hooks/claude-code/session-end.sh b/hooks/claude-code/session-end.shindex 2f40461c..868ee98e 100755--- a/hooks/claude-code/session-end.sh+++ b/hooks/claude-code/session-end.sh@@ -2,8 +2,8 @@# Claude Code session-end hook.# Forwards the event JSON to the ai-memory server, fire-and-forget.# Walks up from the payload's cwd for a .ai-memory.toml marker file;-# if found, appends `&workspace=X&project=Y` to the URL so the server-# routes the event to the declared workspace/project pair instead of+# if found, appends marker query params to the URL so the server+# applies the declared workspace/project/strategy instead of# bucketing by basename(cwd) under the default workspace.# At runtime (after `install-hooks --apply`) `_lib.sh` is staged# alongside this script. From the source tree it lives one dir up.diff --git a/hooks/claude-code/session-start.sh b/hooks/claude-code/session-start.shindex 29286f90..7236a420 100755--- a/hooks/claude-code/session-start.sh+++ b/hooks/claude-code/session-start.sh@@ -7,9 +7,9 @@# human in the loop.## Walks up from the payload's cwd for a .ai-memory.toml marker file-# and appends `&workspace=X&project=Y` to both URLs when found — so a-# session resuming under a marker-declared workspace doesn't query the-# `default` bucket and miss its own handoff.+# and appends marker query params to both URLs when found — so a+# session resuming under marker-declared routing doesn't query the+# wrong bucket and miss its own handoff.# At runtime (after `install-hooks --apply`) `_lib.sh` is staged# alongside this script. From the source tree it lives one dir up._lib_dir="$(dirname "$0")"diff --git a/hooks/claude-code/stop.sh b/hooks/claude-code/stop.shindex c52bd2e0..e6c67b12 100755--- a/hooks/claude-code/stop.sh+++ b/hooks/claude-code/stop.sh@@ -2,8 +2,8 @@# Claude Code stop hook.# Forwards the event JSON to the ai-memory server, fire-and-forget.# Walks up from the payload's cwd for a .ai-memory.toml marker file;-# if found, appends `&workspace=X&project=Y` to the URL so the server-# routes the event to the declared workspace/project pair instead of+# if found, appends marker query params to the URL so the server+# applies the declared workspace/project/strategy instead of# bucketing by basename(cwd) under the default workspace.# At runtime (after `install-hooks --apply`) `_lib.sh` is staged# alongside this script. From the source tree it lives one dir up.diff --git a/hooks/claude-code/user-prompt-submit.sh b/hooks/claude-code/user-prompt-submit.shindex f8994466..c2de7196 100755--- a/hooks/claude-code/user-prompt-submit.sh+++ b/hooks/claude-code/user-prompt-submit.sh@@ -2,8 +2,8 @@# Claude Code user-prompt hook.# Forwards the event JSON to the ai-memory server, fire-and-forget.# Walks up from the payload's cwd for a .ai-memory.toml marker file;-# if found, appends `&workspace=X&project=Y` to the URL so the server-# routes the event to the declared workspace/project pair instead of+# if found, appends marker query params to the URL so the server+# applies the declared workspace/project/strategy instead of# bucketing by basename(cwd) under the default workspace.# At runtime (after `install-hooks --apply`) `_lib.sh` is staged# alongside this script. From the source tree it lives one dir up.diff --git a/hooks/lib/ai-memory-hook.ps1 b/hooks/lib/ai-memory-hook.ps1index 67a3ada6..3f6b0455 100644--- a/hooks/lib/ai-memory-hook.ps1+++ b/hooks/lib/ai-memory-hook.ps1@@ -43,6 +43,8 @@ function Get-AiMemoryMarkerQuery {if ($ws) { $qs += "&workspace=$([uri]::EscapeDataString($ws))" }$proj = Get-AiMemoryTomlKey -File $marker -Key "project"if ($proj) { $qs += "&project=$([uri]::EscapeDataString($proj))" }+ $strategy = Get-AiMemoryTomlKey -File $marker -Key "project_strategy"+ if ($strategy) { $qs += "&project_strategy=$([uri]::EscapeDataString($strategy))" }return $qs}diff --git a/tests/hooks/test_lib.sh b/tests/hooks/test_lib.shindex bdf4ef4a..cf098859 100755--- a/tests/hooks/test_lib.sh+++ b/tests/hooks/test_lib.sh@@ -35,12 +35,14 @@ cat >"$TMP/sample.toml" <<EOF# Comment lineworkspace = "movvia"project = "pe-portais"+project_strategy = "repo-root"# Trailing commentEOFassert_eq "parse workspace" "movvia" "$(ai_memory_parse_toml_key "$TMP/sample.toml" workspace)"assert_eq "parse project" "pe-portais" "$(ai_memory_parse_toml_key "$TMP/sample.toml" project)"+assert_eq "parse project_strategy" "repo-root" "$(ai_memory_parse_toml_key "$TMP/sample.toml" project_strategy)"assert_eq "absent key returns empty" "" "$(ai_memory_parse_toml_key "$TMP/sample.toml" missing)"assert_eq "absent file returns empty" "" "$(ai_memory_parse_toml_key "$TMP/no-such-file.toml" workspace)"@@ -71,9 +73,9 @@ assert_eq "json_string escapes text" '"quoted \"thing\" \\ path\nnext line"' \QS=$(ai_memory_marker_qs "$TMP/a/b/c")assert_eq "marker_qs single key" "&cwd=$TMP/a/b/c&workspace=deep" "$QS"-printf 'workspace = "ws1"\nproject = "p1"\n' >"$TMP/a/b/.ai-memory.toml"+printf 'workspace = "ws1"\nproject = "p1"\nproject_strategy = "repo-root"\n' >"$TMP/a/b/.ai-memory.toml"QS2=$(ai_memory_marker_qs "$TMP/a/b/c")-assert_eq "closer marker wins" "&cwd=$TMP/a/b/c&workspace=ws1&project=p1" "$QS2"+assert_eq "closer marker wins" "&cwd=$TMP/a/b/c&workspace=ws1&project=p1&project_strategy=repo-root" "$QS2"QS3=$(ai_memory_marker_qs "$TMP/nonexistent")assert_eq "no marker -> empty qs" "" "$QS3"