Skip to content

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.md
index 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` across
the unscoped-read and raw-id bypass classes plus the root-only management
surface (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/macOS
tarballs 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.0
git-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 (Grok
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 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 user
completions handoffs purge-session
compact api-key export-okf
message 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.md
index 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 design
pass promised on #708 before any code lands. It changes a security boundary, so
diff --git a/docs/users.md b/docs/users.md
index 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 separate
from 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 owner
bearer / native `aim_` keys / web sessions, and `/admin/*` stays root-only unless a gateway
translates 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 agent
session id; session auto-scope needs the lifecycle-hook session id or explicit
`workspace` + `project` / `scopes`.