Skip to content

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.yml
index 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.md
index 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 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 README.md
index 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.toml
index 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 = true
diff --cc crates/ai-memory-cli/src/cli.rs
index 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.rs
index 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, args
validate_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 already
diff --cc crates/ai-memory-mcp/Cargo.toml
index 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 = true
diff --cc crates/ai-memory-mcp/src/lib.rs
index 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.rs
index 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_identity
mod 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.md
index 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 the
diff --cc docs/users.md
index 8739fc7e,2e3cb1fc..addf5c21
--- a/docs/users.md
+++ b/docs/users.md
@@@ -804,4 -804,4 +804,6 @@@ ones who should keep access; nothing i
session 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.