Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Optional companion crates and projects
This page records the boundary for feature ideas that are useful around ai-memory, but should not become core ai-memory surface area. PR #118 and PR #123 are the historical motivation: both are valid product ideas, but both patch too much import, chat, UI, and mutation behavior into the core server. The better shape is optional companion software that orchestrates ai-memory through public APIs.
ai-memory stays a memory substrate:
- one server binary owns hooks, MCP, the markdown wiki, SQLite indexes, auth, admission webhooks, and the built-in read-only browser;
- the wiki remains markdown-in-git as source of truth;
- SQLite remains a derived index;
- writes go through the existing wiki mutation path, admin endpoints, or MCP tools;
- the built-in
/weband/api/v1surfaces stay read-oriented.
Companion crates can be richer products. They should integrate through public HTTP/MCP surfaces instead of patching handlers, routes, or command surfaces into the core workspace.
Integration rules for companions
Orchestrators that own their harness lifecycle can use the external capture contract to suppress native observation capture per execution while retaining handoff delivery and MCP retrieval. Producer provenance and retry identity use the existing hook ingestion fields.
Companion projects may:
- call the read-only
/api/v1endpoints for workspaces, projects, pages, search, graph, recent pages, and briefing/overview snapshots; - call existing MCP tools such as
memory_write_page,memory_delete_page,memory_read_page, andmemory_querywhen running as an agent/client; - call existing admin endpoints such as
/admin/write-pageand/admin/delete-pagewhen running as an operator-side server process with an appropriate bearer token; - use
--web-ui-dirto let ai-memory serve an alternate static SPA, as long as the SPA still uses public HTTP APIs and does not require in-process plugins; - run their own LLM prompts, import transforms, queues, confirmation flows, UI state, and project-specific policies;
- ship their own CLI binary, web server, Docker image, tests, release cadence, and docs.
Companion projects should not:
- become Cargo workspace members of core ai-memory by default;
- add core MCP tools, admin endpoints, or CLI subcommands unless a missing seam is independently useful to ai-memory itself;
- write wiki files or SQLite rows directly;
- bypass
AuthLevel::authorize, admission webhooks, actor attribution, scope resolution, or the single-writer store boundary; - require ai-memory to host arbitrary plugin code in-process.
Companion features are separate products. They can move faster than core, have their own UX, and carry source-specific or workflow-specific behavior without widening ai-memory's default install.
If a companion exposes browser writes, it must implement its own server-side mutation 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.
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.
Both modes use the normal machine Bearer or browser-session auth boundary;
writes continue through MCP or authenticated admin routes.
Team-wiki sync (#986)
A repository-backed team-wiki sync is accepted as a companion shape, not as a
repo-local storage mode in the core server. A contribution should preserve the
prototype's three-way comparison and clone-local state, sync only explicitly
allowed shared page families, default destructive changes to dry-run, report
divergent edits without choosing a winner, and perform every import through
the public MCP write/delete tools. It must never open the wiki directory or
SQLite directly. The core read seam is /api/v1 in API-only mode; the supported
MCP page arguments are documented in programmatic memory.
All five slices of #986 have shipped. Slice 1 (read-only export) came first,
in 2.x. Slice 2 (the compare-and-write seam in core), slice 3 (two-way sync
through the MCP write tool), slice 4 (conditional writes and opt-in deletes)
and slice 5 (the CI check and post-merge hook) ship in 3.0. The companion is
ai-memory-wikisync
below.
ai-memory-client: shared private capture privacy
ai-memory-client supplies four privacy
functions consumed by both the relay and external-conversation importer. New
bodies are scrubbed before serialization, hashes and local persistence; native
identities containing credentials are refused without being renamed. A relay
item queued before these checks that fails them is never sent: it is dropped
locally with a dropped_policy receipt, so its session keeps flowing. The package has its own workspace and focused tests, with no
server dependency. Server authorization and capture exclusions remain the
authoritative boundaries.
ai-memory-relay: external lifecycle delivery
ai-memory-relay delivers events collected by
an external orchestrator through /hook/batch. Its own local queue records events
before sending and retains unacknowledged entries for a later flush. It does not
launch agents, claim handoffs, or open ai-memory's database or wiki.
The orchestrator still maps its events to the native harness payloads and sets
AI_MEMORY_CAPTURE_OWNER when launching that harness. The relay uses the native
session identity and derives retry keys from the producer's stable event IDs.
Only the first pending event for each session enters a batch; that session
advances after acknowledgement, even when other sessions are rate-limited.
The package has its own workspace, tests and CLI. Its README defines queue limits, local data handling and recovery, with an executable test against the real ai-memory server. Root workspace tests do not run the companion's unit tests.
ai-memory-importer: migration and ingestion companion
This is the companion shape for PR #118. The first implemented companion lives
at companions/ai-memory-importer as a
standalone Cargo package with its own [workspace]; it is not a member of the
root workspace and is not covered by root cargo test --workspace.
Goal
Import or normalize existing memory corpora without making ai-memory core own every source format and migration workflow.
Initial source support is intentionally narrow:
- oh-my-claudecode / OMC flat markdown wiki directories.
- generic external-conversation JSON envelopes (
project,source,session_id, and boundedrole/contentmessages), replayed through the public ordered hook-batch surface. Product-specific export adapters remain outside this repository. - agentmemory exports: its Obsidian vault (
agentmemory-vault) and itsExportDataJSON file (agentmemory-export, with a required project mapping file). Both write through MCPmemory_write_pagewith explicit scope, every write conditional (create_only, thenexpected_page_idper later version), refuse servers older than 3.0, and land underimported/agentmemory/, outside every reserved family. Each page version carries a stable UUIDv5 ingest key; a rerun skips an existing version only when its complete body matches the sanitized plan. A destination body edit retaining the key stops resumption before another version replaces it. Observations are dropped unless replayed asexternal-importsessions through/hook/batch; records with no ai-memory counterpart are counted in the manifest. Details are in the importer README. - one explicitly selected local text/Markdown, text-layer PDF, DOCX, PPTX,
XLSX, VTT, or SRT document (
document, Unix-only). Extraction is bounded and sanitized, pages carry source digest and extractor provenance, and writes use MCPcreate_onlyso reruns are idempotent and conflicts never overwrite another page. OCR, images, and raw audio/video stay outside the companion.
Future sources can include:
- Claude Code memory graph exports such as
memory.jsonlfrom@modelcontextprotocol/server-memory; - Qdrant-backed memory collections, when a user supplies a collection URL and schema mapping;
- future one-off importers maintained on the companion's release cadence.
Validation
Run companion checks explicitly from the repository root:
cargo fmt --check --manifest-path companions/ai-memory-importer/Cargo.toml
cargo test --manifest-path companions/ai-memory-importer/Cargo.toml
cargo clippy --manifest-path companions/ai-memory-importer/Cargo.toml --all-targets -- -D warnings
Root hygiene checks remain separate:
cargo fmt --check
git diff --check
Product shape
Prefer a separate repository and binary crate, for example:
companions/ai-memory-importer/
├── Cargo.toml
├── src/main.rs
└── README.md
It can share Rust libraries later only if those libraries are published with a stable API and are useful outside ai-memory. It should not need to be a member of this workspace.
How it talks to ai-memory
Read and plan:
- use
/api/v1/workspaces,/api/v1/projects,/api/v1/pages,/api/v1/search, and/api/v1/graphto inspect the destination; - default to dry-run, printing planned page writes without mutating ai-memory.
Write:
- write imported or normalized pages through
/admin/write-pageor MCPmemory_write_page; - do not delete in v1;
- use
memory_query/memory_read_pageor/api/v1/search/ page reads for duplicate detection and context checks; - optionally call
memory_consolidateormemory_auto_improveafter import for post-import refinement, rather than building that refinement into core; - for bulk operations, loop over the public single-page operation unless ai-memory later adds a generic bulk-mutation seam for its own reasons.
Re-home by kind:
- compute the move/link-rewrite plan in the companion;
- apply moves as normal writes to the new path plus deletes of the old path;
- preserve frontmatter that ai-memory returns through page reads;
- fail closed on collisions, missing pages, or changed source hashes.
Safety requirements
- Never open ai-memory's SQLite database or wiki directory directly.
- Require an explicit destination workspace/project.
- Preserve only metadata supported by the public write surface (
title,kind,tier,tags,pinned, body, and the boundedentities,abstract, andrelationsdocumented in usage). The current importer preserves the original title/kind/tier/tags/pin subset; broader metadata needs an explicit importer consumer. Do not claim arbitrary frontmatter or author preservation in companion imports. Writes replace the whole page; omitted metadata is cleared. - Carry idempotency keys or source fingerprints in companion-side state so failed imports can be resumed safely.
- Validate and sanitize a complete external-conversation envelope before the
first HTTP request; use a stable imported session identity and per-event
idempotency keys, and send the dedicated
external-importwire identity rather than impersonating a live coding harness. - Surface all destructive actions in dry-run output before live mode.
- Treat non-overwrite checks on
/admin/write-pageas best-effort: the OMC route re-checks before each write but cannot make that endpoint atomic with the read. The agentmemory routes use the conditional MCP write seam that shipped in 3.0 instead, so the server refuses a page that appeared or changed. - Keep LLM normalization optional; deterministic import should work with no LLM.
- Keep provider-specific performance tweaks, such as model parameter changes, out of importer PRs. If ai-memory core needs a provider bugfix or optimization, land it as a small standalone core change.
Implementation plan
- Build a read-only planner for one source format and snapshot fixtures.
- Add dry-run output and collision detection.
- Add live writes through existing ai-memory public write/delete surfaces.
- Add optional LLM normalization as a companion-side pass.
- Add re-home/link-rewrite as a separate subcommand after import is stable.
- Only after repeated usage, consider whether ai-memory core lacks a small, generic API seam; do not start by patching core endpoints.
ai-memory-wikisync: team-wiki export and sync
Slices 1, 3, 4 and 5 of the accepted team-wiki sync
shape, implemented at companions/ai-memory-wikisync
as a standalone Cargo package with its own [workspace] (mirroring the
importer): it is not a member of the root workspace and is not covered by
root cargo test --workspace.
Goal
Mirror a team's shared ai-memory pages into a project repository as reviewable markdown, so the wiki a team actually maintains can travel with the code it documents, and let reviewed repository edits flow back. Both directions are family-scoped and dry-run by default.
How it talks to ai-memory
plan(always dry-run) andexport(dry-run unless--apply) against the documented read-only/api/v1surface: incrementalrecentlisting with cursor paging (legacy array accepted) plus single-page reads withETag/If-None-Matchrevalidation. No admin routes.sync(dry-run unless--apply) also writes to the server, and only through the publicmemory_write_pageandmemory_delete_pageMCP tools with explicitworkspaceandproject, so sanitization, admission and attribution apply. Every call carries the classified page version (expected_page_id, orcreate_onlyfor a new page). It never opens the wiki directory or SQLite, and refuses to write to a server older than 3.0, which would ignore the precondition.sync --checkis read-only (no files, no state) and exits 0 in sync, 3 on drift, 4 on conflicts or refusals; a clone without state compares the repository with the server directly.install-hookwrites a marked gitpost-mergeblock that runssync(a dry-run report unless--on-merge apply; never--prefer) anduninstall-hookremoves only that block.--include FAMILYis an explicit, repeatable allowlist of top-level wiki directories; at least one is required and a bare*is refused.- Auth is a bearer token via
--tokenorAI_MEMORY_AUTH_TOKENonly; tokens are never logged or persisted. - Each file is the server body under a fixed frontmatter of the fields a
write round-trips (
title,tags,pinned, andtierwhen not the default), never server-generated or attribution keys. All local bookkeeping lives in one state file under the destination (.ai-memory-wikisync/state.json, 0600, atomically replaced after each successful write batch). The directory ignores itself with a.gitignoreof*, so the state stays per clone and never reaches a commit.
Safety requirements honored
- Three-way classification per page (destination file, last exported
state, server body): files edited locally since the last export are
reported with a diff summary and the whole batch is refused without
--force. - The state file records the server origin, workspace and project it was
exported from. Reusing a destination for another scope refuses before
anything is written — otherwise that project's pages read as "deleted on
the server" and
--propagate-deletes --applyremoves them — and--adopt-scopeis the explicit way to discard the baseline and start fresh (#1708). A baseline written before the field existed is adopted on its first run, with a warning. planandexportnever delete;syncdeletes only with--propagate-deletes. It never runs git, commits, or pushes; it prints the commands (git add,git rm) the operator may run.- Destination-path safety: traversal, dotfiles, reserved Windows names, non-portable characters, case-fold collisions, oversized bodies, symlinked destinations/components/state directories, and unknown page frontmatter are all refused; files are replaced atomically (tmp + rename + fsync).
- Page bodies are untrusted data, transported verbatim and never executed or rendered.
syncchanges one side only when the other is unchanged since the last sync; a page changed on both sides is refused until--prefer repoor--prefer server. Deletes are reported unless--propagate-deletesis passed; then a side unchanged since the last sync is deleted, and a delete against an edit is a conflict that--preferresolves (repo: delete the page or re-create it withcreate_only;server: re-export or delete the file). More than--max-deletes(default 10) refuses the whole run; a pinned server page is deleted only with--prefer repo; a file is deleted only through the write path checks (no symlinks, confined to--dest) and only if it still holds the classified bytes. A delete that is not propagated keeps its state entry.- The post-merge hook never stores a token (
--tokenis refused; the hook readsAI_MEMORY_AUTH_TOKENat merge time), single-quotes every argument and refuses newlines or NUL, is written atomically with mode 0755, refuses a symlinked hook, appends to a foreign hook only with--appendand a POSIX shell shebang, and refuses a repository whose config setscore.hooksPath(use--hooks-diror--print). The hooks directory is found by reading.git(worktreegitdir:andcommondirincluded); git is never run. - An import requires the file's frontmatter (a write clears what it omits),
and is refused for a server page carrying any metadata the write cannot
carry (
summary,sources,kind, …), naming the keys. - Every import and delete is conditional on the page version the plan classified. An edited repository file uses one full page read to obtain both its comparison and its write precondition; unchanged files still use ETag revalidation. The server refuses a version that changed in between. That page is reported as changed during the run and keeps its state; the other pages still sync and the run exits non-zero.
Validation
cargo fmt --check --manifest-path companions/ai-memory-wikisync/Cargo.toml
cargo test --manifest-path companions/ai-memory-wikisync/Cargo.toml
cargo clippy --manifest-path companions/ai-memory-wikisync/Cargo.toml --all-targets -- -D warnings
Unit tests cover the path-safety matrix, the allowlist rules, state
hash/crash behavior and local-edit refusal; integration tests run the
full plan/export flow against a fixture axum server serving /api/v1
responses (200/ETag/304/401/404 and cursor pagination), and the sync flow
against the same fixture's POST /mcp with the server's replace semantics:
imports with metadata, creates, conflicts and --prefer, the
metadata-loss refusal, the version preconditions the fixture enforces (a
stale version is reported while the other pages apply), the old-server
refusal, delete notices and propagated deletes with each --prefer, the
delete ceiling, the pinned-page and symlink refusals, sanitizer rewrites and
the upgrade of a slice 1 export. Binary-level tests check the --check exit
codes, that it leaves the destination untouched, and drift in a clone without
state; hook tests cover fresh install, reinstall, foreign hooks and
--append, shebangs, core.hooksPath, worktrees, a $(…) workspace name
that stays inert when the hook runs, and that a token in the environment
never reaches the hook file.
Roadmap (#986)
- Read-only export into a project repository (shipped).
- Conditional mutation seam in core (shipped in 3.0:
expected_page_id/create_onlyonmemory_write_page,expected_page_idonmemory_delete_page, and the version id onmemory_read_pageand/api/v1pages). - Bidirectional apply through public write tools (shipped as
sync). - Deletes and conflict reporting (shipped:
sync --propagate-deletes,--max-deletes, conditional writes and deletes). - Post-merge hook / CI integration (shipped:
install-hook,uninstall-hook,sync --check).
ai-memory-macos: menu bar wrapper
Self-contained macOS accessory app at
companions/ai-memory-macos. It is a
wrapper rather than a data-seam dashboard: it ships the ai-memory binary and
hooks/ tree inside an .app, governs the existing LaunchAgent, and opens
/web, ai-memory status, config.toml, the data directory, and logs.
It is not a root workspace member. Build and test it separately:
./companions/ai-memory-macos/build.sh
swift test --package-path companions/ai-memory-macos
Goal
Give macOS a first-class install that does not require a prior tarball, without reimplementing status, search, wiki browsing, or config editing in SwiftUI.
How it talks to ai-memory
GET /admin/statusfor the menu-bar traffic light and two headline lines (version, page/session counts, LLM role).- Bundled
ai-memory status/ai-memory initviaProcess(the real CLI). launchctlagainstcom.github.akitaonrails.ai-memoryand the checked-in plist template inpackaging/launchd/.NSWorkspaceto open/web,config.toml, the data dir, and logs.
It does not open SQLite or the wiki, does not call writable /admin routes, and
does not add MCP tools.
Data vs bundle
Durable state stays in ~/Library/Application Support/ai-memory (the binary’s
existing macOS default) and logs under ~/Library/Logs/ai-memory. Replacing
/Applications/AI Memory.app does not rewrite that tree. An optional data-dir
override is written only into the rendered LaunchAgent plist
(AI_MEMORY_DATA_DIR), never into the bundle.
Safety requirements
- Do not silently start the LaunchAgent on first launch; Install & Start is an explicit click.
- Do not write
AI_MEMORY_AUTH_TOKENinto the plist. The menu bar’s own HTTP client may keep a bearer in the Keychain. - Do not sandbox the app in a way that blocks
launchctlor LaunchAgents.
See docs/macos.md.
ai-memory-desktop: desktop installer
A Tauri v2 app at
companions/ai-memory-desktop for people
who would rather not open a terminal (#1273, RFC #878 Phase 4). Its window
starts on a plain HTML page and then shows the page ai-memory setup --web
serves, so the whole setup UI and its safety rules stay in the CLI. There is
no npm or JavaScript toolchain.
It is not a root workspace member. Check it separately:
cargo clippy --locked --manifest-path companions/ai-memory-desktop/Cargo.toml --all-targets -- -D warnings
cargo test --locked --manifest-path companions/ai-memory-desktop/Cargo.toml
How it talks to ai-memory
- Finds an existing
ai-memory(theinstall.sh/install.ps1location,PATH, the package-manager directories) and uses it as it is. - With none, copies the binary it carries (a Tauri sidecar) and the
hooks/bundle into the same per-user layout the scripts use, links~/.local/bin/ai-memorywhen that name is free, and on Windows adds the directory to the userPATH. - Runs
ai-memory setup --web --no-open --stop-on-stdin-eofand navigates its window to the address that command prints, accepting only the exacthttp://127.0.0.1:<port>/s/<secret>/shape.
It does not open SQLite or the wiki, call /admin routes, or add MCP tools.
Safety requirements
- Never replace an existing install or someone else's
~/.local/bin/ai-memory. - Never run
setupfrom inside the bundle: the service it registers names the binary it ran from, and a.apppath, a replaced install directory or an AppImage mount would stop the server from starting later. - The setup page is a remote origin to the webview and gets no Tauri capability.
- The setup page must not outlive the app: the app holds the child's stdin,
and
--stop-on-stdin-eofstops it when the pipe closes.
Not done: signing
CI builds unsigned installers on dispatch. They are previews and are not attached to releases until the project has an Apple Developer ID with notarization and a Windows Authenticode certificate. That decision, and its cost, belong to the maintainers (RFC #878).
ai-memory-ts: TypeScript client SDK
A typed client for programs that are not coding-agent harnesses (issue #1165):
custom agents and bots, editor and app extensions (RFC #1166) and automation
scripts. It lives at companions/ai-memory-ts,
has no runtime dependencies, and talks to ai-memory only through the public
MCP tools at /mcp, the read-only /api/v1 routes, GET /identity and, from
the separate ai-memory-ts/admin entry point, the root-only /admin/*
lifecycle routes. It adds no core surface. Python is a later, separate
decision.
It is not part of the server distribution: release tarballs, Homebrew, the
Docker image, AUR, RPM and Nix never build or ship it, and
scripts/check-native-packaging.sh fails if one of their build files starts
referencing it. It is unpublished until the maintainer picks the npm name and
owner. Build and test it separately:
cd companions/ai-memory-ts
npm ci --ignore-scripts
npm run check # typecheck, unit, schema, docs
AI_MEMORY_BIN=../../target/debug/ai-memory npm run test:integration
CI runs its integration tests, schema drift test and examples against the
server built in the test job, so a change to an MCP tool schema fails until
the SDK's schema/tools.json is updated. The design, test plan and decisions
are in design-client-sdk.md; usage is in the package
README.
ai-memory-web-editor: browser chat/editor companion
This is the companion shape for PR #123.
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.
Goal
Offer a richer browser product for chat, editing, and curation without turning
the built-in /web browser into a write-capable application.
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.
Product shape
Prefer a separate repository with a backend plus frontend, for example:
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/v1for 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:
- The LLM proposes a patch, create, or delete as a pending action.
- The UI shows an explicit diff and the target workspace/project/path.
- The user confirms or rejects the pending action.
- The companion re-reads the current page and verifies the expected base hash.
- 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/v1read-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.
- Build a read-only editor shell against
/api/v1first. - Add chat over selected page/search context, still read-only.
- Add pending edit proposals with diff preview, but no apply button.
- Add confirmed writes through the companion backend and ai-memory public write endpoints.
- Add confirmed deletes last.
- Keep the built-in
/webUI unchanged unless core ai-memory independently needs a small read-only API enhancement.
Appendix: browser constraints and prerequisites (not approved)
These notes record constraints for a possible future design review. They do not approve the editor, an implementation sequence, or any new core interface. The undecided status, parked plan, concern about distracting from the automatic loop, and preference for a separate repository above remain unchanged.
Browser constraints
- Keep core
/weband/api/v1read-only. Browser requests would go through the companion's own backend, with its own login, session expiry/revocation, CSRF protection, rate limits, confirmation state, and audit. Core human-auth cookies do not establish a companion session. - Bind each authenticated browser operator to that operator's own DB-user API token, held only on the backend. Refuse missing, mismatched, or revoked credentials; never fall back to a shared credential. The browser receives no upstream bearer. Secure provisioning and storage still need design review.
- Exclude the shared static root token,
/admin/*flows, and actor-proxy credentials from this browser design. A DB-user token does not grant admin access, including when the DB user hasrole=root. Do not forward browser-supplied Authorization, actor, or skip-admission headers. These are editor-specific constraints on the broader operator-token wording above. - Reads as well as any future writes must retain the operator's identity and current project permissions. Use explicit workspace/project pairs, reauthorize each request, and isolate drafts, caches, and confirmations by operator, server, and target. UI filters cannot authorize a page; shared pages must not become author-only reads. Preserve explicit access refusals rather than showing empty results.
- Safely render untrusted Markdown, links, and diffs. Any future mutation needs confirmation bound to the operator, exact target, base revision, and proposed change. No LLM response may apply a write automatically.
Prerequisites requiring separate evaluation
- A capability contract or shared client would need independent justification from shipped callers, as discussed in PR #1058. This appendix neither requires a particular SDK nor approves speculative endpoints or wire fields. A reported capability would not replace authorization.
- Conditional editing needs a safe core compare-and-write seam, coordinated
with the normal Wiki and writer paths. 3.0 ships it:
memory_write_pageandmemory_delete_pagetakeexpected_page_id(and writescreate_only), and a stale version writes or deletes nothing (programmatic-memory.md). An editor still needs to show a fresh diff and ask again when its revision went stale. - Any retained-version or evidence reads need current access checks and bounded retention semantics; they must not recover expired or purged content from Git. 3.0's read-only page history in the built-in web UI follows those rules (it hides expired versions); no graph or procedure interface is approved here.
- Mutations must retain sanitization, admission, attribution, and disk/SQL recovery. Direct admission follows the configured failure policy; it is not the automatic loop's separate pending-write approval flow. Uncertain delivery must be reconciled before retrying or reporting success.
- A future implementation would need adversarial browser and integration tests for XSS, CSRF, identity/scope isolation, revoked access, stale revisions, admission failures, and interrupted writes, with legitimate controls. These are prerequisites, not tests or behavior supplied by this documentation.
Two kinds of companion: data-seam vs. independent hook consumer
ai-memory-importer and ai-memory-web-editor are data-seam companions: they
talk to ai-memory's public HTTP/MCP surfaces and build on the data it stores.
Not every adjacent tool is that shape.
Working-tree coordination is out of core, and is an independent hook
consumer, not a data-seam companion (decided in #620). Several agent sessions
sharing one checkout collide over the single git index: one session's
git add . sweeps up another's staged work, or a --fix run rewrites an
unclaimed tree. Building the guard on ai-memory's captured
PreToolUse/PostToolUse signal does not work, for two deliberate reasons:
- ai-memory cannot block a tool action. The
/hookpath is capture-only and fire-and-forget (it returns202/429, never allow/deny/ask, and processes after responding). Hooks that await a REST round-trip can deadlock the engine (agentmemory #221), so by design there is no synchronous veto channel back to the harness. - ai-memory does not retain the file paths. For closed-tool agents the
stored observation is reduced to a
tool_familylabel plus outcome (and an MCP tool's validated server and tool names); raw arguments, paths, and other tool names are extracted only transiently for denylist matching, then dropped (CaptureDecision"never retains raw arguments, paths, or arbitrary tool names"). A consumer can see that a file op happened in a session, never which file.
Reversing either (persisting paths, or adding a blocking hook) would trade away a privacy/bounding invariant or the anti-deadlock invariant, so both stay.
So a working-tree coordinator installs its own PreToolUse hook alongside
ai-memory's, reads the raw tool_input, and arbitrates synchronously in its own
process with its own ephemeral ownership state (a lock file or small store,
never the wiki or SQLite). It is a sibling on the same hook event rather than a
seam-consumer. It may still live under companions/ for discoverability, but it
depends on the harness's hook mechanism, not on ai-memory's surfaces. Scope it
to the shared-index / file-ownership class; stale-tree builds and host
saturation are build/CI-orchestration, a separate problem.
When to move a seam into core
A companion may reveal a missing primitive that belongs in ai-memory. Move only small, generic seams into core, and only after the companion proves the need.
Good core candidates:
- a read-only API field needed by several clients;
- a narrowly-scoped mutation endpoint that is equivalent to an existing MCP tool;
- a capability check or scope-resolution helper that prevents duplicated security logic.
Poor core candidates:
- source-specific import parsers;
- UI workflows;
- LLM chat prompts for editing;
- project-specific scoring, pruning, or normalization policies;
- companion-only admin commands.
That keeps ai-memory stable while richer tools grow around it.