Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
Merge main into release/3.1 (3.0.x fix batch)
AkitaOnRailsb3c60fc6ff11
diff --cc CHANGELOG.mdindex b84fa9d2,23f504d7..0368ebf7--- a/CHANGELOG.md+++ b/CHANGELOG.md@@@ -11,117 -11,60 +11,170 @@@ version in [`docs/changelog/`](docs/cha## [Unreleased]+### Added+- Added opt-in session inspection and owned-session purging for signed-in+ browser users, enabled at runtime with `serve --enable-session-management`+ (`AI_MEMORY_ENABLE_SESSION_MANAGEMENT`). A user can purge only a session they+ own in a project they may write; an Admin can purge any. Requested in #1231.+ (#1267)+- Added opt-in self-service `aim_` API keys for signed-in browser users,+ enabled at runtime with `serve --enable-self-service-keys`+ (`AI_MEMORY_ENABLE_SELF_SERVICE_KEYS`). Labels must be 1 to 128 characters+ and a user may hold at most 20 active keys. A self-issued key survives a+ password reset or account disable and must be revoked separately. Requested+ in #1231. (#1268)+- Added `ai-memory search --global`, which searches the wiki pages of every+ project from the terminal instead of only the current one. Each hit shows+ its `workspace/project` in the text output and carries `workspace` and+ `project` fields in `--json`. The flag cannot be combined with+ `--workspace` or `--project`, and a search without it still resolves its+ scope from the current directory. The server side is `GET /admin/search`+ with no `workspace`/`project`: its hits now include `workspace` and+ `project` next to the fields they already had, and the route stays+ root-only on a multi-user server. Global search covers wiki pages only;+ raw observations and a search limited to one workspace are not part of+ this change. (#1253)+- Added kind and tier filters to the web search. The search page in `/web`+ has "Kind" and "Tier" selects, and `/web/search` accepts `kind` and `tier`+ for both a project search and a cross-project one. Every retrieval stream+ applies the filter in its own query, so other kinds cannot crowd out a rare+ one, a filtered search asks the streams for no more candidates than an+ unfiltered one, and the reranker scores only pages the filter keeps. Kind+ and tier both ignore case, a nonstandard kind is flagged on an empty+ result, and "Search all projects" keeps the filters. An unknown `tier` is+ a 400. (#1248)+- Added `ai-memory setup --plan`, which prints the plan and changes nothing,+ and `--plan --json`, which prints it as a JSON document with a `format`+ version for a script or front end to render. The plan now says what each+ detected agent was found by (its session store, its MCP config, or Muse's+ directory), numbers the agents, and lists the other agents `--agent`+ accepts. At the prompt you can type the numbers of the agents to wire+ instead of `y`; a number outside the plan changes nothing. (#1270)+- Added a native Windows path to the two-command install. `install.ps1`,+ published with each release next to its own `.sha256`, checks the release+ zip against that checksum, refuses archive entries that are absolute or+ hold `..`, unpacks it under `%LOCALAPPDATA%\Programs\ai-memory` and adds+ that directory to the user `PATH` (`AI_MEMORY_NO_MODIFY_PATH=1` skips it),+ with no administrator rights. `ai-memory setup` now has a service step on+ Windows: it writes an `ai-memory` value under the per-user `Run` key that+ starts a hidden `ai-memory service-host` at logon, and starts it right away.+ The value is written and read through the registry API, not by running+ `reg.exe`: an unsigned binary running `reg.exe add` on the `Run` key is a+ common persistence signal, and Bitdefender's behavioral engine quarantined+ `ai-memory.exe` for it (#1280). Its paths are written plainly, without the+ `\\?\` prefix a canonical path carries.+ The host runs the server with no console window and restarts it after a+ failure, giving up after five failures within ten seconds of starting.+ `ai-memory uninstall --apply` stops the host and removes the value when it+ still has the shape `setup` writes and names this install's data dir, so an+ uninstall against another data dir (a second install, a test's temporary+ one) leaves the entry alone. (#1271, #1280)+- Added `ai-memory setup --web`, which shows the setup plan as a page in+ your browser and applies the agents you tick there by running `ai-memory+ setup --yes --agent ...` and streaming its output to the page. The page is+ served on `127.0.0.1` behind a one-time address printed in the terminal+ (opened in the browser unless `--no-open` or there is no desktop), refuses+ requests with another `Host`, without the address's secret, or, for a+ change, without the page's own `Origin` and CSRF token, and holds no token.+ It stops on Finish, after 15 minutes without a request, or on Ctrl-C. (#1272)+- Added a desktop installer preview, `companions/ai-memory-desktop`: a Tauri+ app that uses an existing `ai-memory` install or copies its bundled one into+ the same per-user location as `install.sh` and `install.ps1`, then shows the+ `ai-memory setup --web` page in its own window. CI builds unsigned Linux,+ macOS and Windows installers on manual dispatch; they are not attached to+ releases until the project signs them. `setup --web` gained a hidden+ `--stop-on-stdin-eof` flag so the page stops when the app does. (#1273)+- A prompt that starts with `reload context` (for example `reload context+ after last compaction, then …`) now puts the stretch of the session that+ its last compaction dropped back in front of the agent: the prompts typed+ between the latest two compactions, verbatim; the last captured reply (with+ the assistant-capture opt-in); and the project's open handoffs, listed+ without claiming them. The new read-only `GET /recap` route builds it from+ captured observations. Claude Code and Codex receive it with that prompt+ through `UserPromptSubmit` `additionalContext`, OpenCode V1/V2 through the+ plugin's system/context hook, and Grok Build on the next `PostToolUse`.+ Serving the recap writes nothing, so a reload never consumes a baton (#1230).++### Changed+- `ai-memory setup` now ends by naming the agents to restart and the question+ to ask one of them, "What do you remember about this project?", instead of+ a generic restart line. `install.sh` names the link's full path in its+ `next:` line when `~/.local/bin` is not on `PATH`, so the suggested command+ no longer fails with "command not found". The AUR install and upgrade+ messages, and the README Fedora, Arch and macOS app steps, point to+ `ai-memory setup` instead of the manual `init`, `systemctl` and+ `install-*` commands. (#1270)+- Changed how the opt-in session-start brief (`[briefing]+ inject_on_session_start`) spends `max_chars`. Every pinned, `_rules/` and+ `_slots/` page now gets a short excerpt first, taken from its frontmatter+ `abstract:` or `summary:`, or else from the prose it opens with (read on+ into its first list items). The budget left deepens pages to a longer+ excerpt and then the whole body: pinned and `_slots/` pages first, then+ pages a few bytes short of whole, then the cheapest bodies. Before, the+ brief printed whole bodies in order, so one long `_rules/` page was cut with+ a `[truncated by ...]` note and every page after it became an "omitted"+ path. Bodies are no longer cut: a body that does not fit whole shows its+ excerpt. Four or more unpinned excerpts from one folder share a heading,+ and the omitted list and the closing note point at `memory_read_page`.+ Small wikis whose pages fit still get every body whole. A project with many+ standing pages now sees all of them, fewer in full: pin a page, or give it+ an `abstract:`, to control what it shows. The change adds no marker key+ and no migration. (#1264)+### Fixed+ - Fixed the thin-client commands ignoring a custom `bind`, which could write+ into the wrong store. `server_url` defaulted to `http://127.0.0.1:49374`+ and was never derived from `bind`, so `ai-memory --data-dir X status` (and+ `write-page`, `search`, `purge-project`, ...) called the default port+ whatever `bind` said. With nothing listening there the command failed; with+ another server listening there it operated on that server's data, and one+ reporter wrote test pages into their real store this way. When neither+ `config.toml` nor `AI_MEMORY_SERVER_URL` sets `server_url`, it is now+ derived from `bind`: an unspecified address maps to loopback (`0.0.0.0` to+ `127.0.0.1`, `[::]` to `[::1]`) and any other host is used as given,+ hostname included. An explicit value in the file or the environment still+ wins, even when it names the default URL; a `bind` that is not a+ `host:port`, or one on port 0, leaves the default URL alone; and the default+ `bind` resolves to the same URL as before, so an install that never changed+ either key is unaffected. `install-hooks` and `install-mcp` still prefer an+ existing MCP entry's URL, and otherwise write the derived URL instead of the+ default port. (#1269)+ - Fixed a burst of sessions in a directory with no backfill marker launching+ one `backfill --auto` per session. The SessionStart hook now takes an+ atomic in-progress marker before it spawns the backfill, so concurrent+ sessions in that directory start one; the marker is dropped when the worker+ ends and a leftover one stops blocking after 30 minutes. The backfill's+ emptiness check against the server also gives up after 30 seconds instead+ of waiting forever on a saturated server. Keying the trigger on the project+ rather than the directory is not part of this change. (#1287)+ - Fixed `/web/pending` offering Approve and Reject buttons that always failed+ with `401: unknown error` on a server with a bearer token and no password+ sign-in. The browser reaches `/web` there with the root token over HTTP+ Basic, which only admits reads. The page now says so, points to password+ sign-in, and shows each proposal's `ai-memory pending-writes approve` /+ `reject` command instead; a decision that fails for another reason now shows+ the server's message even when it is plain text. (#1288)+ - Fixed the managed routing snippet's claim that Claude Code never reads+ `AGENTS.md`. Claude Code 2.1.277 and later reads it when no `CLAUDE.md`,+ `.claude/CLAUDE.md`, or `CLAUDE.local.md` is present, and reads that file+ instead when one exists. The `@AGENTS.md` import is how a canonical+ `AGENTS.md` reaches sessions that read only `CLAUDE.md`. (#1276)+ - Fixed bundled hook discovery for a binary installed in a standard Unix+ prefix such as Nix: `install-hooks` and `setup-agent` now probe+ `<prefix>/share/ai-memory/hooks/` from `<prefix>/bin/ai-memory`, and+ `setup-agent` checks it before the fixed `/usr/local/share` and+ `/usr/share` locations. (#1275)+ - Fixed `ai-memory install-hooks` and `setup-agent` failing on a second run+ when the staged hook scripts were read-only copies from a read-only package+ store (the Nix store ships them `0444`). Staging now replaces a read-only+ copy instead of erroring. (#1275)+ - Fixed generated hook commands baking an absolute `/nix/store/...` binary+ path that Nix garbage collection later deletes. A binary running from the+ Nix store now renders the bare `ai-memory` command, resolved through `PATH`+ when the hook runs. (#1275)+ - Fixed the NixOS service lacking `git` on `PATH`: the module now adds+ `pkgs.git` to the unit's `path`. The package binary stays unwrapped so the+ live-process guard can still see a running server. (#1275)- Fixed Windows capture dropping the body of file and shell tool eventsthe client had kept. With `[capture] ignore_paths` active, serverre-inspection compiled a POSIX never-match sentinel and treated thediff --cc docs/security-boundaries.mdindex 956d984b,0d876fac..78ee1cb9--- a/docs/security-boundaries.md+++ b/docs/security-boundaries.md@@@ -38,8 -38,7 +38,8 @@@ means the boundary is not built yet| 3d | `GET /admin/metrics` is root-only on a multi-user server and content-free | `ai-memory-mcp/src/admin.rs` mounts `/admin/metrics` inside the operational router under `require_root_for_multiuser_admin` (`AuthLevel::authorize(Capability::Admin, distinguishes_operators)`); `ai-memory-mcp/src/metrics.rs` `render_prometheus` writes only counts and durations under compile-time metric names and the closed label set `result` / `outcome` / `kind` / `le`; `McpMetrics::record_tool_call` takes only a read/write bit (no client name); `ai-memory-core/src/latency.rs` `LatencyHistogram` holds bucket counts and a sum, nothing keyed on a request; scope is never a label | mcp `integration::admin_metrics` `metrics_count_queries_and_hooks_without_leaking_any_content` (secret-shaped strings planted in a `memory_query` query, a `/hook` prompt and the project name never appear in the scrape, nor do the session id, workspace name or root token; every label key is from the closed set; control: the query and hook histograms, the accepted-hook counter and the read tool-call counter move by exactly what was sent), `metrics_are_root_only_on_a_multi_user_server` (production `require_dual_auth` with a real DB-user key: anonymous 401, DB user 403, unknown bearer 401, root control 200); `admin.rs` `multiuser_admin_routes_reject_db_user_tier` / `…reject_anonymous` include the route, `multiuser_operational_admin_routes_allow_root` admits root | STRONG. Bite checks: with the route mounted outside the gate the three refusal tests fail; with the query, the project name or the hook body rendered as a label value the leak test fails on each || 3e | The web health panel is root-only on a multi-user server, read-only and content-free | `ai-memory-web/src/routes/mod.rs` `require_admin` (`AuthLevel::authorize(Capability::Admin, distinguishes_operators)`, shared with `/web/pending`; `html_auth.rs` `AdminRequired` keeps a non-root 403 off the change-password redirect) gates `GET {web_slug}/health`, a GET-only route; `routes/health.rs` renders only counters, timestamps and configured provider/model labels, `provider_line` leaves out `last_error_message` (it can quote a response body), and the process side comes through `health::HealthProbe` as counts (`ServeHealthProbe` in `ai-memory-cli/src/commands/serve.rs` drops the journal's error text); the response is `Cache-Control: private, no-store` | `ai-memory-web` `tests/suite/health.rs` — `health_page_refuses_anonymous_once_operators_are_distinguished` (401, login redirect on navigation, no counters or fix lines), `health_page_refuses_a_db_user_and_admits_root` (403 "Root access required", no redirect, no counters; root control 200), `health_page_follows_the_admin_gate_on_a_single_operator_server` (control), `health_page_carries_no_secret_material` (secret-shaped strings planted in a failed LLM call's and a failed embed's provider error body, a page body, a page title and the project name never appear), `health_page_has_no_write_route` (POST/PUT/DELETE 405), plus a fixture per rendered check (`health_page_renders_each_failing_check_with_its_fix_line`, `health_page_renders_pending_spool_and_journal_checks`, `health_page_reports_a_healthy_server_as_passing`, and `src/health.rs` unit tests for every check id) | STRONG. Bite checks: with the `require_admin` call removed from the handler, the anonymous and DB-user tests fail; with `last_error_message` appended to the provider line, the planted-secret test fails || 3f | The 1.x token-management surface stays removed, and tokens it issued stay ordinary API keys (3.0) | `ai-memory-mcp/src/admin.rs` mounts only `GET /admin/users` on that path and no `/admin/users/{name}/expire`, `/revive` or `/rotate-token` route; `ai-memory-store` migration `V79__drop_legacy_user_token_columns.sql` drops `users.token_hash` / `token_expired_at` and the V55 mirror triggers, with a guard that aborts the migration if the `users` rebuild would lose any resolving reference to a user (credentials, sessions, grants, authors); authentication reads only `api_credentials` (`api_credentials.rs` `find_active_user_by_token_hash`, `revoked_at` and `expires_at` honored) | `admin.rs` `removed_legacy_token_routes_are_gone_for_every_tier` (production `require_dual_auth`; each removed route as root: 405 on `POST /admin/users`, 404 on the rest; as a DB user and as a legacy-token holder: 403 on `POST /admin/users`, 404 on the rest; anonymous 401; afterwards no user was created, no credential revoked, and the legacy token still authenticates), `legacy_user_token_is_managed_as_an_api_key` (an unprefixed legacy token authenticates as a non-root user, an expired one is 401, `api-key list` shows it as `legacy-user-token`, rotate retires the old secret, revoke refuses the new one); `ai-memory-store` `api_credentials.rs` `v79_upgrade_keeps_legacy_tokens_as_api_keys` (a V78 database seeded the 2.x way with active, expired and rotated tokens plus a web session: after V79 the active and rotated tokens authenticate, the expired and superseded ones do not, all three list as `legacy-user-token`, rotate/revoke work, the session survives, no FK violation) and `v79_rolls_back_rather_than_cascade_delete_credentials` (run with foreign keys on, V79 aborts and leaves the V78 schema and the token intact); `ai-memory-cli` `removed_user_token_commands_no_longer_parse` | STRONG. Bite checks: with a stub `POST /admin/users/{name}/expire` route mounted the route test fails; without V79 the upgrade test and the schema pin fail; without the guard the rollback test fails |- | 3g | A Basic browser sign-in on a server without human accounts never persists the root bearer in a cookie | `ai-memory-mcp/src/human_auth.rs` `require_dual_auth` accepts Basic (or an `ai_memory_auth` cookie an older build set) for GET only before human auth exists and sets no cookie on success; the browser resends Basic itself; `expire_legacy_cookie_mw` retires a leftover cookie once human auth is active | `human_auth.rs` `a_basic_sign_in_mints_no_cookie_holding_the_root_bearer` (no `Set-Cookie` carries the token, no `ai_memory_auth` is set; control: the Basic GET is served and the bearer still authenticates; bite-checked against the old cookie minting), `legacy_browser_credentials_stop_when_human_bootstrap_completes` (Basic and a leftover cookie both stop at bootstrap) | STRONG |+ | 3g | A Basic browser sign-in on a server without human accounts never persists the root bearer in a cookie | `ai-memory-mcp/src/human_auth.rs` `require_dual_auth` accepts Basic (or an `ai_memory_auth` cookie an older build set) for GET only before human auth exists and sets no cookie on success; the browser resends Basic itself; `expire_legacy_cookie_mw` retires a leftover cookie once human auth is active; a request admitted this way carries `ai_memory_core::LegacyBrowserAuth`, which `/web/pending` reads to show CLI commands instead of decision buttons that would post and fail | `human_auth.rs` `a_basic_sign_in_mints_no_cookie_holding_the_root_bearer` (no `Set-Cookie` carries the token, no `ai_memory_auth` is set; control: the Basic GET is served and the bearer still authenticates; bite-checked against the old cookie minting), `legacy_browser_credentials_stop_when_human_bootstrap_completes` (Basic and a leftover cookie both stop at bootstrap), `only_a_legacy_browser_credential_is_marked_read_only` (Basic and the leftover cookie are marked, a Basic POST is still 401; control: the root bearer is unmarked and its POST is served; bite-checked by removing the insertion); `ai-memory-web` `pending_page_offers_cli_commands_instead_of_buttons_to_a_basic_browser` (bite-checked) | STRONG |+| 3h | Cross-project `GET /admin/search` (no `workspace`/`project`, the `ai-memory search --global` path, #1253) is root-only on a multi-user server | `ai-memory-mcp/src/admin.rs` `handle_search` runs the no-scope branch through `ReaderPool::search_pages_with_meta` as `OPERATOR` (every project, each hit tagged with its workspace and project); the route sits in the operational router under `require_root_for_multiuser_admin` (`AuthLevel::authorize(Capability::Admin, distinguishes_operators)`), so a DB user or proxy-asserted user never reaches the unfiltered read. A partial scope is still a 400, never a silent global fallback. `ai-memory-cli/src/commands/search.rs` sends no scope only when `--global` is passed, and clap rejects `--global` with `--workspace`/`--project` | MCP `admin_status_search.rs` `global_search_never_reaches_a_non_root_caller` (a restricted project the user holds no grant on, for both a DB-user deployment and a trusted-proxy deployment with no `users` rows: user 403 and anonymous 401 with neither the sentinel path nor the query term in the body; root control 200 with both projects' hits), `global_search_tags_each_hit_with_its_workspace_and_project`, `search_rejects_partial_scope_instead_of_global_fallback`; the shared `admin.rs` all-admin 403/401 route matrix includes `/admin/search`; CLI `cli.rs` `search_global_parses_and_conflicts_with_an_explicit_scope` | STRONG. Bite check: with the gate's operator test forced off (`authorize(Capability::Admin, false)`) the refusal test fails on the DB-user case (200 instead of 403) || 4 | Handoff single-claim / no-steal | `ai-memory-store/src/ops.rs` `accept_handoff_in_transaction` (metadata `state='open'` guard + atomic CAS; the receiver-session check, which requires the receiving session to exist in the claim's own workspace, project and agent kind and refuses with `InvalidState` before the handoff row is touched; an ended receiver is final EXCEPT for the agents where `AgentKind::reuses_session_id_after_end()` holds — Grok and Kimi Code, whose harnesses reuse the native session id across SessionEnd→resume, so accepting reopens `ended_at` only after the claim-once guard) | `multi_session.rs` `a_second_accept_cannot_steal_an_accepted_handoff`; `handoff_ownership.rs` `another_operator_cannot_claim_the_handoff`; `multi_session.rs` `handoff_accept_rejects_foreign_or_missing_receiver_session` (receivers from a sibling project, another workspace, a different agent kind, and a nonexistent session are each refused as `InvalidState` with the handoff left open and every `accepted_*` column NULL; the matching receiver claims it; the same receiver retrying and a second matching session get `false` with the first claim intact; fails with the `project_id` or `agent_kind` predicate, or the missing-session refusal, removed. The `workspace_id` predicate is redundant defence in depth: project ids are globally unique, so the cross-workspace receiver is already caught by `project_id`); `multi_session.rs` `accept_reopens_an_ended_receiver_session_but_keeps_claim_once` (Grok reopen + no-steal) and `accept_reopens_an_ended_kimi_receiver_but_keeps_every_guard` (Kimi Code resume claims and reopens `ended_at`; adversarial controls: an ended claude-code receiver stays refused, a kimi-code receiver in another project stays refused, and the already-claimed guard still refuses the resumed kimi session a second baton) | STRONG || 4b | Handoff owner-scoped recovery (`any_owner` admin gate) | `ai-memory-mcp/src/server.rs` `require_admin_capability` on `memory_handoff_accept`/`_cancel` `any_owner` | `handoff_admission.rs` — cancel gate + **accept gate** (adversarial: non-admin `any_owner` accept refused) | STRONG || 4c | Turn-checkpoint baton is owner+scope-bound | `ai-memory-store/src/ops.rs` `checkpoint_session_handoff` — reads the session's own `(workspace, project, owner_user)` from `sessions WHERE id=?1 AND ended_at IS NULL`, refuses on scope/owner mismatch, refreshes only that session's own `state='open'` baton (id preserved), returns `None` when the session already ended | `ops.rs` `checkpoint_session_handoff_refreshes_only_the_live_sessions_own_baton` (#865) | STRONG |