ai-memory/docs/auto-scope.md

[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 foreground lifecycle hooks: session start, user prompt, and pre-tool events that resolve a cwd to a real project update the pointer so read tools answer for the project the agent is actually in, not the server's static --project default. Completion and shutdown events still land in their resolved project, but do not advance shared fallback slots: a delayed post-tool, stop, or session-end tail from an older process must not redirect a newer session's unscoped reads.

Since v1.39 that pointer is keyed by the caller's own coordinate by default (per_actor), so two harnesses in one project — or two operators on one server — cannot overwrite each other's notion of "current project".

Before v1.39 the default was a single process-wide slot (single). That is right for exactly one harness at a time and collapses as soon as there are two: 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. Because unscoped writes resolve through the same pointer, that could also land a memory_write_page in the wrong project.

The [auto_scope] config block still selects the mode explicitly, including single for anyone who wants the historical slot back.

Modes

mode	Key	When to use
single	(none — global slot)	The pre-v1.39 behaviour. One operator, one harness at a time; last write wins. Opt in only if you want it.
per_session	session_id	Session-aware clients/bridges that forward the hook session id on every MCP request.
per_actor	(qualified identity, session_id), with an identity-only no-session slot	Default. Isolates parallel harnesses and separate operators. Falls back to the shared slot for a caller with no coordinate, and for an install where nothing has ever been keyed (no lifecycle hooks); fails closed on a genuine session mismatch.

Both opt-in modes still publish foreground activity to the single slot in parallel, so a caller with no actor identity (anonymous probe, legacy code path) sees the most recently active project rather than an empty pointer. Non-foreground events refresh only their exact keyed entry when one exists. That preserves legacy behavior without letting a delayed tail take over, but it is not per-session isolation; use explicit workspace + project arguments when a client cannot send actor identity and concurrent runs matter.

Explicit scope arguments fail closed. A project argument is resolved inside the active workspace first, then inside the server's default workspace; if neither contains that project, the tool returns an error instead of falling back to the active/default project. A workspace argument must be paired with project, and read/admin maintenance paths use find-only lookups so typos do not create empty scopes.

Implementation contract

Scope resolution is centralized in ai_memory_store::ScopeResolver and its explicit helpers:

• lookup_existing_scope for read, search, maintenance, retention, embed, and destructive paths. It never creates workspaces or projects.
• create_explicit_scope for explicit write/create paths only.
• resolve_many_existing_scopes for multi-project search scopes, with deduplication and max-scope validation.
• ScopeResolver::resolve_read_args and resolve_write_args for MCP tools that also need actor-scoped active-project fallback.

New MCP, admin, or web API routes should use those helpers instead of hand-rolling find_workspace / find_project chains. PRs that touch scope resolution should include table-driven tests for partial scope rejection, missing explicit scope, active-project precedence, and cross-workspace isolation.

Configuration

[auto_scope]
mode = "per_actor"        # "per_actor" (default since v1.39) | "per_session" | "single"
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:

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 1b trusted proxy)	username or OIDC (issuer, subject) pair
Auth middleware (rung 2 DB user)	user ← users.username
MCP request header X-Memory-Actor-Session-Id	session_id for tool calls
MCP request _meta["ai.opencode/sessionID"] (OpenCode 2)	native lifecycle session_id for tool calls, before transport-ID fallback
MCP request header Mcp-Session-Id	fallback session_id for tool calls
Anonymous / no token	empty actor → single slot

X-Memory-Actor-Session-Id means the agent-run session id from the lifecycle-hook payload. It is not an OIDC/Keycloak login session: the provider's JWT sid claim identifies an IdP browser/device session and must not be used as ai-memory's actor session key.

per_session reads from session_id; per_actor reads from both the qualified identity and session_id. In per_actor, a request that has identity but no session id can use that user's latest no-session slot instead of the process-wide single slot. A request that does carry a session id must match a hook-published keyed entry; if it does not, ai-memory falls back to the server's baked default rather than another session's latest project.

The composite (identity, session_id) key namespaces only these active-project pointers. The durable SessionId stored for hook observations remains global: if another owner reuses an already-owned id, ai-memory drops that hook before it can append observations or publish a pointer for the foreign actor.

Owner and agent are what identify a session; scope is not. The same operator's session legitimately produces events in another project when its cwd moves, so a differing (workspace, project) is recorded rather than rejected — see [routing] mid_session for how those events are attributed. The one exception is a terminal event: a SessionEnd naming a different scope than its session is not that session's end, so it is dropped rather than ending someone else's session — unless it comes from the session's own cwd. Then the scope drifted under the same directory (a .ai-memory.toml appeared mid-session), and the end closes the session in the scope it was recorded in.

The OpenCode 2 adapter reports a native session.moved explicitly, with the directory the session left and a stable ingest key. Its first delivery rebinds the live session row to the new scope and cwd, provided the stored cwd still matches the one it left, so the session's later end and checkpoints land where it now runs; earlier observations keep their scope. A redelivered move never rebinds again.

Client requirements

Lifecycle hooks already include the agent-run session id in their payloads. MCP tool calls are separate HTTP requests, and most built-in MCP client config files can only declare static URL/auth headers. Static configs cannot inject the current agent-run session id into every tool call.

