Skip to content

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

Rust

docs(scope): retain session-aware project routing

AkitaOnRailsae1eabe7e014
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index a2430990..aef1724a 100644
--- a/docs/design-decisions.md
+++ b/docs/design-decisions.md
@@ -241,7 +241,28 @@ memory in them and does not include a runtime skill router.
Lesson from basic-memory's v0.20 trauma: `(workspace, project, page_path)`. Even if v1 ships single-workspace, the schema and every API/tool param encodes the full 3-tuple. No retrofits.
-Project resolution chain: explicit param → server's default → cwd-based heuristic (match repo root) → error.
+Project resolution uses the shared typed `ScopeResolver`; route families choose
+explicit create or no-create behavior rather than hand-rolling lookup chains.
+Hooks resolve from their event cwd and marker. MCP callers follow one of two
+contracts: a session-aware client that forwards the real lifecycle session id
+on every request may use the per-actor current-project pointer, while a static
+client must pass `workspace` and `project` together. Explicit scope always wins,
+partial scope fails closed, and reads never create a missing scope.
+
+**Retain session-aware automatic routing (#943).** Requiring explicit scope on
+every MCP call and removing the active-project pointer was rejected. It would
+eliminate silent ambiguity for static clients, but those clients are already
+required to send explicit scope; applying the break to genuine session-aware
+clients would discard a core cross-harness convenience and remove the routing
+coordinate used to isolate parallel sessions. The distinction is capability,
+not client brand: automatic routing is permitted only when the client bridges
+the real lifecycle session id into every MCP request. A lifecycle hook without
+that bridge does not qualify. The pointer remains keyed per actor/session and
+is routing data, never authentication; mismatches fail closed instead of
+falling through to another keyed session. Diagnostics and fallback behavior do
+not authorize an unscoped write. Any future schema simplification may improve
+the explicit/static path, but must preserve the session-aware path unless a
+separate major-version decision replaces its UX and concurrency guarantees.
**Install-time `project_strategy` default (#128).** `basename(cwd)` stays the v1 default, but an agent shell that `cd`s into a subdirectory and stays there silently forks the rest of the session into a phantom project named after the subdir. A `.ai-memory.toml` marker with `project_strategy = "repo-root"` fixes this (#16, #23, #111) but needs a marker in (or above) every repo; a runtime env-var fallback that the *user* sets was deliberately rejected in #16. `install-hooks --project-strategy repo-root` instead **bakes** the strategy into the generated hook command (and the OpenCode / OMP / OpenClaw plugins) at install time — the same status as the already-baked `AI_MEMORY_AUTH_TOKEN` / `AI_MEMORY_HOOK_URL` / `--data-dir`, not a user runtime override. This is a client/install-time-only change: the server already parses `project_strategy=repo-root`. A marker's own `project_strategy` / `project` still win, and the default stays `basename` (baking nothing) so existing installs are byte-identical.