Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: changelog, users guide and design status for #708 slice 3
luisfnicolau9da6f52e3766
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8e1bdf65..d8bcb2db 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -28,6 +28,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0`restricted` yet, this is a pure pass-through; enforcing `restricted` acrossthe unscoped-read and raw-id bypass classes plus the root-only managementsurface (setting `restricted`, issuing grants) follow in a later slice. (#708)+- Per-project authorization is enforced (second slice of #708, completing+ [`design-per-project-authz.md`](docs/design-per-project-authz.md)). A+ `restricted` project admits root, its creator and grant holders; `open`, the+ default and what every existing project stays after upgrading, admits any+ authenticated user exactly as before. Every surface attaches the choke point+ for database users — MCP tools, hook routes and captures, the web UI and+ `/api/v1` — and read-shaped tools that mutate (delete, feedback, sweep, lint,+ auto-improve, handoff accept/cancel, message pop/cancel) need `write`.+ Unscoped reads — search, listings, the graph and the workspace overview —+ leave out projects a user may not read, filtered in the query before+ `LIMIT`; managed-run, workstream and session-id entry points authorize the+ project the id resolves to. A refusal is a 403 naming the project and the+ level needed, never an empty result. Installs with no database users, and+ the root token, are never checked. (#708)+- `projects.created_by` (V69) records the database user whose call created a+ project, and the choke point derives "creator" from it, so a creator keeps+ their project if it is later restricted, without a grant. Projects that+ predate it have no recorded creator. (#708)+- Root-only management of access and grants:+ `ai-memory project access --workspace W --project P --mode open|restricted`+ (`POST /admin/projects/access`) — restricting names the page authors it now+ refuses and grants nobody automatically;+ `ai-memory user grant --user U --workspace W --project P --level read|write`,+ `ai-memory user revoke …`, `ai-memory user grants [--user U]` and+ `ai-memory project grants --workspace W --project P`+ (`POST /admin/users/{username}/grant|revoke`,+ `GET /admin/users/{username}/grants`, `GET /admin/projects/grants`). Every+ grant, level change and revoke is recorded in `audit_log`+ (`grant_access` / `revoke_access`). (#708)+- `[auth] new_projects_restricted` (`AI_MEMORY_AUTH__NEW_PROJECTS_RESTRICTED`),+ default `false`: when set, every project created from then on starts+ `restricted`. The reserved `scratch` project and the global preferences scope+ always start open; the global scope cannot be restricted. (#708)+- Cross-project messages respect access: sending into a restricted project's+ inbox, popping it and cancelling its outbox need `write` on it; listing needs+ `read`. (#708)- Native `ai-memory upgrade` for GitHub-release installs (Linux/macOStarballs and Windows x86_64 zip): downloads the matching release archive,verifies the `.sha256` sidecar, replaces the on-disk binary (and a sibling@@ -161,6 +197,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0git-tracked session page. (#865)### Changed+- A capture into a project its author may not write is dropped server-side+ and counted as `dropped_unauthorized` in status, never stored. The native+ hook client treats a 403 from the server as final and drops the event+ instead of retrying it. (#708)- Grok Build CLI shows a pending handoff, and an opted-in `[briefing]`, as`PostToolUse` `additionalContext` on the first tool of a session.`SessionStart` and `UserPromptSubmit` still do not accept the handoff (Grokdiff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 4daa8bbe..4c2bcfdb 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -285,7 +285,7 @@ separately gated Claude Code assistant/Stop excerpt remains capped at 2 KB.| Table | What ||---|---|-| `workspaces`, `projects` | Top of the 3-tuple identity coordinate. |+| `workspaces`, `projects` | Top of the 3-tuple identity coordinate. `projects.access_mode` (V68; `open` default / `restricted`) decides whether any authenticated user or only root, the creator (`projects.created_by`, V69) and grant holders (`project_grants`, V68) reach it, decided by `ai_memory_store::authorize_project` — `docs/users.md#per-project-access`. || `pages` | Versioned wiki pages with `is_latest` + `supersedes` chain. M8 columns: `last_accessed_at`, `access_count`, and decay-only tombstone marker `superseded_at`. M9 cols: `embedding_provider`, `embedding_model`, `embedding_dim`. V36: `expires_at` (frontmatter TTL). V37: `salience` (NULL = `salience_default`; derived from `page_feedback`). || `pages_fts` | FTS5 virtual table over `(title, body)`, auto-synced by triggers. || `sessions`, `observations` | Sanitized, bounded lifecycle-hook projections. `sessions.ended_observation_count` is the stable generation watermark for resumed-session re-end eligibility; wall clocks are not used for that decision. They are an operational audit trail, not a complete native transcript. |@@ -543,6 +543,7 @@ upgrade auth usercompletions handoffs purge-sessioncompact api-key export-okfmessage doctor backfill+project```Run `ai-memory --help` for the full tree.diff --git a/docs/design-per-project-authz.md b/docs/design-per-project-authz.mdindex d22b14ca..6017d85c 100644--- a/docs/design-per-project-authz.md+++ b/docs/design-per-project-authz.md@@ -1,16 +1,38 @@# Design proposal: per-project authorization for multi-user servers (#708)-**Implementation status.** Slice 2 has landed: the inert V68 schema-(`project_grants` + `projects.access_mode`, default `open`) and the+**Implementation status.** Slices 2 and 3 have landed. Slice 2 is the inert+V68 schema (`project_grants` + `projects.access_mode`, default `open`) and the`authorize_project` choke point (`ai-memory-store/src/project_authz.rs`),-wired into `ScopeResolver` read/write resolution and the writer actor. It is-always-allow (no project is `restricted` yet), so there is no behaviour change.-**Slice 3 is pending** and is what makes `restricted` safe end-to-end: closing-the two bypass classes below (unscoped/global reads filtered before `LIMIT`;-raw-id entry points resolving through `authorize_project`), the root-only-management surface (setting `restricted`, issuing grants), and a-`projects.created_by` source for the creator check. Sections below are the-original design pass, retained as the spec.+wired into `ScopeResolver` read/write resolution and the writer actor. Slice 3+makes `restricted` safe end-to-end:++- **Creator.** V69 adds `projects.created_by`, set when a database user's call+ creates the project; `resolve_project_authz` derives `is_creator` from it.+ Projects that predate V69 have none, and admit only root and grants once+ restricted.+- **Every surface opts in.** MCP tools, `/api/v1`, the web pages, hook routes+ and captures attach `ScopeResolver::with_project_authz` (or its free-function+ form, `authorize_scope_for`) for every database user. Root and installs with+ no database users attach nothing and behave as before.+- **Read-shaped mutations need write.** Tools that take read-shaped arguments+ but mutate (delete, feedback, sweep, lint, auto-improve, handoff accept and+ cancel, message pop and cancel, a message's recipient) resolve at+ `ProjectAccess::Write`.+- **Unscoped reads** — search, listings, the graph and the workspace+ overview — are filtered in SQL before `LIMIT` with the same rule the choke+ point applies; the global preferences scope stays readable by everyone.+- **Raw-id entry points** (managed runs, workstreams, session-scoped+ consolidation) resolve the id to its project and authorize it.+- **Management surface**, root-only: `ai-memory project access`,+ `ai-memory user grant|revoke|grants`, `ai-memory project grants`, and the+ matching `/admin` routes; every change is recorded in `audit_log`.+ `[auth] new_projects_restricted` makes new projects start `restricted`.+- **Captures** into a project the author may not write are dropped and counted+ (`dropped_unauthorized`), never retried.++Per-project administrators remain out of scope: granting, revoking and+restricting are root's alone. Sections below are the original design pass,+retained as the spec.**Original status: proposal for review — not implemented.** This was the designpass promised on #708 before any code lands. It changes a security boundary, sodiff --git a/docs/users.md b/docs/users.mdindex e4244337..728236e2 100644--- a/docs/users.md+++ b/docs/users.md@@ -684,26 +684,64 @@ Without `--as-user`, hooks install the same way they always have —the bearer authenticates, attribution flows from the token's owner(root user or DB user) at write time.+## Per-project access++Authentication says *who* is asking; each project's **access mode** decides+what they may reach (#708):++| Mode | Who reaches the project |+|---|---|+| `open` (default) | Every authenticated user — what every project was before access modes existed. |+| `restricted` | The root operator, the user who created it, and users holding a grant on it. |++Every existing project is `open` after upgrading, so nothing changes until an+operator restricts one:++```sh+ai-memory project access --workspace acme --project checkout-api --mode restricted+ai-memory user grant --user alice --workspace acme --project checkout-api --level write+```++Both are root-only. Restricting prints the users who have written to the+project, hold no grant and did not create it — the people it now refuses — so you can grant the+ones who should keep access; nothing is granted automatically.++- **Grants** are `read` or `write`, per project; `write` includes `read`.+ There is no per-project administrator: granting, revoking and restricting+ are the root operator's, like every other administrative act.+ `ai-memory user grant | revoke` manages them; `ai-memory user grants+ [--user NAME]` and `ai-memory project grants --workspace W --project P` list+ them (REST: `POST /admin/users/{name}/grant|revoke`,+ `GET /admin/users/{name}/grants`, `GET /admin/projects/grants`). A user holds one level+ per project; revoking deletes the grant, and purging a project or deleting+ its workspace takes its grants with it. Every grant, level change and revoke+ is recorded in the audit log (`grant_access` / `revoke_access`, with who did+ it), so "who could reach this, and since when" stays answerable.+- **Cross-project messages** respect access too: delivering into a restricted+ project's inbox needs `write` on it (otherwise the mailbox would be a way+ around its grants), and so do popping its inbox and cancelling its outbox,+ which change its queues. Listing them needs `read`.+- **Whoever creates a project** is recorded as its creator+ (`projects.created_by`) and keeps full access if it is later restricted,+ without holding a grant. Projects created before this existed, or by the+ root token, have no recorded creator.+- **New projects** are `open` unless `[auth] new_projects_restricted = true`+ (`AI_MEMORY_AUTH__NEW_PROJECTS_RESTRICTED=true`), which makes every project created from then on start `restricted`. The+ reserved `scratch` project and the global preferences scope always start+ open, and the global scope can never be restricted: it is shared by+ construction.+- **Gates entry, never rows.** Access decides which projects a user reaches;+ inside a project pages stay shared exactly as before (see below).+- **Refusals are explicit.** A user outside a restricted project gets a 403+ naming it and the level needed, never an empty result; search, listings and the graph leave it+ out rather than hinting at it. A hook capture into a project the user may+ not write is dropped and counted (`dropped_unauthorized` in status), not+ retried.+- **No database users, no checks.** A single-operator install, and the root+ bearer token, are never subject to access modes.+## Limitations-- **Accounts are not a tenancy boundary.** Authentication tells the server- *who* is asking; nothing decides *what* they may read. Every authenticated- user sees every page in every project in **every workspace on the server** —- not just the one they are working in. A server holds many workspaces- (`projects.workspace_id` references `workspaces(id)`), but `users` carries no- workspace, project or repository reference and there is no grant, ACL or- membership table anywhere in the schema, so there is nothing for a read to be- checked against. Two accounts created minutes apart, sharing nothing but the- server, can each read the other's projects in full — including via- `memory_query`, which searches across scopes. All `/admin/*` endpoints are- still root-only in multi-user mode.-- This is working as designed for the single-operator and homelab cases- ai-memory targets today. **If one server would hold work for more than one- team, that is not a supported configuration yet.** Run separate ai-memory- servers (per-user data dirs) behind a reverse proxy instead. Per-project- authorization is tracked in- [#708](https://github.com/akitaonrails/ai-memory/issues/708).- **No per-page RBAC *within* a project.** This one is deliberate and separatefrom the above: pages are shared inside a project because multi-session and@@ -726,8 +764,7 @@ the bearer authenticates, attribution flows from the token's ownerbearer / native `aim_` keys / web sessions, and `/admin/*` stays root-only unless a gatewaytranslates accepted OIDC auth into upstream auth that ai-memory accepts.ai-memory still has one shared wiki per server and no- per-page RBAC — and, per the first bullet above, no per-project- authorization either: an accepted OIDC identity can read every project on- the server. The Keycloak/OIDC `sid` claim is also not an ai-memory agent+ per-page RBAC. Per-project access applies to the database user a gateway+ authenticates as, like any other. The Keycloak/OIDC `sid` claim is also not an ai-memory agentsession id; session auto-scope needs the lifecycle-hook session id or explicit`workspace` + `project` / `scopes`.