Skip to content

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

Rust

docs(scope): name per_actor as the auto_scope default (#1065)

Felipe Neves Ricardo407543c20382
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ca172515..84f4ef49 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
provider. (#1026)
### Fixed
+- Corrected the `[auto_scope]` default in doc comments (`Config`,
+ `AutoScopeSettings`, the `ActiveProjectMode` module docs, `serve`) and the
+ README docs index: they still named `single` as the default or called
+ `per_actor` opt-in, but the default has been `per_actor` since v1.39. (#1065)
- Fixed watcher reindexing racing with writes and batches to the same page by
sharing their per-page mutex from disk read through SQLite upsert. Both
mutation guards are released before embedding; external editors remain
diff --git a/README.md b/README.md
index a2ec9225..045616fb 100644
--- a/README.md
+++ b/README.md
@@ -477,7 +477,7 @@ diagram, crate breakdown, schema notes, and invariants.
| [`docs/managed-workstreams.md`](docs/managed-workstreams.md) | Optional `ai-memory run` continuity across harnesses: auto harness selection, native resume, argument forwarding, ledger search, privacy, and recovery. |
| [`docs/agent-messaging.md`](docs/agent-messaging.md) | Cross-project agent-to-agent messaging: a directed, claim-once inbox/queue plus the on-start "you have mail" notice. |
| [`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, plus per-repository server profiles. |
-| [`docs/auto-scope.md`](docs/auto-scope.md) | `[auto_scope]` modes for shared servers: default single-slot routing, session-aware isolation, and multi-user `per_actor` behavior. |
+| [`docs/auto-scope.md`](docs/auto-scope.md) | `[auto_scope]` modes for shared servers: the default `per_actor` isolation, session-aware `per_session` isolation, and the pre-v1.39 `single` slot. |
| [`docs/macos.md`](docs/macos.md) | macOS install paths: menu bar app, native release tarball, source build, Docker wrapper, launchd, and current limitations. |
| [`docs/windows.md`](docs/windows.md) | Windows install modes: full WSL2, native Windows with Docker Desktop, prebuilt native release zip, native source builds, and caveats. |
| [`docs/mcp-install.md`](docs/mcp-install.md) | Per-client MCP and lifecycle notes, handoff-injection limits, and community bridge guidance. |
diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rs
index b43f7216..40c98ec6 100644
--- a/crates/ai-memory-cli/src/commands/serve.rs
+++ b/crates/ai-memory-cli/src/commands/serve.rs
@@ -1130,9 +1130,9 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {
// `--project` (issue #2). In stdio mode no hook router is built, so
// this stays empty and the baked-in default is used.
// Construct ActiveProject with the configured `[auto_scope]` mode +
- // TTL/cap. `single` (default) preserves the legacy behaviour; the
- // opt-in modes (`per_session`, `per_actor`) keyed-isolate concurrent
- // sessions / operators on shared installs.
+ // TTL/cap. `per_actor` (default) and `per_session` keyed-isolate
+ // concurrent sessions / operators; `single` preserves the pre-v1.39
+ // process-wide slot.
let active_project = ActiveProject::with_config(
config.auto_scope.mode,
std::time::Duration::from_secs(config.auto_scope.session_ttl_secs),
diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rs
index 71e57798..2c16ca4b 100644
--- a/crates/ai-memory-cli/src/config.rs
+++ b/crates/ai-memory-cli/src/config.rs
@@ -558,10 +558,11 @@ pub struct Config {
/// `AI_MEMORY_AUTH_TOKEN` env var or `[auth].bearer_token` in
/// config.toml.
pub auth: AuthSettings,
- /// `[auto_scope]` — opt-in isolation of the hook-published "current
- /// project" pointer used by MCP tools that omit `workspace`/`project`.
- /// Default `single` mode preserves the legacy global slot; `per_session`
- /// and `per_actor` are for shared installs. See [`AutoScopeSettings`]
+ /// `[auto_scope]` — isolation of the hook-published "current project"
+ /// pointer used by MCP tools that omit `workspace`/`project`. The default
+ /// `per_actor` mode keys it by whatever coordinate the caller has;
+ /// `per_session` keys by `session_id`, and `single` keeps the pre-v1.39
+ /// global slot. See [`AutoScopeSettings`]
/// and [`ai_memory_core::ActiveProjectMode`].
pub auto_scope: AutoScopeSettings,
/// `[routing]` — how mid-session events whose cwd moved are attributed.
@@ -890,9 +891,10 @@ impl std::fmt::Debug for AuthSettings {
}
/// `[auto_scope]` — controls how the hook-published "currently active
-/// project" pointer is shared across concurrent callers. The legacy default
-/// is `single` (process-wide slot, last-write-wins). Opt-in modes isolate
-/// concurrent agent runs and/or operators.
+/// project" pointer is shared across concurrent callers. The default is
+/// `per_actor` (since v1.39), which keys the pointer by whatever coordinate the
+/// caller has; `per_session` keys by `session_id`, and `single` keeps the
+/// pre-v1.39 process-wide slot (last-write-wins).
///
/// Set under `[auto_scope]` in `config.toml` or via the
/// `AI_MEMORY_AUTO_SCOPE__MODE`, `AI_MEMORY_AUTO_SCOPE__SESSION_TTL_SECS`,
@@ -900,7 +902,7 @@ impl std::fmt::Debug for AuthSettings {
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default)]
pub struct AutoScopeSettings {
- /// `single` (default), `per_session`, or `per_actor`. See
+ /// `per_actor` (default), `per_session`, or `single`. See
/// [`ai_memory_core::ActiveProjectMode`] for full semantics.
pub mode: ai_memory_core::ActiveProjectMode,
/// TTL (seconds) for per-key entries in `per_session`/`per_actor`
diff --git a/crates/ai-memory-core/src/active_project.rs b/crates/ai-memory-core/src/active_project.rs
index 927ab48e..c70a7fd9 100644
--- a/crates/ai-memory-core/src/active_project.rs
+++ b/crates/ai-memory-core/src/active_project.rs
@@ -19,13 +19,14 @@
//!
//! ## Isolation modes
//!
-//! The default `Single` mode keeps the historical behaviour — one process-
-//! wide slot, last-write-wins. That is right for a single operator running
+//! The `Single` mode keeps the pre-v1.39 behaviour — one process-wide slot,
+//! last-write-wins. That is right for a single operator running
//! one project at a time, but collapses parallel sessions on shared installs:
//! a hook firing from `~/repo-A` overwrites the slot a concurrent
//! `memory_query` (with no explicit project) in `~/repo-B` was about to read.
//!
-//! Opt-in modes keep a per-key map alongside the single slot:
+//! The `PerActor` (default) and `PerSession` isolation modes keep a per-key
+//! map alongside the single slot:
//!
//! - `PerSession` keys by `session_id` — isolates concurrent agent runs of
//! the same operator (one person with several Claude Code / Codex windows
@@ -479,7 +480,7 @@ impl ActiveProject {
/// hook router after it resolves an event's `cwd` to a real project.
///
/// The actor's identity steers which slot is updated:
- /// - In `Single` mode (the default), the process-wide slot is overwritten.
+ /// - In `Single` mode, the process-wide slot is overwritten.
/// - In `PerSession` / `PerActor`, the entry keyed by the actor is set
/// *and* the single slot is updated as well, so callers that have no
/// actor identity (anonymous probes, legacy code paths) still see the