OpenCode 2 (2.0.4+) sends the native session id on every tool call as CallToolRequest.params._meta["ai.opencode/sessionID"], including Code Mode and subagent calls; initialize carries none. Its Mcp-Session-Id is shared by every session in a directory, so the metadata key is what tells concurrent sessions apart. It is a routing coordinate, not authentication, and takes precedence over the transport header. With the generated OpenCode 2 lifecycle adapter, no separate bridge is needed.

Claude Code can opt into ai-memory's session-aware stdio bridge:

ai-memory install-mcp --client claude-code --session-aware --apply

The bridge reads the CLAUDE_CODE_SESSION_ID that Claude supplies to its stdio MCP subprocess and forwards it as X-Memory-Actor-Session-Id while preserving the configured remote endpoint and bearer token. Existing Claude Code installs stay on the static HTTP transport unless this flag is used.

Claude Code's stdio MCP subprocess keeps the id it received at startup across /clear, even though subsequent hooks receive the new id. On --continue/--resume without an explicit id, Claude may also give the MCP subprocess the startup id rather than the resumed id. Restart Claude Code after /clear when exact session-key continuity matters, and prefer --resume <session-id> for explicit resumes. The bridge deliberately fails when no CLAUDE_CODE_SESSION_ID is available instead of silently degrading to the shared single slot.

Use per_session only when your client or bridge can send the same opaque session id from the hook payload on each MCP request as X-Memory-Actor-Session-Id, native MCP metadata as above, or Mcp-Session-Id. Otherwise requests that carry a different MCP session id fail closed to the baked default, while requests with no usable actor identity still degrade to the legacy single slot.

OIDC/Keycloak authentication can identify the human user, client, and agent, but it does not automatically identify the current coding-agent session. If a gateway validates a Keycloak JWT, it should propagate X-Memory-Actor-User or the Issuer + Sub pair, plus optional Client / Agent; it should only emit X-Memory-Actor-Session-Id when a real agent session id has been forwarded by a session-aware bridge.

For built-in installs that use static MCP config, prefer:

• single for one operator / one active project at a time.
• per_actor with multi-user bearer auth when several humans share one server. It isolates users via authenticated actor keys; same-user concurrent sessions still need explicit workspace + project args or a session-aware bridge when the MCP client cannot forward the hook session id.
• per_session plus Claude Code's install-mcp --session-aware bridge when one operator runs concurrent Claude Code sessions in different projects.

Pairing with multi-user mode

per_actor is most useful when the engine is in multi-user mode (see docs/users.md) — each native API credential resolves through api_credentials to its owning users 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 for MCP calls; if their clients also forward session ids, concurrent sessions by the same user are isolated too.

Single-user installs can use per_session alone (no token_pepper, no users row) only when the client/bridge forwards the session id on MCP calls. Claude Code has the opt-in bridge above; with other stock static MCP configs, use explicit workspace + project arguments for concurrent windows.

Surviving a restart

The pointer is process memory: restarting the daemon — which is exactly what the packages tell you to do after an upgrade — empties it, including for sessions that are still open. Until the next foreground hook event lands, every keyed read misses, and an unscoped read used to resolve through the baked default scope and report an empty project through the success path. Nothing in the answer or the log said "scope unresolved", so an agent asking "what do we have here?" was told "nothing" while thousands of observations sat in the DB.

serve therefore seeds a read-side fallback slot at startup from the most recently active project already recorded in SQLite, so a keyed miss right after a restart degrades to real data instead of an empty default. Four bounds keep that narrow:

• Reads only. The seed is a reconstruction, not an observed publish, so it lives in its own slot. An unscoped write still resolves as if nothing were published — it fails closed on a genuine mismatch and otherwise uses the configured default, exactly as before. Nothing in a restart should retarget where a page lands.
• Keyed entries are never reconstructed, so a keyed hit still wins and per-actor isolation is unchanged.
• Bounded by the same TTL as a per-key entry (session_ttl_secs, default one hour). Activity older than that would have aged out of a live pointer, so a server that was down overnight starts with no fallback at all.
• The first foreground hook event supersedes it for every caller, exactly as it overwrites any other shared-slot value. Admin invalidations (purge-project, move-project, workspace removal) reach the seed too, so a scope that no longer exists cannot keep answering from it.

Reads deliberately do not fail closed on an unresolved pointer. A keyed miss is also the normal shape of the pre-publish window (hooks are fire-and-forget, so a session's first read can arrive before its SessionStart write lands) and of TTL/cap eviction on a busy server. Erroring there would turn both into spurious failures; seeding a real fallback fixes the silent answer without touching them.

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.

Upgrading to v1.39

The default changed from single to per_actor. For most installs nothing observable changes:

your setup	before	after
one harness, hooks installed	shared slot	keyed slot for that session — same project
static MCP client (bearer, no session id)	shared slot	that operator's identity-only slot — same project
client that forwards no identity at all	shared slot	shared slot, unchanged
MCP-only install, no lifecycle hooks	shared slot	shared slot — nothing is ever keyed, so the fallback applies
two harnesses / two operators	one slot, last write wins	one slot each

The single behavioural change is deliberate: a client that forwards a session id which does not match any published hook activity no longer inherits the shared slot. Answering it from there is what routed a request into whichever project published last — on a shared server, potentially another operator's. Such a caller now resolves to the server's configured default instead.

To restore the old behaviour exactly:

[auto_scope]
mode = "single"

or AI_MEMORY_AUTO_SCOPE__MODE=single. The effective mode is logged at startup (active-project isolation mode mode=…), which is the quickest way to confirm what a running server is using.