Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: document per-repository server profiles (#992)
Talysson de Oliveira Cassianocf21fcb351f5
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 689682fd..81d1d970 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -280,6 +280,30 @@handoff ownership, so a forwarded id cannot report another operator's oranother session's claim. The `handoff` field is unchanged. (#988, #920)+- Hook capture can be routed to a different ai-memory server per repository.+ `ai-memory server add|list|remove` registers named server profiles locally,+ in `<data_dir>/servers.toml`, with each token in its own owner-only file+ under `<data_dir>/auth-tokens/`. A repository's `.ai-memory.toml` then+ selects one with `server = "<name>"`. The marker carries only the name,+ never a URL or token. When several profiles are registered, each must+ declare `--root` directories, and a marker outside them cannot select it.+ An unknown, tokenless, out-of-roots or unrooted profile, or a malformed+ `servers.toml`, makes the hook emit nothing, never fall back to the install+ default.+ - Native hooks route the spooled event, the session-start handoff fetch,+ later drains and the one-time boot backfill.+ - Generated TypeScript integrations and the `.sh`/`.ps1` script hooks+ cannot route yet, so they drop a routed repository's events and handoff+ fetch.+ - Clients older than this release ignore the key, so upgrade every client+ before adding `server` to a shared marker.+ - Re-running `server add` keeps a profile's roots when `--root` is omitted,+ and changing its URL without a new token discards the old token.+ - `uninstall` removes the stored profile tokens together with the hook+ token; the registry of URLs stays.+ - `hook --check-capture` reports `server_profile` and `server_resolution`.++ See `docs/marker-file.md`. (#992)### Changed@@ -743,6 +767,11 @@`["full_page", "patch"]`, and normalisation folds `full`, `full-page` and`Full Page` into `full_page` (with a warning) for providers withoutconstrained decoding. Unknown modes still fail validation. (#991)+- The one-time SessionStart backfill now delivers to the server the hook is+ installed against, authenticated with the persisted hook token. Before,+ it resolved the server from the environment and fell back to+ `http://127.0.0.1:49374` when `AI_MEMORY_SERVER_URL` was unset where the+ agent was launched. (#992)- Kimi Code no longer receives a bare `{}` when a `UserPromptSubmit` isdropped by capture policy: the hook now writes an empty success responsediff --git a/README.md b/README.mdindex 350ca410..2ad235f5 100644--- a/README.md+++ b/README.md@@ -406,7 +406,8 @@ your machine can reach it. From there, hardening is incremental: a bearertoken for the LAN, per-user accounts, OIDC device auth for hooks, TLS viaa reverse proxy. Capture is sanitized at a typed privacy boundary beforeanything is stored, and per-repository `[capture]` rules can exclude-paths or invert to allowlist mode.+paths or invert to allowlist mode. A repository can also route its capture+to a different server than the one the hooks were installed against.The full model is in [`docs/security.md`](docs/security.md),[`docs/users.md`](docs/users.md), and@@ -459,7 +460,7 @@ diagram, crate breakdown, schema notes, and invariants.| [`docs/usage.md`](docs/usage.md) | Handoffs, proactive memory queries, slim routing snippet + managed Agent Skills, web UI, raw-wiki inspection, and rules-vs-facts workflow. || [`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. |+| [`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/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. |diff --git a/docs/cookbook.md b/docs/cookbook.mdindex d039e4e7..f7edeb89 100644--- a/docs/cookbook.md+++ b/docs/cookbook.md@@ -191,6 +191,29 @@ ai-memory run --yolo claudeSee [`design-yolo-safety-ai-jail.md`](design-yolo-safety-ai-jail.md) for thefull contract.+## Recipe: send different repositories to different servers++One machine, several organisations, each with its own ai-memory server.+Register each server once under a name, with the directory it is allowed to+serve, then let each repository's marker pick it:++```bash+ai-memory server add team-a --url https://memory-a.example.com --root ~/work/team-a --auth-token-stdin+ai-memory server add team-b --url https://memory-b.example.com --root ~/work/team-b --auth-token-stdin+```++```toml+# ~/work/team-b/.ai-memory.toml+workspace = "team-b"+server = "team-b"+```++Repositories without a `server` key keep using the server `install-hooks`+configured. The marker only ever names a profile; a profile that does not+resolve drops the event rather than sending it anywhere else. Details, the+fail-closed rules, and which integrations support it:+[`marker-file.md`](marker-file.md#routing-capture-to-another-server-server).+## Recipe: run the server on a MacUse the menu bar app when you want one `.app` that starts the server and@@ -229,6 +252,7 @@ ai-memory backfill # import prior local history into an emptyai-memory write-page … # save a durable pageai-memory handoffs # list open handoffs for the projectai-memory message list # cross-project inbox+ai-memory server list # server profiles a marker can route toai-memory export-okf … # export the wiki as an OKF bundleai-memory serve # run the server```diff --git a/docs/install.md b/docs/install.mdindex e8b44596..2362caee 100644--- a/docs/install.md+++ b/docs/install.md@@ -565,6 +565,16 @@ server, and needs a JSON payload naming the directory to test. In the output,Note the trade: recall is lost for every repository you do not mark, and arepository you *intended* to capture stays silent until you add its marker.+**Send different repositories to different servers.** One install can deliver+capture to several ai-memory servers, for example one per organisation. Register+each server once with `ai-memory server add <name> --url <url> --root <dir>+--auth-token-stdin`, then set `server = "<name>"` in each repository's+`.ai-memory.toml`. Repositories without the key keep using the server+`install-hooks` configured. A profile that does not resolve drops the event+instead of falling back. Native hook commands route profiles; the generated+TypeScript integrations and the script hooks drop routed repositories. See+[`marker-file.md`](marker-file.md#routing-capture-to-another-server-server).+Some agent harnesses attach the assistant's final turn to their `Stop` event —Claude Code sends it as a raw `last_assistant_message`. By default that text isnever persisted: the native hook binary strips the raw field before it can reachdiff --git a/docs/marker-file.md b/docs/marker-file.mdindex 8288c92c..aac8cbda 100644--- a/docs/marker-file.md+++ b/docs/marker-file.md@@ -202,6 +202,130 @@ before it ever POSTs. Only the raw script-fallback paths (the`setup-agent` snippets) POST to the server directly without running eitherenforcement point, so allowlist mode does not gate them.+## Routing capture to another server (`server`)++One machine can deliver hook capture to more than one ai-memory server, for+example when each organisation you work for runs its own. Register each server+locally under a name, then let a repository's marker select one:++```bash+ai-memory server add team-a --url https://memory-a.example.com --root ~/work/team-a --auth-token-stdin+ai-memory server add team-b --url https://memory-b.example.com --root ~/work/team-b --auth-token-stdin+ai-memory server list # names, URLs, roots, and whether a token is stored; never the token+```++```toml+# ~/work/team-b/.ai-memory.toml+workspace = "team-b"+server = "team-b" # a profile NAME, never a URL+```++Profiles live in `<data_dir>/servers.toml`; each token is stored separately in+`<data_dir>/auth-tokens/<name>`, owner-only. A marker, a rendered hook config+and a process command line never contain a URL or token for a profile. A+repository without a `server` key keeps using the server `install-hooks`+configured, exactly as before. `ai-memory uninstall` removes the stored+tokens together with the hooks that read them and keeps the registry, so a+later reinstall lists each profile with `token: missing` until you store one+again.++The marker is repository content, so treat it as untrusted: it can only choose+among servers **you** registered. When several profiles exist, each must+declare `--root` directories, and a marker outside a profile's roots cannot+select it. This is what stops a cloned repository naming another team's+profile.++Every failure is fail-closed. If the named profile is unknown, has no token,+is outside its roots, needs roots it does not have, or `servers.toml` is+malformed, the hook emits **nothing** for that event: nothing is spooled, no+handoff is fetched, and a one-line warning goes to the hook's stderr. It never+falls back to the install default, because that would deliver one team's+capture to another team's server.++Routing is inherited down the tree, unlike the other keys. The nearest marker+that declares `server` decides, so a nested marker that only sets `workspace`,+or only `[capture]`, keeps its ancestor's profile. A nested marker can select+a different profile, but only if that profile's roots admit it. Outside+`$HOME` the search does not stop at the checkout root, so an+organisation-level marker above a repository (`/srv/work/team-b/`) still+routes it. Inside `$HOME` it stops at `$HOME`, as for every other key. Note+that allowlist mode keeps its own nearest-marker rule: outside `$HOME`, a+repository whose only marker is that organisation-level one is routed but not+opted in, so under allowlist mode it emits nothing until it has a marker of+its own.++The selection fails closed on shape too:++- An unquoted or empty `server =` is a selection that fails name validation,+ never a silent "no selection".+- A UTF-8 BOM or a stray non-UTF-8 byte cannot hide the key.+- A marker on the way up that cannot be read is refused+ (`rejected-unreadable-marker`), because it may declare a profile.+- An event whose payload carries no `cwd` is routed by the hook process's+ working directory instead of going to the install default.++Re-running `ai-memory server add` for an existing profile keeps its roots when+`--root` is omitted, so rotating a token cannot lift the restriction. Changing+a profile's `--url` without a new token discards the old token first: a token+belongs to the server it was issued for, so the profile refuses events until+you add one for the new URL.++Check the decision for a directory without sending anything:++```bash+echo '{"cwd":"'"$PWD"'"}' | ai-memory hook --event user-prompt-submit --agent claude-code \+ --server-url http://127.0.0.1:49374 --check-capture+```++`server_resolution` is `install-default`, `marker`, or one of+`rejected-unknown-profile`, `rejected-no-token`, `rejected-outside-roots`,+`rejected-roots-required`, `rejected-invalid-profile-name`,+`rejected-unreadable-marker` or `rejected-invalid-registry`. `server_profile`+names the profile; no URL, path or token is printed.++**Supported integrations.** Native `ai-memory hook` commands route profiles,+including the session-start handoff fetch, the spooled events drained later,+and the one-time boot backfill. The generated TypeScript integrations+(`opencode`, `opencode2`, `omp`, `pi`, `openclaw`) do not route yet: a+repository whose marker selects a profile emits nothing from them and fetches+no handoff. The script hooks (the `.sh` and `.ps1` bundles used by the+`AI_MEMORY_HOOK_PLATFORM` override, the Docker host wrapper and `setup-agent`+snippets) cannot route either, and likewise drop a routed repository's events+and handoff fetch. Clients older than this change ignore the key and deliver to+their install default, so upgrade every client before adding `server` to a+shared marker.++**Known limits.**++- **Mixed binaries on one data dir.** Spooled events record their profile in a+ field older binaries do not know. If an older `ai-memory` drains the same+ spool, it treats profile events as install-default ones: it may retry a+ rejected one with the install token, or re-send one addressed to a dead+ loopback port to the server in `config.toml`. Upgrade every install that+ shares a data dir.+- **MCP and `ai-memory run`.** Profiles route hook capture only. The MCP+ server entry and `ai-memory run` (its managed-run ledger and heartbeats)+ still talk to the server they were configured with, so in a routed+ repository they reach the install default. Point that repository's MCP+ client at its own server with a per-repository `.mcp.json`, and avoid+ `ai-memory run` there until it learns profiles.++Profiles use static tokens only. OIDC `auth.json` stays with the install+default and is never presented to a profile's server.++**One server, several identities.** Two profiles may share a URL and differ+only in their token. On a shared server that restricts projects per user+(#708), this lets each repository authenticate as the account that has access+to it:++```bash+ai-memory server add team-a --url https://memory.example.com --root ~/work/team-a --auth-token-stdin # team-a account+ai-memory server add team-b --url https://memory.example.com --root ~/work/team-b --auth-token-stdin # team-b account+```++Events from different profiles never share a request, and each profile's+retries use only its own token.+## Capture exclusionsUse the exact per-repository shape `[capture]` plus `ignore_paths = [...]`@@ -581,13 +705,16 @@ hook events that arrive without a usable one.## What the marker file does NOT do- ❌ No glob patterns. Walk-up by literal ancestry only.-- ❌ No merge of ancestor markers. Closest wins.+- ❌ No merge of ancestor markers. Closest wins. (`server` is the one key+ inherited from the nearest marker that declares it; see above.)- ❌ No automatic migration of `default`-workspace projects.- ❌ No automatic repo-root collapsing. Worktrees and subdirectories onlyshare a project when `project_strategy = "repo-root"` is explicitly set(per marker, or baked install-wide — see above).-- ❌ No user-set env / auth / hook-url override. Use the existing env vars- (`AI_MEMORY_AUTH_TOKEN`, `AI_MEMORY_HOOK_URL`) for those. (A repo-root+- ❌ No URL or token in the marker. `server = "<name>"` selects a server+ profile registered locally with `ai-memory server add`; it cannot introduce a+ new destination or carry a credential. Otherwise use the existing env vars+ (`AI_MEMORY_AUTH_TOKEN`, `AI_MEMORY_HOOK_URL`). (A repo-root*default* can still be baked into an install without a marker via`install-hooks --project-strategy repo-root`, but that is install-timeconfig, not a runtime override the user sets in their shell.)diff --git a/docs/security-boundaries.md b/docs/security-boundaries.mdindex 40e49dd6..a842ed85 100644--- a/docs/security-boundaries.md+++ b/docs/security-boundaries.md@@ -53,6 +53,7 @@ boundary not yet built.| 11a | Hook backpressure (202/429) + bounded fan-out (invariant #5) | `ai-memory-hooks/src/router.rs` semaphore→429, 202 immediately, `MAX_HOOK_BATCH_ITEMS`, bounded LRU limiter | `router.rs` `handle_hook_returns_429_when_ingest_saturated`, `ingest_rate_limiter_is_bounded` | STRONG || 11b | Capture exclusions drop before storage | `ai-memory-hooks` `capture_policy.rs` `inspect`→`Drop` (before semaphore/spawn), including shell commands whose arguments name an ignored path (`match_command`; argv elements matched whole and tokenized); an invalid marker makes file and shell calls metadata-only, and the server admits a metadata-only shell body only under an invalid marker (`router.rs` `metadata_protocol_is_legal`); generated OpenCode/OMP/Pi/OpenClaw integrations mirror it in `render_shared.rs` `ts_capture_policy_v1` (`captureMatchCommand`) | `capture_policy.rs` per-agent `…honors_exclusions` tests, `shell_fixture_vectors` (shared `capture-policy.json` `shell` drop/keep vectors: tool aliases incl. OpenClaw/Devin `exec`, `workdir`, glob directories, Windows paths), `shell_tool_shapes_of_every_adapter_honor_exclusions`, `fixture_vectors` (incl. TS-adapter `bash`/`exec` vectors); `shell_matching_is_off_when_inactive_and_fails_closed_when_invalid_or_over_budget`; `router.rs` `capture_protocol_shell_decisions_survive_server_reinspection`, `capture_protocol_invalid_marker_shell_is_metadata_only` (active metadata-only shell refused, older client's invalid-marker keep stripped, commandless control kept), `capture_protocol_unparseable_marker_strips_shell_events` (server fallback for an unparseable marker), `capture_protocol_invalid_shell_metadata_claim_must_be_canonical` (a stripped shell claim with a path count or non-`extracted` state is refused); `capture_policy.rs` `invalid_marker_strips_shell_calls_with_unparseable_commands`, `long_bash_lc_script_in_argv_is_not_dropped_by_the_match_budget`; `hook.rs` `shell_command_reading_an_ignored_path_is_dropped_before_spool`; `render_shared.rs` `generated_capture_policy_v1_node_runtime_evidence` (runs the same fixture sections against the emitted TypeScript; `#[ignore]` locally, run with `--ignored` under Node 24 by the Linux CI test job) | STRONG || 11c | Capture hook ≤200ms budget (invariant #5) | `hooks/_lib.sh` capture path `curl --max-time 0.2` (context-fetch 1.0s and background drain 2.0s are separate, larger-budget paths) | none (shell-script timeout; hard to unit-test) — watch on any capture-path change | WATCH |+| 11d | Hook server-profile routing: a marker-selected server gets only its own capture and its own token (#992) | `ai-memory-cli/src/server_profiles.rs` `resolve` (validated `ProfileName`, strict `servers.toml` parse, `roots` required once two profiles exist, component-wise root match) and `marker.rs` `find_server_selection` (inherited down the tree, any value shape counts); `commands/hook.rs` `resolve_hook_route` drops a `Rejected` route before spool, handoff and backfill, and hands the drainer no live token for a profile route; `commands/hook_spool.rs` `static_retry_token` (a profile entry retries only with its own stored token), the loopback reroot skip, and chunk splitting on `profile`; generated TS `captureServerRouted` drops a routed repository and gates `fetchHandoff`; `hooks/_lib.sh` `ai_memory_server_routed` (flag refused by `ai_memory_post_hook`/`ai_memory_get_handoff`) and `hooks/lib/ai-memory-hook.ps1` `Test-AiMemoryServerRouted` drop it in the script hooks | `hook.rs` `each_repository_spools_to_its_own_profile_with_its_own_token`, `a_selection_that_does_not_resolve_emits_nothing` (unknown / tokenless / outside roots / roots required / invalid name, plus a resolving control), `session_start_handoff_comes_from_the_profile_server_only`, `a_repository_without_a_server_key_keeps_the_install_default`; `hook_spool.rs` `a_profile_entry_is_never_retried_with_the_install_live_token` (server B accepts exactly the install's live token and must still not get it), `a_profile_entry_recovers_with_its_own_rotated_token` (control), `a_profile_entry_on_a_dead_loopback_port_is_not_rerouted_to_the_default`, `profile_and_default_entries_at_one_address_ride_separate_batches`; `server_profiles.rs` roots/registry/name tests; `marker.rs` `nested_markers_without_server_inherit_the_ancestor_selection`; `install_hooks.rs` `generated_integrations_fail_closed_on_a_server_profile_marker`, `openclaw_plugin.rs` `openclaw_plugin_fails_closed_on_a_server_profile_marker`, and the `server-routed-*` checks in `generated_capture_policy_v1_node_runtime_evidence`; `hook.rs` `an_event_without_a_payload_cwd_routes_by_the_process_cwd`, `a_refused_route_prints_nothing_for_kimi_user_prompts`; `hook_spool.rs` `a_profile_entry_is_not_retried_with_a_token_issued_for_a_new_url`; `server_profiles.rs` `changing_the_url_without_a_token_discards_the_old_token`, `omitted_roots_keep_the_registered_ones`; `marker.rs` `outside_home_the_walk_reaches_a_marker_above_the_checkout_root`, `encoding_noise_cannot_hide_a_server_key`, `an_unreadable_marker_is_a_refused_selection`; `backfill.rs` `a_spawned_backfill_authenticates_like_the_hook_that_spawned_it`; `tests/hooks/test_lib.sh` "server profiles (#992)" section; `hook.rs` `a_mixed_spool_drains_each_event_only_to_its_own_server` (two token-gated servers, one spool, one drain: each server receives exactly its own event with exactly its own bearer); `tests/suite/server_profiles.rs` (the built binary: `server add` → `hook` spools to the profile with its token, unknown profile spools nothing, `uninstall` removes the tokens; `two_real_servers_each_receive_only_their_own_repository` runs two real `ai-memory serve` children with different root tokens and checks on each server which repository landed there); `ai-memory-hooks` `powershell_server_routed.rs` `server_routed_guard_mirrors_the_native_walk` (runs `Test-AiMemoryServerRouted` under real PowerShell: inherited, BOM, look-alike keys, the `$HOME` boundary with its control, past a checkout root outside home, current directory) | STRONG for native hooks, generated TS, `.sh` and `.ps1` hooks. Known gap: an older binary draining a shared spool ignores `profile` || 12 | Network/auth posture | `config.rs` loopback `DEFAULT_BIND`; `serve.rs` `validate_http_exposure`, `require_allowed_host`; `auth.rs` `require_bearer` | `serve.rs` host-guard (missing→400 / forged→403), non-loopback-requires-token; `auth.rs` wrong-token 401 | STRONG || 13 | Managed-run transcript attribution (concurrent launches in one checkout, invariant #16) | `ai-memory-store/src/workstream.rs` `link_native_session` stamps `native_session_linked_at` on its own run only, both `finish` updates drop the stamp when the session changes, `run_status` reports it; `ai-memory-cli/src/commands/run.rs` `resolve_native_session_after_run` takes a linked session only when `ai-memory-workstream` `native_session_in_checkout` holds it for this checkout (OpenCode by recorded directory), never falls back to a link it set aside, and turns an `AmbiguousNativeSession` into a warning with nothing imported; `ai-memory-workstream/src/transcript.rs` `discover_crush` claims only the one top-level session created (or, with `--continue`, touched) during the run, and in a data directory outside the project only one that edited a file in it | `multi_session.rs` `a_session_linked_by_one_managed_run_is_not_another_runs`; `run.rs` `a_session_linked_during_the_run_wins_over_discovery` (concurrent newer session, another checkout's link refused, no fallback to it, unlinked control); `transcript.rs` `native_session_in_checkout_checks_the_opencode_directory`; `store/src/lib.rs` `managed_run_status_reports_a_link_made_during_the_run`; `run.rs` `ambiguous_crush_discovery_keeps_the_run`; `transcript.rs` `crush_discovery_claims_only_the_session_the_run_created`, `crush_discovery_in_a_shared_store_claims_only_an_edit_here` | PARTIAL: a run whose child links nothing still falls back to discovering the newest session in the checkout; Crush, which has no hooks, relies on that discovery alone and claims nothing when it is ambiguous || 14 | Per-project authorization (#708) | `ai-memory-store/src/project_authz.rs` `authorize_project` / `ProjectAuthz::authorize` choke point (V68 `project_grants` + `projects.access_mode`, default `open`; V69 `projects.created_by` feeds `is_creator`); `scope.rs` `ScopeResolver::with_project_authz` (reader pool for reads, writer actor for writes) and its free forms `authorize_scope_for` / `*_guarded`, attached for every DB user by `ai-memory-mcp` `scope_resolver_as`, `ai-memory-web` `authorize_read` / `lookup_project`, and `ai-memory-hooks` (`grants.rs` `authorize_resolved` for run/workstream ids, the capture check in `router.rs`); read-shaped mutations resolve at `ProjectAccess::Write` (`resolve_existing_args(.., need)`); unscoped reads filtered before `LIMIT` by `reader.rs` `readable_repository_sql`; `WriterHandle::authorize_project` as defense in depth. Page ids are never taken from a caller (only derived from already-authorized hits), so there is no page-id entry point to guard | `tests/suite/project_authz.rs` (decision matrix, ship-inert, resolver gate); `tests/suite/access_mode.rs` `every_caller_against_both_modes`, `a_restricted_project_admits_the_team_and_refuses_the_outsider`, `new_projects_follow_the_server_default_and_admit_their_creator`; `scope.rs` `the_argument_shape_does_not_decide_the_level`, `a_user_reaches_only_what_they_were_granted`, `creating_authorizes_against_a_project_that_already_exists`, `a_refused_scope_fails_the_search_instead_of_shortening_it`; `grants.rs` `search_finds_only_what_the_viewer_may_read`, `the_limit_counts_only_what_the_viewer_may_see`, `the_workspace_handoff_comes_only_from_readable_repositories`; `ai-memory-mcp` `server.rs` `a_reader_may_read_everything_and_change_nothing`, `bob_cannot_read_alices_page_in_a_restricted_project`, `bob_cannot_find_alices_page_by_searching_in_a_restricted_project`, `bob_cannot_consolidate_a_session_in_alices_repository`, `a_restricted_projects_queues_need_write`; `ai-memory-hooks` `a_capture_needs_writer_on_the_repository_it_lands_in`, `session_start_delivers_nothing_from_a_repository_the_viewer_cannot_read`, `run_and_workstream_ids_only_answer_someone_who_may_reach_the_repository`; `ai-memory-web` `web_reads_honour_grants_in_a_restricted_project`, `metadata_shows_only_what_the_viewer_may_read` — each with a granted or open-project control, and proven to fail with the choke point (18 tests) or the SQL filter (9 tests) neutralized | STRONG — slice 3 closed both bypass classes (unscoped reads, raw-id entry points) and added the root-only management surface. Out of scope by design: per-project administrators (granting/restricting is root-only), and access modes, creators and grants live only in SQLite, so `reindex` resets them |diff --git a/docs/security.md b/docs/security.mdindex 51d4e0cd..a5ef3434 100644--- a/docs/security.md+++ b/docs/security.md@@ -35,6 +35,15 @@ ai-memory install-hooks --agent claude-code --apply \--server-url "http://<server-ip>:49374" --auth-token "$TOKEN"```+When users must not see each other's projects at all, run separate servers.+One machine can still capture for several of them: register each server as+a named profile with `ai-memory server add` and let each repository's+`.ai-memory.toml` select one with `server = "<name>"`. The marker never holds+a URL or token, a profile can be restricted to the directories it serves, and+a selection that does not resolve drops the event instead of sending it to+another server. See+[`marker-file.md`](marker-file.md#routing-capture-to-another-server-server).+Bearer auth protects `/mcp`, `/hook`, `/handoff`, `/workstream/*`, andmachine calls to `/admin/*` and `/api/v1/*`. Humans sign in at`POST /auth/login`; the console uses an `HttpOnly` session cookie plus CSRF,