Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
Merge release 3.1: adopt runtime opt-ins for sessions and keys
Vinicius Migueld4e4ab6ab3f1
diff --cc CHANGELOG.mdindex 3b3eddc7,4a936f50..befaab95--- a/CHANGELOG.md+++ b/CHANGELOG.md@@@ -12,9 -12,17 +12,20 @@@ version in [`docs/changelog/`](docs/cha## [Unreleased]### Added+- Added an opt-in server-rendered management console for users, sessions, and+ personal MCP API keys, using existing authentication and SQLite storage.+ Required the `management-ui` build feature and runtime switch. (#1231)+ - 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 everyproject from the terminal instead of only the current one. Each hit showsits `workspace/project` in the text output and carries `workspace` anddiff --cc crates/ai-memory-cli/Cargo.tomlindex bced2ca1,bd874a05..68baa113--- a/crates/ai-memory-cli/Cargo.toml+++ b/crates/ai-memory-cli/Cargo.toml@@@ -23,12 -23,6 +23,10 @@@ path = "src/main.rs# a second ~120 MB harness binary for it that contains no tests.test = false+[features]+default = []- management-ui = ["session-management", "self-service-keys", "ai-memory-mcp/management-ui", "ai-memory-web/management-ui"]- session-management = ["ai-memory-mcp/session-management"]- self-service-keys = ["ai-memory-mcp/self-service-keys"]++management-ui = ["ai-memory-mcp/management-ui", "ai-memory-web/management-ui"]+[dependencies]ai-memory-consolidate.workspace = trueai-memory-core.workspace = truediff --cc crates/ai-memory-cli/src/commands/serve.rsindex 744d597a,662c703a..95efed28--- a/crates/ai-memory-cli/src/commands/serve.rs+++ b/crates/ai-memory-cli/src/commands/serve.rs@@@ -1150,19 -1150,7 +1150,18 @@@ pub async fn run(config: &Config, argslet mut shutdown = ShutdownSignals::install();validate_web_ui_args(args.enable_web, args.web_ui_dir.as_deref())?;+ #[cfg(feature = "management-ui")]+ if args.enable_management_ui && !matches!(args.transport, TransportKind::Http) {+ anyhow::bail!("--enable-management-ui requires --transport http");+ }++ #[cfg(feature = "management-ui")]+ if args.enable_management_ui && args.enable_web && normalize_prefix(&args.web_slug) == "/manage"+ {+ anyhow::bail!("the management console reserves /manage; choose a different --web-slug");+ }+refuse_a_missing_token_file(&config.auth)?;- #[cfg(feature = "session-management")]if args.enable_session_management && !matches!(args.transport, TransportKind::Http) {anyhow::bail!("--enable-session-management requires --transport http");}@@@ -1853,15 -1841,7 +1852,11 @@@auth_state.clone(),expire_legacy_cookie_mw,)));- #[cfg(all(- any(feature = "session-management", feature = "self-service-keys"),- not(feature = "management-ui")- ))]- let router = if args.enable_session_management {++ #[cfg(not(feature = "management-ui"))]+ let management_ui_enabled = false;+ #[cfg(feature = "management-ui")]+ let management_ui_enabled = args.enable_management_ui;- #[cfg(feature = "session-management")]+ let router = if args.enable_session_management || management_ui_enabled {router.merge(ai_memory_mcp::session_management::router(ai_memory_mcp::session_management::SessionManagementState {reader: store.reader.clone(),@@@ -1873,8 -1853,7 +1868,7 @@@} else {router};- #[cfg(feature = "self-service-keys")]- let router = if args.enable_self_service_keys {+ let router = if args.enable_self_service_keys || management_ui_enabled {router.merge(ai_memory_mcp::self_service_keys::router(ai_memory_mcp::self_service_keys::SelfServiceKeysState {reader: store.reader.clone(),diff --cc crates/ai-memory-mcp/Cargo.tomlindex 3f36cb83,5ad36d8f..a643f1a2--- a/crates/ai-memory-mcp/Cargo.toml+++ b/crates/ai-memory-mcp/Cargo.toml@@@ -12,12 -12,6 +12,10 @@@ description = "MCP server transport an# statically links the whole dep graph and gets scanned by macOS on# first run.+[features]+default = []- management-ui = ["session-management", "self-service-keys"]- session-management = []- self-service-keys = []++management-ui = []+[dependencies]ai-memory-core.workspace = trueai-memory-consolidate.workspace = truediff --cc crates/ai-memory-mcp/tests/suite/mod.rsindex e39f3359,d6848f9d..0f79fa33--- a/crates/ai-memory-mcp/tests/suite/mod.rs+++ b/crates/ai-memory-mcp/tests/suite/mod.rs@@@ -36,10 -36,11 +36,14 @@@ mod query_pin_firstmod query_reasoning;mod query_superseded;mod read_page_related;+ mod recap_identity;+ mod restore_page_authz;mod retrieval_via_tools;+ mod self_service_keys;+ mod session_management;mod slot_identity;mod stress_autoscope;++#[cfg(feature = "management-ui")]+mod management;mod web_search_parity;diff --cc docs/security-boundaries.mdindex 9e0e2ab5,44e418d6..8dc5b8bd--- a/docs/security-boundaries.md+++ b/docs/security-boundaries.md@@@ -109,13 -112,11 +112,16 @@@ means the boundary is not built yet| 14g | Web project search and its recall trace honour `memory_query`'s scope rules (#708) and never describe another project | `ai-memory-web/src/routes/search.rs` resolves `workspace`+`project` through `resolve_read_scope` (`lookup_existing_scope_guarded`, no-create, `ProjectAccess::Read`) before any ranking, and refuses partial scope; scoped `/api/v1/search` keeps `lookup_project` / `resolve_many_existing_scopes_guarded`; `ai-memory-web/src/recall.rs` ranks only the resolved scopes through `ReaderPool::hybrid_search_scopes`, whose streams and graph expansion are bound to each `(workspace_id, project_id)`; a search with no scope stays `search_pages_with_meta(.., viewer)` (readable repositories only) | `ai-memory-web` `tests/suite/recall_trace.rs` — `project_search_refuses_a_restricted_project_without_a_grant` (bob, with no grant, gets 403 from `/web/search` with and without `explain=1` and from scoped `/api/v1/search`, with no path, body text or trace in the response, and a `scopes` POST naming the restricted project next to an open one is refused; alice's grant and an unrestricted viewer are the controls), `project_search_fails_closed_on_unknown_and_partial_scope` (unknown project or workspace 404 with nothing created, partial scope 400), `explain_renders_stream_ranks_rrf_authority_and_timings` (a better-matching page in a sibling project never reaches the hits or the trace), `search_scope_selector_lists_only_readable_projects` (the search page's "Search in" selector lists only projects the viewer may read, and a hand-typed `scope=` for an ungranted project is a 403 that leaks nothing; controls: the granted reader and an unrestricted viewer; passing no viewer to `list_projects_with_stats` in the handler fails it), `routes.rs` `search_page_scope_selector_round_trips_and_rejects_malformed_values` (a malformed `scope` is a 400); `recall_trace.rs` `kind_filter_does_not_widen_what_a_viewer_can_read` (a `kind`/`tier` filter only narrows: bob gets no hits and a 403 on a scoped search; alice and an unrestricted viewer are the controls), `search_filters_a_project_by_kind_and_tier_keeping_rank_order` (survivors of a filter keep the unfiltered order), `reranker_is_shown_only_the_pages_the_filter_keeps` (a dropped page never reaches the reranker), `kind_and_tier_filters_hold_in_every_stream` (FTS, entity, vector, observation and both graph directions each filter in SQL; dropping any one stream's predicate fails it), `kind_filter_finds_a_rare_kind_the_unfiltered_page_ranks_out` and `cross_project_kind_filter_sees_past_the_candidate_window` (the filter sees past the candidate window in both modes); `ai-memory-mcp` `tests/suite/web_search_parity.rs` (same top-k order as `memory_query` from `/web` and `/api/v1`, with a deterministic embedder and with none, explain on and off, and merged `scopes`; controls show a web search without the embedder, or the old FTS-only scoped search, would fail it) | STRONG. Bite checks: passing no viewer to `resolve_read_scope` in the search handler, to `lookup_project` or to `resolve_scopes` in the API each fails the restricted-project test; dropping the query vector in `recall.rs` fails the embedder parity tests || 15 | Agent-archive restore path confinement, resource bounds, and consistency | `ai-memory-cli/src/commands/restore_agents.rs` stages only bounded regular UTF-8 entries; requires a one-to-one manifest/body/checksum/target mapping; allowlists destinations by scope; rejects symlinked descendants; writes each file atomically and rolls back earlier writes after a later failure. `backup_agents.rs` skips direct and directory-root source symlinks, bounds individual assets, and atomically replaces a private archive only after gzip completion | `backup_agents.rs` `restore_agents_rejects_path_traversal`, `restore_agents_rejects_unauthorized_destination_path`, `restore_agents_verifies_sha256_integrity`, `restore_agents_requires_a_complete_one_to_one_manifest`, `restore_agents_rejects_oversized_entries_from_the_header`, `restore_agents_rejects_a_symlinked_destination_parent`, `backup_agents_does_not_follow_config_or_asset_root_symlinks`, and `failed_backup_leaves_the_previous_archive_intact`; `backup_and_restore_agents_round_trip` is the valid-path control; `restore_agents::tests::rollback_removes_new_files_and_restores_overwrites` covers recovery | STRONG || 16 | Relay queue identity, migration, and private filesystem state | `companions/ai-memory-relay/src/queue.rs` `Queue::open_inner` performs read-only identity preflight, rechecks under `IMMEDIATE`, commits schema and metadata together; `configure` checks the presence of user objects and rechecks `identity`/`schema_version` metadata on the same connection before every bounded BUSY/LOCKED retry; `fsguard.rs` checks existing paths and creates owner-only files before SQLite opens them | `tests/relay.rs` `a_foreign_database_is_refused_byte_for_byte`, `unknown_schemas_refuse_without_mutation`, `a_foreign_database_with_a_writer_is_refused_before_write_coordination`, `a_foreign_identity_after_preflight_is_refused_without_mutation`, `a_foreign_identity_during_journal_retry_is_refused_without_mutation`, `journal_retry_refuses_a_changed_version_or_empty_database_without_mutation`; controls: `journal_transition_retries_sqlite_lock_without_losing_v1_values`, `fresh_queue_init_and_v1_reopens_work_across_processes`; recovery: `interrupted_and_failed_migrations_roll_back_and_recover`, `journal_reclassification_busy_preserves_committed_migration_and_retries_same_queue`; diagnostics: `classification_read_failures_display_the_sqlite_cause_once_and_preserve_foreign_bytes`; Unix privacy: `the_queue_database_and_its_sidecars_are_owner_only` and the contended migration control | Guard-removal proof covers preflight, locked recheck, and journal retry identity/version checks; full table structure is outside this classification. Windows path rejection is preserved; Windows ACL hardening remains operator-owned |-+ | 17 | `ai-memory setup --web` local wizard: only the page this process printed can read the plan or apply a setup | `ai-memory-cli/src/commands/setup_web.rs` `guard` (binds `127.0.0.1` on an OS-picked port; every request needs a `Host` of exactly `127.0.0.1:<port>` or `localhost:<port>` and the one-time 256-bit path secret, compared with `subtle`; a POST also needs this page's `Origin` and the CSRF token the page reads from its own JSON; no CORS grant; `no-store`, `no-referrer`, `DENY` framing, and a CSP with a per-run nonce and no outside sources on the page) and `apply` (agent names must be `--agent` values, de-duplicated, at least one; the child is always `ai-memory setup --yes --agent ...` with the wizard's own flags, never a caller-chosen argument) | `setup_web.rs` `the_page_is_served_only_to_our_host_and_secret` (a rebinding `Host`, a bare `127.0.0.1`, another port, a wrong secret and a missing one refused; controls: `127.0.0.1` and `localhost` with the secret), `apply_refuses_cross_site_and_unknown_input_and_starts_nothing` (no `Origin`, a foreign `Origin`, no CSRF token and a wrong one each refused; `--force`, a shell-like name and an empty choice refused; no child starts), `apply_runs_setup_with_the_picked_agents_and_streams_its_output` (legitimate control: exact argument list); `tests/suite/setup_e2e.rs` `setup_web_serves_the_plan_and_applies_the_picked_agent` (the same through the binary); bite-checked by removing the `Host` check, the `Origin` check, the CSRF check and the agent allowlist one at a time | STRONG |+ | 18 | `uninstall` removes only a service `setup` wrote, including the Windows logon entry | `ai-memory-cli/src/commands/user_service.rs` `planned_removal` / `is_rendered_by_setup` (a unit file whose identity digest still matches) and `planned_removal_for` / `is_setup_run_entry_for` (a `REG_SZ` `HKCU\...\Run\ai-memory` value that is a quoted `ai-memory.exe` ending in `service-host`, with no `&` or `|` chaining, whose `--data-dir`, the first argument after the quoted executable and a whole quoted argument ending at its closing quote, is the data dir being uninstalled, both absolute (`X:\…`, UNC or `\\?\Volume{GUID}\…`; a drive-relative `C:` matches nothing), compared without the verbatim `\\?\` / `\\?\UNC\` prefix, case or trailing separators) before `remove` stops anything or deletes it | `user_service.rs` `uninstall_removes_only_setups_logon_entry` (another install's entry, naming a different `--data-dir`, is left with only the query run; another program's value under the same name is left; absent value is nothing to do; control: this data dir's entry is deleted), `only_the_entry_for_this_data_dir_is_ours` (a temporary data dir does not claim the operator's entry, #1280), `a_volume_guid_data_dir_owns_its_entry` (a volume GUID data dir owns its rendered entry and not another volume's; `uninstall_removes_only_setups_logon_entry` drives both through `remove`), `a_drive_relative_data_dir_is_not_the_drive_root` (`--data-dir "C:"` does not claim `C:\`'s entry; control: the rendered drive-root entry does; `uninstall_removes_only_setups_logon_entry` drives it through `remove` and asserts nothing is stopped or deleted), `a_data_dir_that_runs_past_its_quote_is_not_ours` (`"C:\d"\other` and an escaped closing quote, which Windows reads as other directories, do not claim `C:\d`'s entry; control: the rendered entry does; `uninstall_removes_only_setups_logon_entry` drives the same case through `remove`), `the_data_dir_is_read_after_the_executable` and, on Windows, `a_rendered_entry_belongs_to_its_own_data_dir` (a ` --data-dir ` inside the executable's path neither hides nor fakes the option), `data_dirs_compare_without_prefix_case_or_trailing_separator` (verbatim UNC matches its plain spelling; another share does not), Windows-only `only_a_plain_string_value_is_read` (a `REG_EXPAND_SZ` value under the name is not read as setup's; control: the same data as `REG_SZ` is), `only_setups_entry_shape_counts_as_ours` (unquoted, other program, `serve`, `&`/`|` chaining all refused), and the unit-file identity tests in the same module | STRONG |+ | 19 | Human-session session inspection and owned purging (`serve --enable-session-management`, #1267) | `ai-memory-mcp/src/session_management.rs`: human session and CSRF, completed password change, guarded no-create scope lookup, and an exact-owner preflight before any admission or checkpoint side effect; `ai-memory-store/src/ops.rs` `purge_session_with_owner`: ownership and project write grant rechecked inside the deletion transaction (previews included), cross-project collateral refused unless an Admin purges; `Wiki::purge_owned_session`: wiki mutation lock, admission, pre/post checkpoints, partial-cleanup reporting and replay tombstones | MCP `session_management` suite: `management_refuses_foreign_ids_shared_deletion_and_missing_csrf_with_admin_control` (foreign and shared sessions, anonymous, machine bearer, missing CSRF refused; owner and Admin controls), `management_raw_session_ids_fail_closed_on_wrong_and_partial_scope`, `management_purge_admission_rejection_preserves_rows_and_files`, `management_pagination_reports_its_limit_and_keeps_pages_disjoint`; store `multi_session::owned_session_purge_refuses_foreign_shared_and_wrong_scope_sessions`, `owned_session_purge_refuses_cross_project_cascades_with_admin_control`; wiki `owned_session_purge_authorization_failure_preserves_page_and_index`, `owned_session_purge_cleanup_failure_is_reported_and_tombstoned`. Bite-checked: removing the transaction owner check fails `owned_session_purge_refuses_foreign_shared_and_wrong_scope_sessions`; removing it together with the handler preflight fails `management_refuses_foreign_ids_shared_deletion_and_missing_csrf_with_admin_control` (the two are defence in depth) | STRONG |+ | 20 | Human-session self-service native API keys (`serve --enable-self-service-keys`, #1268) | `ai-memory-mcp/src/self_service_keys.rs`: human session and CSRF (a disabled account's session is refused by `load_session`), completed password change; creation takes the authenticated `UserId`, never a supplied username, trims and bounds `label` (1 to 128 characters) and asks the writer for `create_api_credential_within_limit` (at most 20 active keys per user, counted on the writer thread); revocation answers 404 unless the credential is the caller's own and still active; the token appears only in the one-time create response; issued keys stay `AuthLevel::User` | `self_service_keys_refuse_foreign_ids_csrf_machine_and_pending_password_with_owner_controls` (anonymous, machine bearer, missing CSRF, pending password and foreign-id revoke refused; supplied username ignored; User and Root owner controls), `self_service_keys_refuse_blank_and_overlong_labels` (empty, whitespace, 129 ASCII and 129 multi-byte characters refused with nothing stored; control: 128 characters and a trimmed label accepted), `self_service_keys_cap_active_keys_per_user` (the 21st key refused with 409; controls: another user unaffected, a revoked key frees a slot), `self_service_keys_refuse_a_disabled_user` (list, create and revoke refused; key untouched; control: an enabled user), `self_service_keys_revoking_an_unknown_or_revoked_id_is_not_found` (unknown and already-revoked ids answer 404 without moving the revocation time or touching another user's key). Bite-checked: removing the owner filter fails the foreign-id test; removing the active filter or the key limit fails the revoked-id and cap tests | STRONG |++| 17 | Human-session session inspection and owned purging | `mcp/src/session_management.rs`: human session/CSRF, completed password change, guarded scope lookup, exact ownership; `ops::purge_session_with_owner`: transaction ownership/write-grant checks and collateral refusal; `Wiki::purge_owned_session`: mutation lock, admission/checkpoints, partial cleanup/tombstones. | MCP `session_management` suite (foreign/shared/raw ids, wrong/partial scopes, anonymous/machine/CSRF, admission refusal, owner/Admin controls); store `multi_session::owned_session_purge_*`; wiki `owned_session_purge_authorization_failure_preserves_page_and_index`, `owned_session_purge_cleanup_failure_is_reported_and_tombstoned`. | Adversarial controls and guard-removal proofs. |+| 18 | Human-session self-service native API keys | `mcp/src/self_service_keys.rs`: human session/CSRF and completed password change; creation takes authenticated `UserId`, never a supplied username; revocation verifies immutable owner; existing native keys remain User-level. | `self_service_keys_refuse_foreign_ids_csrf_machine_and_pending_password_with_owner_controls` (anonymous/machine/CSRF/pending-password/foreign-id refusal, supplied username ignored, legitimate User/Root controls). | Adversarial controls and guard-removal proofs. |+| 19 | Server-rendered plain management forms | `web/src/management/forms.rs` refuses cross-origin POSTs before JSON conversion, fixed operations/typed ids delegate to existing human/CSRF/capability handlers; `backend.rs` forwards only peer transport extensions, templates autoescape, responses deny framing/no-store and hash-authorize the static script. | MCP `management_html_plain_forms_preserve_csrf_owner_and_machine_boundaries`, `management_html_login_rejects_cross_origin_forms_and_preserves_session_cookies`; web `management_assets_work_under_a_prefix_and_deny_framing`. Existing API tests retain wrong/partial scope, admission, ownership and recovery controls. | Adversarial refusal with legitimate owner/login controls; guard-removal proofs accompany review. |+## Keeping this current (the standing protocol)1. **Touch a guard, add/extend its adversarial test.** Any change to code in the