Skip to content

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.md
index 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 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
diff --cc crates/ai-memory-cli/Cargo.toml
index 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 = true
ai-memory-core.workspace = true
diff --cc crates/ai-memory-cli/src/commands/serve.rs
index 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, args
let 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.toml
index 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 = true
ai-memory-consolidate.workspace = true
diff --cc crates/ai-memory-mcp/tests/suite/mod.rs
index 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_first
mod 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.md
index 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