Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
Merge PR #1268: feat: add human-session self-service MCP API keys
AkitaOnRails41cffd7b6728
diff --cc .github/workflows/ci.ymlindex 6e665da0,1efb9338..5f25d6f8--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@@ -45,19 -45,19 +45,32 @@@ jobs- uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2- run: cargo clippy --workspace --all-targets -- -D warnings+ session-management:+ name: optional session-management+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1+ - uses: dtolnay/rust-toolchain@4cda84d5c5c54efe2404f9d843567869ab1699d4 # stable+ with:+ components: clippy+ - uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2+ - run: cargo clippy --workspace --all-targets --features ai-memory-cli/session-management -- -D warnings+ - run: cargo test -p ai-memory-mcp --features session-management session_management+ - run: cargo test -p ai-memory-cli --features session-management --lib session_management++ self-service-keys:+ name: optional self-service-keys+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1+ - uses: dtolnay/rust-toolchain@4cda84d5c5c54efe2404f9d843567869ab1699d4 # stable+ with:+ components: clippy+ - uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2+ - run: cargo clippy --workspace --all-targets --features ai-memory-cli/self-service-keys -- -D warnings+ - run: cargo test -p ai-memory-mcp --features self-service-keys self_service_keys+ - run: cargo test -p ai-memory-cli --features self-service-keys --lib self_service_keys+test:name: test (${{ matrix.os }})strategy:diff --cc CHANGELOG.mdindex 10d41fee,95a2aca0..1207d617--- a/CHANGELOG.md+++ b/CHANGELOG.md@@@ -12,9 -12,9 +12,12 @@@ version in [`docs/changelog/`](docs/cha## [Unreleased]### Added+- Added optional human-session session inspection and owned purging, gated by the+ `session-management` build feature and runtime switch. Reused existing human+ authentication, authorization, and SQLite storage. (#1231)+ - Added optional human-session self-service native API keys, gated by the+ `self-service-keys` build feature and runtime switch. Reused existing+ authentication, credential hashing, and SQLite storage. (#1231)- 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 README.mdindex 0c8bc535,8d254b5d..c317fa40--- a/README.md+++ b/README.md@@@ -692,5 -675,5 +692,8 @@@ This codebase is being built collaborat(Anthropic Claude Opus 4.7) following the plan documented in`docs/design-decisions.md`.+The optional [human-session session inspection and owned purging](docs/session-management.md)+uses existing browser authentication and is disabled by default.+++ Optional [self-service MCP API keys](docs/self-service-keys.md) reuse existing+ browser authentication and are disabled by default.diff --cc crates/ai-memory-cli/Cargo.tomlindex db915b84,37c020ac..0613f267--- a/crates/ai-memory-cli/Cargo.toml+++ b/crates/ai-memory-cli/Cargo.toml@@@ -25,7 -25,7 +25,8 @@@ test = fals[features]default = []+session-management = ["ai-memory-mcp/session-management"]+ self-service-keys = ["ai-memory-mcp/self-service-keys"][dependencies]ai-memory-consolidate.workspace = truediff --cc crates/ai-memory-cli/src/cli.rsindex c6fcf1fb,000544f5..8e533755--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@@ -3374,11 -3340,11 +3374,16 @@@ pub enum TransportKind/// Arguments for `serve`.#[derive(Debug, Args)]pub struct ServeArgs {+ /// Enable optional browser-session management API (requires an opt-in build).+ #[cfg(feature = "session-management")]+ #[arg(long, env = "AI_MEMORY_ENABLE_SESSION_MANAGEMENT")]+ pub enable_session_management: bool,++ /// Enable optional browser-session management API (requires an opt-in build).+ #[cfg(feature = "self-service-keys")]+ #[arg(long, env = "AI_MEMORY_ENABLE_SELF_SERVICE_KEYS")]+ pub enable_self_service_keys: bool,+/// Transport to expose the MCP server on.#[arg(long, value_enum, default_value_t = TransportKind::Stdio)]pub transport: TransportKind,@@@ -3511,35 -3477,33 +3516,62 @@@ pub struct WritePageArgs#[cfg(test)]mod tests {+ #[cfg(feature = "session-management")]+ #[test]+ fn session_management_is_runtime_opt_in() {+ let parsed = Cli::try_parse_from(["ai-memory", "serve"]).unwrap();+ let Command::Serve(args) = parsed.command else {+ panic!("serve")+ };+ assert!(!args.enable_session_management);+ let parsed = Cli::try_parse_from([+ "ai-memory",+ "serve",+ "--transport",+ "http",+ "--enable-session-management",+ ])+ .unwrap();+ let Command::Serve(args) = parsed.command else {+ panic!("serve")+ };+ assert!(args.enable_session_management);+ }+ #[cfg(not(feature = "session-management"))]+ #[test]+ fn session_management_flag_is_absent_by_default() {+ assert!(+ Cli::try_parse_from(["ai-memory", "serve", "--enable-session-management"]).is_err()+ );+ }++ #[cfg(feature = "self-service-keys")]+ #[test]+ fn self_service_keys_is_runtime_opt_in() {+ let parsed = Cli::try_parse_from(["ai-memory", "serve"]).unwrap();+ let Command::Serve(args) = parsed.command else {+ panic!("serve")+ };+ assert!(!args.enable_self_service_keys);+ let parsed = Cli::try_parse_from([+ "ai-memory",+ "serve",+ "--transport",+ "http",+ "--enable-self-service-keys",+ ])+ .unwrap();+ let Command::Serve(args) = parsed.command else {+ panic!("serve")+ };+ assert!(args.enable_self_service_keys);+ }+ #[cfg(not(feature = "self-service-keys"))]+ #[test]+ fn self_service_keys_flag_is_absent_by_default() {+ assert!(Cli::try_parse_from(["ai-memory", "serve", "--enable-self-service-keys"]).is_err());+ }+use super::*;use clap::{CommandFactory, Parser};use std::collections::BTreeSet;diff --cc crates/ai-memory-cli/src/commands/serve.rsindex b0e4c251,1ca18ba7..8b28f320--- a/crates/ai-memory-cli/src/commands/serve.rs+++ b/crates/ai-memory-cli/src/commands/serve.rs@@@ -1151,10 -1151,10 +1151,14 @@@ pub async fn run(config: &Config, argsvalidate_web_ui_args(args.enable_web, args.web_ui_dir.as_deref())?;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");+ }+ #[cfg(feature = "self-service-keys")]+ if args.enable_self_service_keys && !matches!(args.transport, TransportKind::Http) {+ anyhow::bail!("--enable-self-service-keys requires --transport http");+ }config.require_llm_fallback_credentials()?;// Merge config + CLI CORS origins (config first, CLI adds new entries).@@@ -1838,19 -1838,24 +1842,37 @@@auth_state.clone(),expire_legacy_cookie_mw,)));+ #[cfg(feature = "session-management")]+ let router = if args.enable_session_management {+ router.merge(ai_memory_mcp::session_management::router(+ ai_memory_mcp::session_management::SessionManagementState {+ reader: store.reader.clone(),+ writer: store.writer.clone(),+ wiki: wiki.clone(),+ },+ auth_state.clone(),+ ))+ } else {+ router+ };+ #[cfg(feature = "self-service-keys")]+ let router = if args.enable_self_service_keys {+ router.merge(ai_memory_mcp::self_service_keys::router(+ ai_memory_mcp::self_service_keys::SelfServiceKeysState {+ reader: store.reader.clone(),+ writer: store.writer.clone(),+ pepper: config+ .auth+ .token_pepper+ .clone()+ .filter(|p| !p.trim().is_empty())+ .map(TokenPepper::new),+ },+ auth_state.clone(),+ ))+ } else {+ router+ };let router = apply_host_layer(router, config.allowed_hosts.clone());// Host the entire surface under the configured base path. Empty// base = root (unchanged). The auth/host layers are alreadydiff --cc crates/ai-memory-mcp/Cargo.tomlindex e38c4b65,aaccd21c..12e84f74--- a/crates/ai-memory-mcp/Cargo.toml+++ b/crates/ai-memory-mcp/Cargo.toml@@@ -14,7 -14,7 +14,8 @@@ description = "MCP server transport an[features]default = []+session-management = []+ self-service-keys = [][dependencies]ai-memory-core.workspace = truediff --cc crates/ai-memory-mcp/src/lib.rsindex a4d3620f,54e87947..5e7f1f6e--- a/crates/ai-memory-mcp/src/lib.rs+++ b/crates/ai-memory-mcp/src/lib.rs@@@ -39,5 -39,5 +39,8 @@@ extern crate self as ai_memory_mcp#[path = "../tests/suite/mod.rs"]mod integration;+#[cfg(feature = "session-management")]+pub mod session_management;+++ #[cfg(feature = "self-service-keys")]+ pub mod self_service_keys;diff --cc crates/ai-memory-mcp/tests/suite/mod.rsindex 267d3394,aac13724..490c997b--- a/crates/ai-memory-mcp/tests/suite/mod.rs+++ b/crates/ai-memory-mcp/tests/suite/mod.rs@@@ -42,5 -41,5 +42,8 @@@ mod slot_identitymod stress_autoscope;mod web_search_parity;+#[cfg(feature = "session-management")]+mod session_management;+++ #[cfg(feature = "self-service-keys")]+ mod self_service_keys;diff --cc docs/security-boundaries.mdindex 96651eb6,14b83e9d..03feba69--- a/docs/security-boundaries.md+++ b/docs/security-boundaries.md@@@ -110,11 -109,10 +110,13 @@@ 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 |+| 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. |+## Keeping this current (the standing protocol)1. **Touch a guard, add/extend its adversarial test.** Any change to code in thediff --cc docs/users.mdindex 8739fc7e,2e3cb1fc..addf5c21--- a/docs/users.md+++ b/docs/users.md@@@ -804,4 -804,4 +804,6 @@@ ones who should keep access; nothing isession id; session auto-scope needs the lifecycle-hook session id or explicit`workspace` + `project` / `scopes`.+See [Human-session session inspection and owned purging](session-management.md) for the opt-in HTTP surface.+++ See [Self-service MCP API keys](self-service-keys.md) for the opt-in HTTP surface.