Skip to content

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.md
index 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
### Added
diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rs
index 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.md
new file mode 100644
index 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.