Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs(editor): propose staged browser memory curation
Éverton Toffanetto4443021ded11
diff --git a/docs/companion-crates.md b/docs/companion-crates.mdindex 1ffd1dcc..a698f6e5 100644--- a/docs/companion-crates.md+++ b/docs/companion-crates.md@@ -60,8 +60,10 @@ workflow-specific behavior without widening ai-memory's default install.If a companion exposes browser writes, it must implement its own server-sidemutation broker. Browsers should talk to the companion; the companion should talk-to ai-memory with an operator token. That keeps CSRF, confirmation, audit, rate-limits, and UI-specific policy outside the core server.+to ai-memory with a server-held credential bound to the authenticated operator.+That keeps CSRF, confirmation, audit, rate limits, and UI-specific policy outside+the core server. The proposed editor's [browser boundary](#browser-boundary)+details its DB-user-only broker and identity binding.Read-only companions can start ai-memory with `serve --enable-api` to mount`/api/v1` without the browser UI. `--enable-web` still implies the same API.@@ -266,104 +268,178 @@ override is written only into the rendered LaunchAgent plistSee [`docs/macos.md`](macos.md#scenario-d-menu-bar-app).-## `ai-memory-web-editor`: browser chat/editor companion+## `ai-memory-web-editor`: browser curation/editor companion-This is the companion shape for PR #123.+PR #123 motivated this companion shape. This fresh design proposal narrows+it to reviewing and correcting stored memory, with implementation split into+small dependent changes.-Status: **undecided**. Do not implement this companion yet without a fresh design-review. The useful writable version is larger than it first appears: it needs a-safe core compare-and-write seam, a companion mutation broker, browser auth/CSRF,-confirmation state, diffing, conflict handling, audit, and later LLM proposal-policy. It is not clear that this complexity brings enough benefit for-ai-memory's main goal. The system is meant to auto-improve its own memory through-capture, consolidation, review, pending writes, and eval gates; manual memory-editing may be less valuable than it seems, and could distract from improving the-automatic loop.+Status: **undecided**. Maintainer evaluation of this proposal is pending; neither+the editor nor the proposed prerequisites below have upstream design acceptance+by virtue of this document. The existing concern remains: a writable browser+needs auth, concurrency control, confirmation, conflict handling, and audit.+The review should weigh correction of wrong or stale memory against the cost of+maintaining that product alongside the automatic improvement loop.### Goal-Offer a richer browser product for chat, editing, and curation without turning-the built-in `/web` browser into a write-capable application.+Let an operator inspect the source of a claim, draft a correction, compare it+with the stored revision, and deliberately submit it. Capture, consolidation,+pending writes, and eval gates continue to own the automatic loop. Inspection,+drafting, and editing must work without an LLM.-The core built-in browser remains intentionally small: project list, tree view,-markdown rendering, search, and other read-oriented inspection. A separate web-editor can move faster and make stronger product decisions.+The MVP does not execute procedures or introduce chat. Its views use only data+available through current authorized reads; absent evidence stays absent. Core+`/web` and `/api/v1` remain read-oriented. Canonical ADRs stay in their repository:+the editor links to their source/revision instead of creating a second decision+record in memory.### Product shape-Prefer a separate repository with a backend plus frontend, for example:--```text-ai-memory-web-editor/-├── crates/server/ # auth, CSRF, mutation broker, LLM orchestration-├── crates/client/ # UI or generated assets-├── src/ # if kept as a single binary crate initially-└── tests/e2e/-```--The companion can be deployed next to ai-memory and reverse-proxied under a-separate path or host, for example `https://memory.example.com/editor`, while-ai-memory remains at `/api/v1`, `/mcp`, `/admin`, `/hook`, and `/web`.--### How it talks to ai-memory--Read:--- use `/api/v1` for project lists, pages, recent pages, search, graph, briefing,- and overview data;-- use the companion's own LLM provider for chat orchestration if it needs more- than raw page/search context.--Write:--- browser requests go to the companion backend, not directly to ai-memory admin- routes;-- the companion backend performs CSRF checks, user/session policy, rate limiting,- and confirmation state;-- after approval, it calls ai-memory's existing write/delete surfaces with a- server-side token.--Mutation flow:--1. The LLM proposes a patch, create, or delete as a pending action.-2. The UI shows an explicit diff and the target workspace/project/path.-3. The user confirms or rejects the pending action.-4. The companion re-reads the current page and verifies the expected base hash.-5. The companion applies the write/delete through ai-memory's public mutation- path and records its own audit trail.--### Safety requirements--- No auto-applied browser writes from an LLM response.-- Deletes always require explicit confirmation.-- Edits preserve existing metadata unless the user deliberately changes it.-- Folder or search scope is a context limit, not a mutation boundary; the backend- must independently authorize the target page before applying a change.-- If the UI advertises folder-scoped editing, the companion must enforce that- target paths stay inside the allowed folder or project on the server side.-- The companion must not rely on cookie/basic auth to perform non-GET ai-memory- mutations from the browser. Use a server-side token and companion CSRF/session- protection.-- In multi-user mode, `/admin/*` is root-only. A companion must either run with an- operator token or use MCP/tooling flows appropriate to the actor; it must not- assume normal user tokens can admin-write.-- Propagate actor/author context where the public write surface supports it so- admission webhooks and audit stay meaningful.-- Keep `/api/v1` read-only; do not ask core ai-memory to expose writable CORS- browser endpoints for this product.--### Implementation plan--This plan is intentionally parked until the benefit is clearer.--1. Build a read-only editor shell against `/api/v1` first.-2. Add chat over selected page/search context, still read-only.-3. Add pending edit proposals with diff preview, but no apply button.-4. Add confirmed writes through the companion backend and ai-memory public write- endpoints.-5. Add confirmed deletes last.-6. Keep the built-in `/web` UI unchanged unless core ai-memory independently- needs a small read-only API enhancement.+The proposed location is `companions/ai-memory-web-editor`, a standalone Rust+package with its own `[workspace]`, backend, browser assets, and integration/E2E+tests. It is not a root Cargo workspace member. It has its own validation and+release cadence and never opens ai-memory's wiki or SQLite directly.++Public requests should use the proposed minimal client SDK, after it has two+real consumers, relay and importer. The SDK and its capability contract are+prerequisites proposed separately, not shipped editor APIs. An older server or+an unavailable capability must leave the dependent feature disabled; the+capability catalogue never grants access to a user or project.++The companion may run beside ai-memory behind a reverse proxy, but owns a+separate browser origin or explicitly isolated path and cookie namespace. It+does not assume ai-memory's human-auth cookies authenticate the companion; the+core [HTTP authentication classes](ARCHITECTURE.md#http-authentication-classes)+still govern every upstream request.++### Browser boundary++The read-only shell already needs this boundary, before any editing is enabled:++- The companion implements its own login, session expiry/revocation, and CSRF+ protection, including login and later state-changing draft/confirmation+ requests. Session cookies are HttpOnly with appropriate Secure/SameSite and+ path settings; origin checks and session-bound CSRF tokens protect mutations.+- Bind the authenticated browser principal to the same server-authenticated+ ai-memory identity. The broker exclusively holds that operator's own DB-user+ API token server-side. Refuse missing, mismatched, or revoked+ identity/credentials; never fall back to a shared credential. Provisioning and+ secure credential storage are part of the shell's proposed design, not an+ existing core login exchange.+- Root/admin flows and admin proposal views/actions are excluded from this MVP.+ Do not accept or store the shared static root bearer: it cannot identify which+ human made a browser request. A DB-user token attached to a `role=root`+ identity still authenticates as `AuthLevel::User`; it cannot authorize+ `/admin/*`. Any future admin views need a separate design proposal.+- The browser receives neither a machine credential nor an upstream bearer.+ Build upstream requests from allowed fields with only the operator's own+ DB-user token. Never act as an actor proxy or configure/use+ `actor_proxy_bearer_token`. Never fabricate or forward `X-Memory-Actor-*` or+ `X-Memory-Skip-Admission-Chain`, or forward browser-supplied `Authorization`.+ The authenticated DB-user identity supplies real attribution and admission+ context.+- Reads also pass through the broker under the operator's credential. Send+ explicit workspace/project pairs on project-scoped calls, preserve current+ per-project access and ownership rules, and reauthorize each request. Drafts, caches, and+ confirmations are isolated by operator, server, workspace, project, and path.+ Changing account or scope must not expose another coordinate's state. Shared+ pages remain shared; `author_id` must not become a page-read filter.+- Honor projects' `open`/`restricted` modes and `read`/`write` grants (`write`+ includes `read`) from the core [per-project access](users.md#per-project-access)+ contract. An explicit request refused for a target or access level must+ preserve the 403 response, never turn it into an empty result. Search, listings,+ and graph reads retain the core's filtering of inaccessible projects.++These requirements preserve `ScopeResolver`, `AuthLevel::authorize`, Wiki+sanitization/admission/attribution, and the single-writer boundary. The companion+may restrict its own targets further; UI filters never replace authorization.++### Proposed delivery sequence++Every stage below is proposed. A stage's unavailable prerequisites must be+delivered and tested before that feature is enabled; this sequence defines no+new shipped endpoint or wire field.++1. Read-only shell. Requires maintainer design evaluation and the proposed+ client SDK with its two consumers. Deliver the browser boundary above and+ browse the existing `/api/v1` and MCP reads. No wiki mutation is enabled.+ Display explicit access refusals as 403, distinct from missing data.+2. Draft, preview, and diff. Requires the shell and proposed bounded+ retained-version reads. Keep a draft with its base revision, supported+ metadata, and exact target. Render untrusted Markdown safely and show a+ reproducible diff. There is no apply action; drafts never write to the wiki.+ History must expose only eligible retained versions under current per-project access,+ without recovering expired or purged content from Git.+3. Confirmed conditional editing. Requires the proposed core patch and+ compare-and-swap (CAS) seam. Confirmation binds the operator, target,+ base revision, and exact patch/diff; a changed draft needs a new confirmation.+ Preserve omitted metadata, distinguish explicit clears, and disallow editing+ scope or authorship. Deletes remain disabled until the proposed conditional+ delete seam has its own target/diff confirmation and tests.+4. Graph and evidence views. Requires conditional editing and proposed+ directed, bounded graph reads plus portable evidence. Show relation+ direction, source revision, and evidence provenance from authorized data.+ Authorize both ends and every hop; inaccessible nodes/edges cannot leak through+ labels, counts, or expansion. ADR navigation follows the canonical reference.+5. Attempts and procedure views. Requires conditional editing and proposed+ attempt/result/revalidation/procedure contracts. Display incomplete+ or failed attempts, result attribution, applicability, and missing evidence+ explicitly. Narrated success is separate from a checker-verified result.+ Procedure steps remain inspection-only. Split these views further if needed+ to keep each implementation small.++### Confirmation and conflict handling++The proposed revision token must cover the latest version and editable stored+metadata, so a metadata-only change also invalidates confirmation. Core must+compare it in the writer transaction and coordinate disk divergence through the+Wiki lock. A companion read followed by an unconditional write is insufficient;+do not enable apply on servers lacking conditional writes. CAS does not promise+coordination with arbitrary file editors that ignore the process's locking.++On a stale token, retain the draft and its base, fetch the currently authorized+revision, and show the conflict. Reconcile explicitly and obtain a new+confirmation; never retry as an unconditional overwrite. Admission remains in+the normal Wiki path. Display transformed content and refusals according to the+server's authoritative result. Webhook failures/timeouts follow the configured+`failure_policy`: `reject` aborts the write, while `ignore` logs the failure and+continues. Only report committed content after server confirmation. Direct+admission does not create a pending approval; [auto-improvement pending+writes](auto-improvement-loop.md#pending-review-ux) are a separate flow excluded+from this MVP. Preserve drafts on rejection or uncertain delivery, and reconcile+delivery status before retrying. Record operator, scope, base, confirmed diff,+and outcome in the companion audit without retaining secrets.++### Required validation before implementation acceptance++Each implementing change must add adversarial integration/browser tests with a+legitimate control and prove failure with its guard removed. These are required+tests, not coverage claimed by this documentation-only proposal:++- XSS: hostile Markdown/HTML, link schemes, graph labels, and diffs cannot run+ scripts or expose credentials; ordinary content still renders.+- CSRF/session: missing or mismatched tokens, cross-origin requests, and expired+ sessions cannot change drafts or apply edits; a valid same-session request can.+- Two users/two projects: forged actor/skip headers, token identity mismatch,+ root/proxy credentials, account switching, and foreign draft/version IDs fail+ closed. Explicit restricted-project requests with insufficient or revoked+ grants return 403; authorized shared-page reads and operator-attributed writes+ succeed as controls.+- Stale CAS: concurrent body or metadata changes refuse apply and preserve the+ draft/current variant; an explicitly reconfirmed current revision succeeds.+- Admission/recovery: transform, webhook failures/timeouts under both `reject`+ and `ignore`, and interrupted writes keep truthful UI state and attribution.+ Reject-policy failures leave the target unchanged; ignore-policy failures+ allow the normal write. Prove core disk/SQL rollback and recovery, with an+ admitted DB-user write as control. Direct-write tests must not expect pending+ approval.++The companion's standalone workspace needs its own fmt/clippy/tests plus real+broker/browser checks against a temporary server. Implemented boundaries must+be added to the [security inventory](security-boundaries.md) with enforcing code+and guard-off evidence in the same change; proposed seams keep their own core+regressions. Root workspace tests alone cannot validate the companion.## Two kinds of companion: data-seam vs. independent hook consumer