Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(auto-scope): thread ActorContext into every MCP read tool
Djalma Júnior9a85f9b67d69
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex da6b043f..fae96ffd 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).## [Unreleased]+### Added+- New `[auto_scope]` config block (`mode`, `session_ttl_secs`,+ `max_entries`) selects how the hook-published "currently active project"+ pointer is shared across concurrent MCP callers. The default `single` mode+ preserves the historical process-wide slot. Opt-in `per_session` keys the+ pointer by `session_id` to isolate concurrent agent runs of the same+ operator; opt-in `per_actor` keys by `(user, session_id)` to isolate+ across operators as well, pairing with multi-user mode where `user`+ comes from the `users` row that owns the bearer token. Per-key entries+ carry an insertion timestamp and are TTL-evicted (default 1 hour) and+ capped (default 4096) so adversarial / runaway clients cannot grow the+ map without bound. Both opt-in modes still publish to the single slot+ in parallel, so any caller without actor context falls back gracefully+ to the most recent project rather than an empty pointer. All MCP read+ tools (`memory_query`, `memory_recent`, `memory_read_page`,+ `memory_status`, `memory_briefing`, `memory_explore`, `memory_lint`,+ `memory_forget_sweep`, `memory_handoff_*`) now thread the request's+ `ActorContext` into scope resolution, so opt-in isolation takes effect+ for the full read surface.## [0.10.0] - 2026-06-04### Addeddiff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex 9d320722..8efcc61c 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -580,17 +580,6 @@ impl AiMemoryServer {/// `actor` is built by [`Self::actor_key_from_parts`]; pass/// `ActorKey::default()` when the call site has no request context./// Empty actor → fall back to the single slot (legacy behaviour).- /// Backward-compatible wrapper for call sites that have not yet- /// threaded a request `Parts` extension. Behaves like the historical- /// `effective_ids` — i.e. consults the single slot only — which is- /// what every tool gets under the default `[auto_scope] mode = single`.- /// Opt-in modes (`per_session` / `per_actor`) gain proper isolation as- /// each tool gets migrated to [`Self::effective_ids_with_actor`].- async fn effective_ids(&self, explicit_project: Option<&str>) -> (WorkspaceId, ProjectId) {- self.effective_ids_with_actor(explicit_project, &ai_memory_core::ActorKey::default())- .await- }-async fn effective_ids_with_actor(&self,explicit_project: Option<&str>,@@ -615,20 +604,6 @@ impl AiMemoryServer {active.unwrap_or((self.workspace_id, self.project_id))}- /// Backward-compatible wrapper paired with [`Self::effective_ids`].- async fn effective_ids_for_read_args(- &self,- explicit_workspace: Option<&str>,- explicit_project: Option<&str>,- ) -> Result<(WorkspaceId, ProjectId), McpError> {- self.effective_ids_for_read_args_with_actor(- explicit_workspace,- explicit_project,- &ai_memory_core::ActorKey::default(),- )- .await- }-async fn effective_ids_for_read_args_with_actor(&self,explicit_workspace: Option<&str>,@@ -863,7 +838,9 @@ impl AiMemoryServer {async fn memory_query(&self,Parameters(args): Parameters<QueryArgs>,+ Extension(parts): Extension<axum::http::request::Parts>,) -> Result<CallToolResult, McpError> {+ let aps_actor = Self::actor_key_from_parts(Some(&parts));let limit = args.limit.unwrap_or(self.default_limit).clamp(1, 100);if args.global.unwrap_or(false) {if !args.scopes.is_empty()@@ -912,7 +889,11 @@ impl AiMemoryServer {let query_vec = self.embed_query(&args.query).await;let hits = if args.scopes.is_empty() {let (ws, proj) = self- .effective_ids_for_read_args(args.workspace.as_deref(), args.project.as_deref())+ .effective_ids_for_read_args_with_actor(+ args.workspace.as_deref(),+ args.project.as_deref(),+ &aps_actor,+ ).await?;self.search_project(ws, proj, &args.query, query_vec.as_deref(), limit).await@@ -950,7 +931,11 @@ impl AiMemoryServer {// project; for multi-scope queries there is no single (ws, proj).let raw_hits = if hits.is_empty() && args.scopes.is_empty() {let (ws, proj) = self- .effective_ids_for_read_args(args.workspace.as_deref(), args.project.as_deref())+ .effective_ids_for_read_args_with_actor(+ args.workspace.as_deref(),+ args.project.as_deref(),+ &aps_actor,+ ).await?;self.reader.search_observations_for_project(ws, proj, query, limit)@@ -977,10 +962,16 @@ impl AiMemoryServer {async fn memory_recent(&self,Parameters(args): Parameters<RecentArgs>,+ Extension(parts): Extension<axum::http::request::Parts>,) -> Result<CallToolResult, McpError> {+ let aps_actor = Self::actor_key_from_parts(Some(&parts));let limit = args.limit.unwrap_or(self.default_limit).clamp(1, 100);let (ws, proj) = self- .effective_ids_for_read_args(args.workspace.as_deref(), args.project.as_deref())+ .effective_ids_for_read_args_with_actor(+ args.workspace.as_deref(),+ args.project.as_deref(),+ &aps_actor,+ ).await?;let hits = self.reader@@ -1002,9 +993,15 @@ impl AiMemoryServer {async fn memory_forget_sweep(&self,Parameters(args): Parameters<SweepArgs>,+ Extension(parts): Extension<axum::http::request::Parts>,) -> Result<CallToolResult, McpError> {+ let aps_actor = Self::actor_key_from_parts(Some(&parts));let (ws, proj) = self- .effective_ids_for_read_args(args.workspace.as_deref(), args.project.as_deref())+ .effective_ids_for_read_args_with_actor(+ args.workspace.as_deref(),+ args.project.as_deref(),+ &aps_actor,+ ).await?;let report = run_sweep(&self.reader,@@ -1027,7 +1024,9 @@ impl AiMemoryServer {async fn memory_lint(&self,Parameters(args): Parameters<LintArgs>,+ Extension(parts): Extension<axum::http::request::Parts>,) -> Result<CallToolResult, McpError> {+ let aps_actor = Self::actor_key_from_parts(Some(&parts));let Some(wiki) = self.wiki.as_ref() else {return Err(McpError::internal_error("memory_lint requires the server to be built with a wiki handle",@@ -1035,7 +1034,11 @@ impl AiMemoryServer {));};let (ws, proj) = self- .effective_ids_for_read_args(args.workspace.as_deref(), args.project.as_deref())+ .effective_ids_for_read_args_with_actor(+ args.workspace.as_deref(),+ args.project.as_deref(),+ &aps_actor,+ ).await?;let report = run_lint(&self.reader,@@ -1210,7 +1213,9 @@ impl AiMemoryServer {async fn memory_read_page(&self,Parameters(args): Parameters<ReadPageArgs>,+ Extension(parts): Extension<axum::http::request::Parts>,) -> Result<CallToolResult, McpError> {+ let aps_actor = Self::actor_key_from_parts(Some(&parts));let Some(wiki) = self.wiki.as_ref() else {return Err(McpError::internal_error("memory_read_page requires the server to be built with a wiki handle",@@ -1221,7 +1226,11 @@ impl AiMemoryServer {// can target a page in a DIFFERENT workspace (a sibling project on a// shared server). Plain `project` keeps the active-project chain.let (ws, proj) = self- .effective_ids_for_read_args(args.workspace.as_deref(), args.project.as_deref())+ .effective_ids_for_read_args_with_actor(+ args.workspace.as_deref(),+ args.project.as_deref(),+ &aps_actor,+ ).await?;let page_path = if let Some(p) = args.path {@@ -1312,6 +1321,7 @@ impl AiMemoryServer {Parameters(args): Parameters<DeletePageArgs>,Extension(parts): Extension<axum::http::request::Parts>,) -> Result<CallToolResult, McpError> {+ let aps_actor = Self::actor_key_from_parts(Some(&parts));let Some(wiki) = self.wiki.as_ref() else {return Err(McpError::internal_error("memory_delete_page requires the server to be built with a wiki handle",@@ -1320,12 +1330,12 @@ impl AiMemoryServer {};let path = PagePath::new(args.path.clone()).map_err(|e| McpError::internal_error(format!("invalid path: {e}"), None))?;- // Same resolution as read/write tools: when (workspace, project) are- // BOTH given, they're looked up explicitly; otherwise the cwd-based- // active-project chain is used. Closes the silent cross-workspace- // delete that the single-arg `effective_ids(project)` allowed.let (ws, proj) = self- .effective_ids_for_read_args(args.workspace.as_deref(), args.project.as_deref())+ .effective_ids_for_read_args_with_actor(+ args.workspace.as_deref(),+ args.project.as_deref(),+ &aps_actor,+ ).await?;// Carry actor identity + loop-prevention skip list (same as write_page).@@ -1370,14 +1380,18 @@ impl AiMemoryServer {async fn memory_handoff_begin(&self,Parameters(args): Parameters<HandoffBeginArgs>,+ Extension(parts): Extension<axum::http::request::Parts>,) -> Result<CallToolResult, McpError> {+ let aps_actor = Self::actor_key_from_parts(Some(&parts));// Handoffs bypass `Wiki::write_page` (they live in their own// table), so scrub the agent-supplied free-text here. We don't// touch `cwd` or `files_touched` — they're path lists that the// path-pattern regexes already cover when applicable, but we// pass each entry through anyway as defence-in-depth.let s = &self.sanitizer;- let (ws, proj) = self.effective_ids(args.project.as_deref()).await;+ let (ws, proj) = self+ .effective_ids_with_actor(args.project.as_deref(), &aps_actor)+ .await;let handoff = NewHandoff {workspace_id: ws,project_id: proj,@@ -1420,8 +1434,12 @@ impl AiMemoryServer {async fn memory_handoff_accept(&self,Parameters(args): Parameters<HandoffAcceptArgs>,+ Extension(parts): Extension<axum::http::request::Parts>,) -> Result<CallToolResult, McpError> {- let (ws, proj) = self.effective_ids(args.project.as_deref()).await;+ let aps_actor = Self::actor_key_from_parts(Some(&parts));+ let (ws, proj) = self+ .effective_ids_with_actor(args.project.as_deref(), &aps_actor)+ .await;let handoff = self.reader.latest_open_handoff(ws, proj, args.cwd)@@ -1451,11 +1469,17 @@ impl AiMemoryServer {async fn memory_handoff_cancel(&self,Parameters(args): Parameters<HandoffCancelArgs>,+ Extension(parts): Extension<axum::http::request::Parts>,) -> Result<CallToolResult, McpError> {+ let aps_actor = Self::actor_key_from_parts(Some(&parts));let handoff_id = HandoffId::from_str(&args.handoff_id).map_err(|e| McpError::internal_error(format!("invalid handoff_id: {e}"), None))?;let (ws, proj) = self- .effective_ids_for_read_args(args.workspace.as_deref(), args.project.as_deref())+ .effective_ids_for_read_args_with_actor(+ args.workspace.as_deref(),+ args.project.as_deref(),+ &aps_actor,+ ).await?;let handoff = self.reader@@ -1496,9 +1520,15 @@ impl AiMemoryServer {async fn memory_status(&self,Parameters(args): Parameters<StatusArgs>,+ Extension(parts): Extension<axum::http::request::Parts>,) -> Result<CallToolResult, McpError> {+ let aps_actor = Self::actor_key_from_parts(Some(&parts));let (ws, proj) = self- .effective_ids_for_read_args(args.workspace.as_deref(), args.project.as_deref())+ .effective_ids_for_read_args_with_actor(+ args.workspace.as_deref(),+ args.project.as_deref(),+ &aps_actor,+ ).await?;let counts = self.reader@@ -1522,10 +1552,16 @@ impl AiMemoryServer {async fn memory_briefing(&self,Parameters(args): Parameters<BriefingArgs>,+ Extension(parts): Extension<axum::http::request::Parts>,) -> Result<CallToolResult, McpError> {+ let aps_actor = Self::actor_key_from_parts(Some(&parts));let limit = args.recent_pages_limit.unwrap_or(10);let (ws, proj) = self- .effective_ids_for_read_args(args.workspace.as_deref(), args.project.as_deref())+ .effective_ids_for_read_args_with_actor(+ args.workspace.as_deref(),+ args.project.as_deref(),+ &aps_actor,+ ).await?;let snapshot = self.reader@@ -1552,10 +1588,16 @@ impl AiMemoryServer {async fn memory_explore(&self,Parameters(args): Parameters<ExploreArgs>,+ Extension(parts): Extension<axum::http::request::Parts>,) -> Result<CallToolResult, McpError> {+ let aps_actor = Self::actor_key_from_parts(Some(&parts));let limit = args.recent_pages_limit.unwrap_or(10);let (ws, proj) = self- .effective_ids_for_read_args(args.workspace.as_deref(), args.project.as_deref())+ .effective_ids_for_read_args_with_actor(+ args.workspace.as_deref(),+ args.project.as_deref(),+ &aps_actor,+ ).await?;let snapshot = self.reader@@ -1795,6 +1837,17 @@ fn build_explore_request(/// `prompts/explore_system.md`.const EXPLORE_SYSTEM_PROMPT: &str = include_str!("../prompts/explore_system.md");+#[cfg(test)]+fn test_parts_default() -> axum::http::request::Parts {+ axum::http::Request::builder()+ .uri("/mcp")+ .method("POST")+ .body(())+ .unwrap()+ .into_parts()+ .0+}+#[cfg(test)]mod tests {use super::*;@@ -2017,7 +2070,12 @@ mod tests {let (_tmp, store, server, ws, baked) = setup_server().await;// Baseline: nothing published, no arg → baked-in default.- assert_eq!(server.effective_ids(None).await, (ws, baked));+ assert_eq!(+ server+ .effective_ids_with_actor(None, &ai_memory_core::ActorKey::default())+ .await,+ (ws, baked)+ );// A second real project in the same workspace.let other = store@@ -2032,11 +2090,18 @@ mod tests {// Hook publishes it → it becomes the default for cwd-less calls.server.active_project.set(ws, other);- assert_eq!(server.effective_ids(None).await, (ws, other));+ assert_eq!(+ server+ .effective_ids_with_actor(None, &ai_memory_core::ActorKey::default())+ .await,+ (ws, other)+ );// An explicit (existing) project arg wins over the active pointer.assert_eq!(- server.effective_ids(Some("scratch")).await,+ server+ .effective_ids_with_actor(Some("scratch"), &ai_memory_core::ActorKey::default())+ .await,(ws, baked),"explicit project arg should override the active pointer");@@ -2044,7 +2109,12 @@ mod tests {// An explicit but unknown project name falls through to the// active pointer rather than erroring or returning a bogus id.assert_eq!(- server.effective_ids(Some("does-not-exist")).await,+ server+ .effective_ids_with_actor(+ Some("does-not-exist"),+ &ai_memory_core::ActorKey::default()+ )+ .await,(ws, other),"unknown explicit project falls through to the active pointer");@@ -2190,17 +2260,22 @@ mod tests {"direct read should see the written page");assert_eq!(- server.effective_ids(Some("sibling")).await,+ server+ .effective_ids_with_actor(Some("sibling"), &ai_memory_core::ActorKey::default())+ .await,(active_ws, sibling_proj),"project-only read resolution should use the active workspace");let result = server- .memory_recent(Parameters(RecentArgs {- limit: Some(5),- project: Some("sibling".to_string()),- workspace: None,- }))+ .memory_recent(+ Parameters(RecentArgs {+ limit: Some(5),+ project: Some("sibling".to_string()),+ workspace: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let text = result@@ -2223,14 +2298,17 @@ mod tests {async fn memory_query_returns_hits_via_tool_method() {let (_tmp, _store, server, _ws, _pj) = setup_server().await;let result = server- .memory_query(Parameters(QueryArgs {- query: "karpathy".into(),- limit: Some(5),- project: None,- scopes: Vec::new(),- workspace: None,- global: None,- }))+ .memory_query(+ Parameters(QueryArgs {+ query: "karpathy".into(),+ limit: Some(5),+ project: None,+ scopes: Vec::new(),+ workspace: None,+ global: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let text = match result.content.first().and_then(|c| c.as_text()) {@@ -2272,14 +2350,17 @@ mod tests {.unwrap();let result = server- .memory_query(Parameters(QueryArgs {- query: "quokka".into(),- limit: Some(5),- project: None,- scopes: Vec::new(),- workspace: None,- global: None,- }))+ .memory_query(+ Parameters(QueryArgs {+ query: "quokka".into(),+ limit: Some(5),+ project: None,+ scopes: Vec::new(),+ workspace: None,+ global: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let text = match result.content.first().and_then(|c| c.as_text()) {@@ -2328,14 +2409,17 @@ mod tests {.unwrap();let result = server- .memory_query(Parameters(QueryArgs {- query: "workspace_specific_token".into(),- limit: Some(5),- project: Some("unit-testing".into()),- scopes: Vec::new(),- workspace: Some("practice".into()),- global: None,- }))+ .memory_query(+ Parameters(QueryArgs {+ query: "workspace_specific_token".into(),+ limit: Some(5),+ project: Some("unit-testing".into()),+ scopes: Vec::new(),+ workspace: Some("practice".into()),+ global: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let text = result@@ -2379,12 +2463,15 @@ mod tests {let result = server.with_wiki(wiki)- .memory_read_page(Parameters(ReadPageArgs {- query: None,- path: Some("notes/sibling.md".into()),- project: Some("docs".into()),- workspace: Some("practice".into()),- }))+ .memory_read_page(+ Parameters(ReadPageArgs {+ query: None,+ path: Some("notes/sibling.md".into()),+ project: Some("docs".into()),+ workspace: Some("practice".into()),+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let text = result@@ -2426,12 +2513,15 @@ mod tests {let result = server.with_wiki(wiki)- .memory_read_page(Parameters(ReadPageArgs {- query: None,- path: Some("notes/db-only-tool.md".into()),- project: None,- workspace: None,- }))+ .memory_read_page(+ Parameters(ReadPageArgs {+ query: None,+ path: Some("notes/db-only-tool.md".into()),+ project: None,+ workspace: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let text = result@@ -2523,23 +2613,26 @@ mod tests {.unwrap();let result = server- .memory_query(Parameters(QueryArgs {- query: "multi_scope_token".into(),- limit: Some(10),- project: None,- scopes: vec![- MemoryScopeArg {- project: "product".into(),- workspace: "default".into(),- },- MemoryScopeArg {- project: "unit-testing".into(),- workspace: "practice".into(),- },- ],- workspace: None,- global: None,- }))+ .memory_query(+ Parameters(QueryArgs {+ query: "multi_scope_token".into(),+ limit: Some(10),+ project: None,+ scopes: vec![+ MemoryScopeArg {+ project: "product".into(),+ workspace: "default".into(),+ },+ MemoryScopeArg {+ project: "unit-testing".into(),+ workspace: "practice".into(),+ },+ ],+ workspace: None,+ global: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let text = result@@ -2598,14 +2691,17 @@ mod tests {}let result = server- .memory_query(Parameters(QueryArgs {- query: "global_token".into(),- limit: Some(10),- project: None,- scopes: Vec::new(),- workspace: None,- global: Some(true),- }))+ .memory_query(+ Parameters(QueryArgs {+ query: "global_token".into(),+ limit: Some(10),+ project: None,+ scopes: Vec::new(),+ workspace: None,+ global: Some(true),+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let text = result@@ -2629,14 +2725,17 @@ mod tests {async fn memory_query_global_rejects_explicit_scope() {let (_tmp, _store, server, _ws, _pj) = setup_server().await;let err = server- .memory_query(Parameters(QueryArgs {- query: "x".into(),- limit: Some(5),- project: Some("product".into()),- scopes: Vec::new(),- workspace: None,- global: Some(true),- }))+ .memory_query(+ Parameters(QueryArgs {+ query: "x".into(),+ limit: Some(5),+ project: Some("product".into()),+ scopes: Vec::new(),+ workspace: None,+ global: Some(true),+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await;assert!(err.is_err(),@@ -2648,10 +2747,13 @@ mod tests {async fn memory_status_returns_counts() {let (_tmp, _store, server, _ws, _pj) = setup_server().await;let result = server- .memory_status(Parameters(StatusArgs {- project: None,- workspace: None,- }))+ .memory_status(+ Parameters(StatusArgs {+ project: None,+ workspace: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let text = result@@ -2667,11 +2769,14 @@ mod tests {async fn memory_briefing_returns_structured_snapshot() {let (_tmp, _store, server, _ws, _pj) = setup_server().await;let result = server- .memory_briefing(Parameters(BriefingArgs {- recent_pages_limit: Some(5),- project: None,- workspace: None,- }))+ .memory_briefing(+ Parameters(BriefingArgs {+ recent_pages_limit: Some(5),+ project: None,+ workspace: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let text = result@@ -2711,12 +2816,15 @@ mod tests {async fn memory_explore_without_llm_degrades_to_briefing() {let (_tmp, _store, server, _ws, _pj) = setup_server().await;let result = server- .memory_explore(Parameters(ExploreArgs {- focus: None,- recent_pages_limit: Some(5),- project: None,- workspace: None,- }))+ .memory_explore(+ Parameters(ExploreArgs {+ focus: None,+ recent_pages_limit: Some(5),+ project: None,+ workspace: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let text = result@@ -2772,11 +2880,14 @@ mod tests {async fn memory_recent_returns_one_hit() {let (_tmp, _store, server, _ws, _pj) = setup_server().await;let result = server- .memory_recent(Parameters(RecentArgs {- limit: Some(5),- project: None,- workspace: None,- }))+ .memory_recent(+ Parameters(RecentArgs {+ limit: Some(5),+ project: None,+ workspace: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let text = result@@ -2841,11 +2952,14 @@ mod tests {assert!(text.contains("notes/santander-2025.md"), "got {text}");let recent = server- .memory_recent(Parameters(RecentArgs {- limit: Some(5),- project: None,- workspace: None,- }))+ .memory_recent(+ Parameters(RecentArgs {+ limit: Some(5),+ project: None,+ workspace: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let recent_text = recent@@ -2918,12 +3032,15 @@ mod tests {// The on-disk file is gone; reading it back errors (file not found).let read = server- .memory_read_page(Parameters(ReadPageArgs {- query: None,- path: Some("notes/temp.md".into()),- project: None,- workspace: None,- }))+ .memory_read_page(+ Parameters(ReadPageArgs {+ query: None,+ path: Some("notes/temp.md".into()),+ project: None,+ workspace: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await;assert!(read.is_err(), "deleted page must not be readable");@@ -2931,11 +3048,14 @@ mod tests {// does not reconcile deletions, so a file-only delete would leave the// page surfacing in recent/search with stale content.let recent = server- .memory_recent(Parameters(RecentArgs {- limit: Some(10),- project: None,- workspace: None,- }))+ .memory_recent(+ Parameters(RecentArgs {+ limit: Some(10),+ project: None,+ workspace: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let recent_text = recent@@ -3047,7 +3167,7 @@ mod tests {path: Some("notes/twin.md".into()),project: Some("shared".into()),workspace: Some("alpha".into()),- }))+ }), rmcp::handler::server::tool::Extension(test_parts_default())).await;assert!(read_alpha.is_ok(),@@ -3061,7 +3181,7 @@ mod tests {path: Some("notes/twin.md".into()),project: Some("shared".into()),workspace: Some("beta".into()),- }))+ }), rmcp::handler::server::tool::Extension(test_parts_default())).await;assert!(read_beta.is_err(),@@ -3120,11 +3240,14 @@ mod tests {// Visible in `other` (created), absent from the baked `scratch`.let in_other = server- .memory_recent(Parameters(RecentArgs {- limit: Some(5),- project: Some("other".into()),- workspace: None,- }))+ .memory_recent(+ Parameters(RecentArgs {+ limit: Some(5),+ project: Some("other".into()),+ workspace: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let other_text = in_other@@ -3139,11 +3262,14 @@ mod tests {);let in_scratch = server- .memory_recent(Parameters(RecentArgs {- limit: Some(5),- project: None,- workspace: None,- }))+ .memory_recent(+ Parameters(RecentArgs {+ limit: Some(5),+ project: None,+ workspace: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let scratch_text = in_scratch@@ -3172,23 +3298,29 @@ mod tests {server.active_project.set(ws, active);server- .memory_handoff_begin(Parameters(HandoffBeginArgs {- summary: "fix omp CHECK".into(),- open_questions: vec![],- next_steps: vec![],- files_touched: vec![],- cwd: Some(r"C:\GIT\ai-memory".into()),- project: None,- }))+ .memory_handoff_begin(+ Parameters(HandoffBeginArgs {+ summary: "fix omp CHECK".into(),+ open_questions: vec![],+ next_steps: vec![],+ files_touched: vec![],+ cwd: Some(r"C:\GIT\ai-memory".into()),+ project: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let briefing = server- .memory_briefing(Parameters(BriefingArgs {- recent_pages_limit: Some(5),- project: None,- workspace: None,- }))+ .memory_briefing(+ Parameters(BriefingArgs {+ recent_pages_limit: Some(5),+ project: None,+ workspace: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let text = briefing@@ -3207,14 +3339,17 @@ mod tests {async fn handoff_begin_then_accept_round_trips() {let (_tmp, _store, server, _ws, _pj) = setup_server().await;let begin = server- .memory_handoff_begin(Parameters(HandoffBeginArgs {- summary: "left mid-refactor of writer actor".into(),- open_questions: vec!["what max channel size?".into()],- next_steps: vec!["finish supersession path".into()],- files_touched: vec!["crates/ai-memory-store/src/writer.rs".into()],- cwd: Some("/tmp/aim".into()),- project: None,- }))+ .memory_handoff_begin(+ Parameters(HandoffBeginArgs {+ summary: "left mid-refactor of writer actor".into(),+ open_questions: vec!["what max channel size?".into()],+ next_steps: vec!["finish supersession path".into()],+ files_touched: vec!["crates/ai-memory-store/src/writer.rs".into()],+ cwd: Some("/tmp/aim".into()),+ project: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let begin_text = begin@@ -3227,10 +3362,13 @@ mod tests {// Accepting with matching cwd returns the handoff.let accept = server- .memory_handoff_accept(Parameters(HandoffAcceptArgs {- cwd: Some("/tmp/aim".into()),- project: None,- }))+ .memory_handoff_accept(+ Parameters(HandoffAcceptArgs {+ cwd: Some("/tmp/aim".into()),+ project: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let accept_text = accept@@ -3244,10 +3382,13 @@ mod tests {// Second accept returns null (handoff is now accepted).let again = server- .memory_handoff_accept(Parameters(HandoffAcceptArgs {- cwd: Some("/tmp/aim".into()),- project: None,- }))+ .memory_handoff_accept(+ Parameters(HandoffAcceptArgs {+ cwd: Some("/tmp/aim".into()),+ project: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.unwrap();let again_text = again@@ -3270,7 +3411,7 @@ mod tests {files_touched: vec![],cwd: Some("/tmp/aim".into()),project: None,- }))+ }), rmcp::handler::server::tool::Extension(test_parts_default())).await.unwrap();let begin_text = begin@@ -3287,7 +3428,7 @@ mod tests {recent_pages_limit: Some(5),project: None,workspace: None,- }))+ }), rmcp::handler::server::tool::Extension(test_parts_default())).await.unwrap();let before_text = before@@ -3303,7 +3444,7 @@ mod tests {handoff_id: handoff_id.clone(),project: None,workspace: None,- }))+ }), rmcp::handler::server::tool::Extension(test_parts_default())).await.unwrap();let cancel_text = cancel@@ -3320,7 +3461,7 @@ mod tests {recent_pages_limit: Some(5),project: None,workspace: None,- }))+ }), rmcp::handler::server::tool::Extension(test_parts_default())).await.unwrap();let after_text = after@@ -3335,7 +3476,7 @@ mod tests {.memory_handoff_accept(Parameters(HandoffAcceptArgs {cwd: Some("/tmp/aim".into()),project: None,- }))+ }), rmcp::handler::server::tool::Extension(test_parts_default())).await.unwrap();let accept_text = accept@@ -3387,12 +3528,15 @@ mod tests {async fn memory_lint_without_wiki_errors_cleanly() {let (_tmp, _store, server, _ws, _pj) = setup_server().await;let err = server- .memory_lint(Parameters(LintArgs {- dry_run: Some(true),- no_llm: None,- project: None,- workspace: None,- }))+ .memory_lint(+ Parameters(LintArgs {+ dry_run: Some(true),+ no_llm: None,+ project: None,+ workspace: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.expect_err("must reject when wiki is not attached");let msg = format!("{err:?}");@@ -3456,7 +3600,13 @@ mod tests {let sweep_count = |args: SweepArgs| {let server = &server;async move {- let out = server.memory_forget_sweep(Parameters(args)).await.unwrap();+ let out = server+ .memory_forget_sweep(+ Parameters(args),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ )+ .await+ .unwrap();let text = out.content.first()@@ -3500,10 +3650,13 @@ mod tests {async fn memory_handoff_accept_when_none_pending_returns_null() {let (_tmp, _store, server, _ws, _pj) = setup_server().await;let result = server- .memory_handoff_accept(Parameters(HandoffAcceptArgs {- cwd: None,- project: None,- }))+ .memory_handoff_accept(+ Parameters(HandoffAcceptArgs {+ cwd: None,+ project: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.expect("empty-queue must be Ok, not Err");let text = result@@ -3528,14 +3681,17 @@ mod tests {// with a sane response. (We don't have 10k pages, so the// hit count is small — we just need NOT to error.)let result = server- .memory_query(Parameters(QueryArgs {- query: "Karpathy".into(),- limit: Some(99_999),- project: None,- scopes: Vec::new(),- workspace: None,- global: None,- }))+ .memory_query(+ Parameters(QueryArgs {+ query: "Karpathy".into(),+ limit: Some(99_999),+ project: None,+ scopes: Vec::new(),+ workspace: None,+ global: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await.expect("oversized limit should be clamped, not refused");let text = result@@ -3556,14 +3712,17 @@ mod tests {async fn memory_query_malformed_fts5_returns_error() {let (_tmp, _store, server, _ws, _pj) = setup_server().await;let err = server- .memory_query(Parameters(QueryArgs {- query: "\"unbalanced".into(),- limit: Some(10),- project: None,- scopes: Vec::new(),- workspace: None,- global: None,- }))+ .memory_query(+ Parameters(QueryArgs {+ query: "\"unbalanced".into(),+ limit: Some(10),+ project: None,+ scopes: Vec::new(),+ workspace: None,+ global: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ ).await;// Either a tidy 0-hit Ok (FTS5 is occasionally lenient) or// an Err — both are acceptable. A panic is not.diff --git a/docs/auto-scope.md b/docs/auto-scope.mdnew file mode 100644index 00000000..68b652f9--- /dev/null+++ b/docs/auto-scope.md@@ -0,0 +1,84 @@+# `[auto_scope]` isolation modes++`ai-memory serve` publishes a process-shared "currently active project"+pointer that MCP read tools consult when the caller omits `workspace` /+`project`. The pointer is fed by the lifecycle hooks: every `/hook`+event that resolves a `cwd` to a real project updates the pointer so+read tools answer for the project the agent is actually in, not the+server's static `--project` default.++By default that pointer is a single process-wide slot — right for one+operator running one project at a time, but it collapses parallel+sessions on shared installs: a hook firing from `~/repo-A` overwrites+the slot that a concurrent `memory_query` (with no explicit project)+in `~/repo-B` was about to read.++The `[auto_scope]` config block selects opt-in isolation modes that+key the pointer by request identity so concurrent callers stay+separated.++## Modes++| `mode` | Key | When to use |+|---------------|------------------------|----------------------------------------------------------------------------------------------------------|+| `single` | (none — global slot) | **Default.** Single operator, one project at a time. Backward-compatible with every existing install. |+| `per_session` | `session_id` | Single operator running concurrent agent runs in different repos (e.g. several Claude Code / Codex windows open). |+| `per_actor` | `(user, session_id)` | Shared engine fielding multiple authenticated users (multi-user mode, rung 2). Isolates across operators too. |++Both opt-in modes still publish to the single slot in parallel, so a+caller with no actor identity (anonymous probe, legacy code path) sees+the most recent project rather than an empty pointer — graceful+degradation, never a silent error.++## Configuration++```toml+[auto_scope]+mode = "single" # "single" (default) | "per_session" | "per_actor"+session_ttl_secs = 3600 # TTL for per-key entries (default 1 h)+max_entries = 4096 # hard cap; oldest insertions evicted first+```++Environment-variable overrides follow the standard+`AI_MEMORY_<SECTION>__<KEY>` shape:++```bash+AI_MEMORY_AUTO_SCOPE__MODE=per_actor+AI_MEMORY_AUTO_SCOPE__SESSION_TTL_SECS=7200+AI_MEMORY_AUTO_SCOPE__MAX_ENTRIES=8192+```++## Where the actor identity comes from++| Source | Populates |+|----------------------------------------------------|----------------------------|+| Hook payload (`/hook?event=…&agent=…`) | `session_id`, `agent` |+| Auth middleware (rung 1 root with `root_username`) | `user` ← root_username |+| Auth middleware (rung 2 DB user) | `user` ← `users.username` |+| Anonymous / no token | empty actor → single slot |++`per_session` reads from `session_id`; `per_actor` reads from both+`user` and `session_id`. When either is missing, the lookup falls back+through the chain ending at the single slot.++## Pairing with multi-user mode++`per_actor` is most useful when the engine is in multi-user mode (see+[`docs/users.md`](users.md)) — each authenticated user has their own+`users.token_hash` row, so the auth middleware tags every request with+the right `user`. With `[auto_scope] mode = "per_actor"`, two+authenticated users running concurrent agent sessions through the same+engine no longer overwrite each other's "current project" pointer.++Single-user installs can use `per_session` alone (no `token_pepper`,+no `users` row) when one operator wants to run multiple agent windows+in parallel.++## Memory footprint++Per-key entries are tiny: two `Uuid`-sized ids + an `Instant`. With+the default `max_entries = 4096`, the map worst-cases at ~tens of KB+even on a corporate engine fielding hundreds of concurrent sessions.+The TTL ensures stale entries (closed Claude Code windows, dropped+hook clients) age out within an hour; the cap drops the oldest+insertions first if the TTL window is somehow exceeded.