Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

Merge main into release/2.5 (forward-merge: #982 #979 #981 #977-stress + docs #954)

AkitaOnRailsbf17ff250c69
diff --cc CHANGELOG.md
index cd43917c,8d89834e..4b95c7a2
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -8,285 -8,6 +8,208 @@@ and this project adheres to [Semantic V
## [Unreleased]
### Added
+- The watcher's reconcile pass can now optionally tombstone a wiki page whose
+ file has disappeared from disk, closing part of the gap left by #929 (the
+ watcher only reconciled create/modify events, so a deleted file stayed
+ indexed until `ai-memory delete-page` ran explicitly). Opt-in and default
+ `false` (`[maintenance] reconcile_tombstones_deleted_pages`), so existing
+ installs see no behavior change unless they turn it on. When enabled, a
+ page's file must be observed missing on two consecutive 30s reconcile
+ passes, re-verified against the live filesystem immediately before acting;
+ a circuit breaker refuses to act on a whole scope when more than `max(3,
+ 50%)` of its candidate pages look missing in one pass, or when a
+ non-partial walk finds nothing at all (either shape is far more likely a
+ walk/mount problem than genuine mass deletion); and reserved/indexed-but-
+ unwalked paths (`bootstrap.md`, `_meta.md`, `_pending/` sidecars, and
+ `sessions/*.md` — excluded because a same-workspace `move-session` re-home
+ can leave one with a correct row and no file, a separate pre-existing bug)
+ are never candidates. The action is a soft tombstone (`is_latest = 0` +
+ `superseded_at`, the same shape decay eviction already uses), picked up by
+ the SAME aged-tombstone hard-delete sweep decay eviction uses — it is not
+ exempt from it. What actually protects it: it is never destroyed while its
+ chain has no successor; if the file returns, the new version re-links onto
+ the tombstoned chain instead of starting a fresh, disconnected one, so
+ nothing is left orphaned for that sweep to destroy. It never runs the
+ blocking admission gate (nothing can refuse it), but does fire-and-forget
+ any non-blocking observer/mirror webhook on success. `restore-page` and
+ version history remain intact. See `docs/okf.md` for the full design.
+ (#964)
+- `[consolidation] input_token_safety_margin` (float, default `0.8`, validated
+ to `(0.0, 1.0]`) scales the approximate char-count input budget. The
+ `max_input_tokens` budget uses a flat chars-per-token heuristic that
+ under-budgets denser corpora — pt-BR text and source code tokenize at fewer
+ chars per token than English and could overshoot a provider's real input
+ limit by ~40%. The default tightens the common case modestly while leaving
+ such corpora headroom; lower it further for a mostly non-English or code
+ corpus. `max_input_tokens` is now documented as an approximate heuristic in
+ the config reference. (#884)
+- `install-skills --agent hermes` (and the `hermes` entry in
+ `memory_install_self_routing`'s `target_hints`) installs the managed routing
+ skills into Hermes Agent's `.hermes/skills` (project) or `~/.hermes/skills`
+ (global) family, completing Hermes routing support alongside its lifecycle
+ hooks (#933). (#942)
+- `[search.fts] stopwords` (env `AI_MEMORY_SEARCH_FTS_STOPWORDS`, CSV) makes
+ the stopword filter for bare natural-language FTS queries configurable,
+ so a non-English install can list its own function words (e.g. Portuguese
+ `de`, `que`, `em`) instead of having them match nearly every page and skew
+ the FTS side of hybrid ranking. Absent keeps today's English list, so
+ nothing changes on upgrade; `[]` disables the filter. Entries match
+ queries case-insensitively (Unicode) but keep diacritics, so list both
+ `nao` and `não` if users type both. Option A from #953, proposed by
+ @rntjr. (#956)
+- `docs/jev-reranker-adapter.md` gains a choice-contrastive variant of the
+ Jev reranker adapter
+ (`docs/examples/jev-reranker-adapter/jev_rerank_shim_choice.py`): one
+ `choice` question over the whole candidate list instead of one rubric
+ `score` per candidate, choice probability mapped to `relevance`. The
+ example asks for the specific page that contains the answer, and not to
+ pick an index, catalog, or summary when a more specific page answers.
+ On the same live golden set and 35B backend the choice shape measured
+ hit@1 0.778 / NDCG@10 0.893 at 0.75 s mean rerank latency versus 0.636 /
+ 0.833 at 2.2 s for the rubric adapter, and it is the shape in which
+ replay-trained small judges hold their quality (4B: 0.808 vs 0.596).
+ Safe because the reranker leg is sort-only; the rubric-adapter caveat
+ on absolute relevance semantics is scoped to consumers that read
+ absolute values.
+- `ai-memory reclaim-ledger-versions` drops the superseded versions of the raw
+ hook event ledger that the pre-2.1.1 indexer left behind (#660), and nothing
+ else. It reports what it would remove and changes nothing unless
+ `--confirm`; `--drop-latest` also removes each ledger's live row, and
+ `--compact` rebuilds the FTS index and `VACUUM`s to return the freed bytes.
+ A path is only a candidate when its *content* is a hook ledger, so a real
+ page named `log-2026-09.md` keeps its whole version chain, and only
+ `is_latest=0 AND superseded_at IS NULL` rows are eligible, so decay-owned
+ rows stay with `forget-sweep`. Derived FTS/entity/vector/link rows go with
+ the page through the existing cascades, and the FTS delete trigger is stood
+ down for the bulk delete and restored from its own `sqlite_master` DDL
+ afterwards, so the cleanup does not re-tokenize tens of gigabytes of ledger
+ body one row at a time. (#914)
+- `identity = "…"` in `.ai-memory.toml` pins the repository identity a
+ checkout's captures route by, outranking `project` and the git remote — see
+ [marker-file.md](docs/marker-file.md#repository-identity). (#708)
+- The builtin web UI has a root-only `/web/pending` page to triage pending
+ auto-improvement proposals. It lists the proposals of all projects, with a
+ project filter and a sort, and shows the rationale and the proposed body.
+ Approve and reject post to the existing
+ `/admin/pending-writes/{id}/approve|reject` routes with the session cookie
+ and the CSRF header, so admission, audit, and attribution stay the same.
+ `ai-memory-web` adds no write route. (#855)
- - Inert per-project-authorization schema and the `authorize_project` choke
- point (first slice of #708). A new `project_grants` table
- (`(workspace, project, user) -> read|write`) and a `projects.access_mode`
- column (`open` | `restricted`, default `open`) are added additively — every
- existing project stays `open`, so there is no behaviour change. The typed
- `authorize_project` gate (consulted by `ScopeResolver` read/write resolution
- and, as defense in depth, by the writer actor) short-circuits `open`
- projects and single-user/loopback deployments to ALLOW, and degrades to open
- when grants cannot be read (never a lockout). A `restricted` project with
- zero grants still admits root and the creator. Because nothing sets
- `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 (third 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
+ `hooks/` tree when present), then re-runs `install-hooks --apply` for staged
+ agents. Windows uses rename-aside self-replace (running `.exe` → `.old`,
+ promote `.new`) because the mapped image cannot be overwritten in place.
+ Refuses package-managed paths (Homebrew/AUR/`/usr`), containers, and
+ unwritable prefixes; the Docker wrapper's `upgrade` path is unchanged. Pin
+ with `--version` / force a re-download with `--force`. Optional
+ `AI_MEMORY_RELEASE_BASE_URL` / `release_base_url` overrides the Releases
+ base for mirrors and hermetic tests (loaded via `Config`, not ad-hoc env).
+ Downloads refuse bodies over 128 MiB (Content-Length and streamed cap).
+ (#801, #802)
+- `ai-memory run` accepts a repeatable `--env KEY=VALUE` and an `--env-file
+ <path>` (blank lines and `#` comments skipped) to pass extra environment
+ into the spawned harness — e.g. a per-account `CLAUDE_CONFIG_DIR` for
+ callers who previously had to wrap the launch in `env KEY=VAL harness`.
+ Both flags are wrapper-owned like `--yolo`/`--executable` and must precede
+ the harness name; a `--env` entry overrides a same-key `--env-file` line.
+ The resolved environment reaches the spawned process, ai-memory's own
+ native-session resolution, first-launch auto-wire and the global Crush
+ config the managed context packet is layered onto, so the session store,
+ hooks and MCP all follow a `CLAUDE_CONFIG_DIR`-style override, and
+ auto-wire warns when the override puts Pi and OMP in one extensions
+ directory. See `docs/managed-workstreams.md`. (#820)
+- `contradiction_band_min` / `contradiction_band_max` config keys (env:
+ `AI_MEMORY_CONTRADICTION_BAND_MIN` / `AI_MEMORY_CONTRADICTION_BAND_MAX`)
+ make `memory_lint`'s A5 zero-LLM contradiction-detection cosine-similarity
+ band configurable, defaulting to the historical fixed `0.4`–`0.75`. The
+ band is a fixed absolute cosine value, but background similarity is
+ corpus-dependent: on a single-language or single-domain store, unrelated
+ pages already sit above the general-purpose floor, so the default band
+ measures domain proximity more than conflict and produces noisy findings.
+ Raising `contradiction_band_min` trims that noise. Rejected at config load
+ unless `0.0 <= contradiction_band_min < contradiction_band_max <= 1.0` and
+ both are finite. (#853)
+- Fedora users can install prebuilt x86_64 and aarch64 RPMs from GitHub
+ Releases, with the existing native systemd service assets. (#858)
+- `embedding_query_prefix` / `embedding_document_prefix` config keys (env:
+ `AI_MEMORY_EMBEDDING_QUERY_PREFIX` / `AI_MEMORY_EMBEDDING_DOCUMENT_PREFIX`)
+ for the `openai` and `openai-compat` embedders: an optional string
+ prepended to query / document text before the existing truncation, so
+ truncation still bounds the whole input. Asymmetric embedding models need
+ a query-side instruction their publisher specifies; the OpenAI-compatible
+ `/v1/embeddings` wire format has no field for it.
+ `nvidia/Nemotron-3-Embed-1B-BF16` and base E5 models use a simple
+ `"query: "` / `"passage: "` pair; instruction-tuned E5 variants and
+ Qwen3-Embedding instead need a task-instruction string on the query side
+ only (documents stay plain). Empty by default — no behaviour change when
+ unset, and not trimmed (nor is a present-but-empty env-var override, which
+ now clears a `config.toml` value), so a publisher's trailing space is
+ preserved. A non-empty `embedding_document_prefix` is folded into the
+ stored embedding identity (`Embedder::model_identity`), so a document
+ prefix change makes retrieval, backfill, and cleanup treat existing pages
+ as stale and re-embed them automatically — an empty prefix keeps the
+ pre-existing identity, so upgrading installs need no migration, and a
+ query-only prefix change never needs a rebuild. See
+ `docs/llm-providers.md`. (#859)
+- Added the optional `ai-memory-relay` companion for external lifecycle events.
+ It queues events locally and sends ordered batches through the public hook API,
+ using stable event identities for retries. The package has its own workspace
+ and does not change the server's capture or storage defaults. (#823)
+- `auto_improve.patchable_page_prefixes` makes the folders whose page bodies the
+ reviewer reads configurable, defaulting to the historical `_rules/` and
+ `procedures/`. Only those two folders' contents were ever sent; every other
+ page reached the model as a single title line, so a project keeping its
+ durable knowledge in `decisions/` or `gotchas/` — with no `_rules/` pages at
+ all — sent no page bodies, and the reviewer re-proposed invariants that were
+ already written down, at high confidence, indefinitely. Existing configs are
+ unchanged. (#834)
+- `ai-memory finalize-session --reopen --session-id <uuid>` re-finalizes a
+ session that already ended, for agents without a true session-end event
+ (Antigravity CLI, Kiro, ZCode, Pool) whose conversation continued after a
+ first manual finalize: the discovery step now accepts `include_ended=true`
+ on `GET /admin/open-sessions` for an exact session id (rejected without
+ one, so reopening stays exact-id-only and never a bulk operation), and the
+ server's normal session-end path re-runs over the new observations
+ (updated summary page via supersession, new handoff, opt-in
+ consolidation). Re-running with nothing new since the first end remains a
+ harmless no-op. The default finalize behavior is unchanged: ended sessions
+ stay invisible unless `--reopen` is passed. (#836)
+- Added per-execution `AI_MEMORY_CAPTURE_OWNER` context for external lifecycle
+ producers. Updated native hooks, script bundles and generated integrations
+ suppress capture while preserving supported handoff delivery and MCP recall.
+ Documented producer provenance and stable retries through the existing hook
+ ingestion API, without changing its schema or standalone defaults. (#821)
+- Builtin `/web` login and change-password pages for human password sessions:
+ unauthenticated browser GETs to the wiki redirect to `{web_slug}/login`
+ (not bare JSON 401), forms call existing `POST /auth/login` /
+ `/auth/password` / `/auth/logout`, and `--web-ui-dir` custom SPAs stay
+ unchanged. (#811)
- - `[consolidation] input_token_safety_margin` (float, default `0.8`, validated
- to `(0.0, 1.0]`) scales the approximate char-count input budget. The
- `max_input_tokens` budget uses a flat chars-per-token heuristic that
- under-budgets denser corpora — pt-BR text and source code tokenize at fewer
- chars per token than English and could overshoot a provider's real input
- limit by ~40%. The default tightens the common case modestly while leaving
- such corpora headroom; lower it further for a mostly non-English or code
- corpus. `max_input_tokens` is now documented as an approximate heuristic in
- the config reference. (#884)
+- `docs/jev-reranker-adapter.md` documents a stdlib-only adapter
+ (`docs/examples/jev-reranker-adapter/jev_rerank_shim.py`) that serves the
+ `AI_MEMORY_RERANKER=llm` request leg from a Jev `/v1/systemone` judge
+ endpoint while reverse-proxying consolidation/lint/bootstrap traffic to
+ the configured provider unchanged. In the contributor's own 102-query
+ golden-set benchmark the judge matched the hosted reranker's
+ hit@1/MRR/NDCG@10 (0.778/0.838/0.873 vs 0.778/0.840/0.875) at 0.205 s
+ mean latency instead of 20.2 s — in that run the hosted mean sat on the
+ server's 20 s completion timeout, which made the reranker stall every
+ query before falling back. (#873)
+- MCP tool calls from OpenCode 2 (2.0.4+) are routed by the native session id
+ the client sends in `params._meta["ai.opencode/sessionID"]`, ahead of the
+ `Mcp-Session-Id` transport header, which OpenCode shares across every
+ session in a directory. Concurrent OpenCode sessions in different projects
+ no longer read each other's active project; explicit `workspace`/`project`
+ arguments still win and `X-Memory-Actor-Session-Id` keeps precedence. (#864)
+- OpenCode 2 turn checkpoints: every completed root turn
+ (`session.execution.succeeded`, `.failed` or `.interrupted`, OpenCode
+ 2.0.10+) now refreshes `sessions/<id>.md` and the session's automatic
+ handoff without ending the native session, because OpenCode 2's shared
+ service outlives the CLI and closing a terminal is not a session end. The
+ checkpoint is deterministic (no LLM call), is written in the session's own
+ scope, keeps one open baton per live session (refreshed in place, audited as
+ `refresh_handoff`), and never touches a session that already ended. Child
+ sessions neither claim startup context nor publish batons. (#865)
- - `install-hooks --agent opencode2 --capture-assistant` extends the
- assistant/Stop capture double opt-in to OpenCode 2: the plugin forwards the
- last completed assistant text through the native hook's sanitizer before it
- reaches the spool or the wire. The captured excerpt continues the work in
- the next session's automatic handoff; it is not rendered into the
- git-tracked session page. (#865)
- - `install-hooks --agent hermes` (alias `hermes-agent`) and
- `setup-agent --agent hermes` for **Hermes Agent** (Nous Research). Hermes
- splits a configured hook `command` with `shlex.split` and runs it with **no
- shell**, with the event JSON on stdin, so the generated block invokes the
- native `hook` subcommand directly — the same shape Zero and ZCode use, and no
- `.sh`/`.ps1` bundle is staged. Two events are wired, `pre_tool_call` and
- `post_tool_call`, whose payload (`tool_name` / `tool_input`) is the envelope
- the router already mapped for `agent=hermes`; this is what finally gives
- Hermes sessions tool observations. `~/.hermes/config.yaml` is printed, never
- written: it is YAML the operator also edits, and Hermes gates user hooks
- behind its own acceptance prompt (`hooks_auto_accept`). Session lifecycle
- stays with the ai-memory memory-provider plugin, so a hook-driven
- `session-end` cannot double-close a session. (#623 follow-up, #933)
- `docs/llm-providers.md` now has a dedicated OpenRouter subsection and a
matching row in the recommended-defaults table. The wiring
(`openai-compat` + `AI_MEMORY_LLM_BASE_URL=https://openrouter.ai/api/v1`)
@@@ -314,391 -35,28 +237,275 @@@
`ai-memory backup --to <tarball>` command
(`docs/lifecycle-ops.md#backup`) is unchanged. (#950)
++
### Changed
+- `ai-memory purge-session` without `--confirm` now previews what a confirmed
+ purge would delete before refusing, the same way `purge-project` does (#945):
+ `Would purge session from <ws>/<proj>: N observations, N handoffs, N pages,
+ N auto-improve runs.` (the session id itself is never printed). The server
+ takes a new `dry_run` field on `POST /admin/purge-session` that always wins
+ over `confirm`. It only counts; no delete, wiki file removal, webhook,
+ audit row or checkpoint runs. `POST /admin/purge-session`'s confirmed
+ report also gains two new fields, always present on both the preview and
+ the confirmed response: `collateral_observations_deleted` and
+ `collateral_handoffs_denulled`, counting what the purge cascades into
+ *other* projects through this session's own id. The CLI still exits
+ non-zero without `--confirm`; against an older server, or if the preview
+ times out, it prints only the existing refusal. (#957)
+- `POST /admin/delete-workspace` takes a `dry_run` field that always wins
+ over `force` and previews what a confirmed delete would remove, with the
+ same 404/409 a confirmed delete gives. It only counts: no admission call,
+ directory removal, mirror dispatch or checkpoint. The preview and the
+ confirmed response now also report `sessions_deleted`,
+ `observations_deleted`, `handoffs_deleted` and `embeddings_deleted`
+ (previously only projects, pages, workstreams and managed runs), plus
+ `collateral_observations_deleted` and `collateral_handoffs_denulled` for
+ rows in *other* workspaces reached through this workspace's sessions.
+ `merge-workspace` is unaffected. There is no CLI subcommand, so this is
+ HTTP-only. (#963)
- - `ai-memory purge-project` without `--confirm` now previews what a confirmed
- purge would delete before refusing: `Would purge <ws>/<proj>: N pages, N
- sessions, N observations, …`, with the same 404/409 a real purge gives.
- Before, the counts only appeared after the rows were gone. The server takes
- a new `dry_run` field on `POST /admin/purge-project` that always wins over
- `confirm`. It only counts; no delete, wiki removal, webhook, audit row or
- checkpoint runs. The preview and the confirmed report also count what the
- purge cascades into *other* projects through this project's sessions
- (`collateral_observations_deleted`, `collateral_handoffs_denulled`). The
- CLI still exits non-zero without `--confirm`; against an older server, or
- if the preview times out, it prints only the existing refusal. (#945)
+- Captures from a checkout with no declared `project` and a git remote now route
+ by the repository's identity — the normalised `upstream` remote, else `origin`
+ — instead of the folder name (`projects.identity`, V70). Two unrelated
+ repositories sharing a folder name now get two projects (the second named
+ after its owner, e.g. `orgb-api`); one repository cloned into differently
+ named folders converges on one project, the first to claim the identity —
+ an existing second project keeps its history but stops receiving captures.
+ Existing projects are claimed in place, so upgrading moves no memory, and a
+ user who may not write to a project cannot claim its identity. Checkouts
+ that declare `project` in their marker route by name exactly as before. Every
+ hook client (native, shell, PowerShell, TypeScript) resolves the identity
+ host-side and sends it as `identity` / `identity_src`; credentials in a remote
+ URL never leave the machine. (#708)
- - 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
+ discards that stdout); a session that never calls a tool leaves the handoff
+ open for `memory_handoff_accept`. The note is clipped to 10,000 characters
+ (Grok's own cap). Because Grok reuses one session id across a
+ SessionEnd→restart, `memory_handoff_accept` now reopens an already-ended
+ receiver session (clears `ended_at`) instead of rejecting it — but only for
+ agents that reuse their session id across a restart (Grok); for every other
+ agent an ended session stays final, so a lifecycle-only receiver still cannot
+ reclaim after it released and ended. The reopen also only happens after the
+ exactly-once claim guard, so a session that already took a baton still cannot
+ take another (the multi-session claim-once invariant is preserved).
+ Delivery of this PostToolUse handoff is exempt from `AI_MEMORY_CAPTURE_OWNER`
+ capture suppression, like the other context-delivery events. (#840)
+- The generated OpenCode 2 plugin binds to the OpenCode 2.0.10+ event and hook
+ API (`session.execution.*`, `session.text.ended`, `session.moved`, the
+ `context` hook). Startup context is claimed once per root session and
+ retained on every later model request; content-only tool results are
+ captured; each location instance owns its own queue, spool state and
+ cleanup; an explicit `session.moved` rebinds the live session to its new
+ directory so its later end lands there. Checked against OpenCode 2.0.14. (#865)
+- Quieted the default server log: the reconciliation-pass summary that fired
+ every 30 s regardless of activity dropped from `info` to `debug`, and the
+ default log filter now pins the external `rmcp` MCP SDK to `warn` (its
+ per-request lifecycle logging at `info` was the other half of a near-empty
+ server's log). Both are restorable through `log_level` (e.g.
+ `"info,rmcp=info"` or `"debug"`) or `RUST_LOG`; the `tracing_appender=warn`
+ feedback-loop guard stays non-overridable. (#894)
+
+ - Documented Cheaper Inference as an endpoint for the existing `openai-compat`
- provider.
++ provider. (#981)
++
+
### Fixed
-- `observations.title` is now sanitized before it is truncated, not after.
- `title_hint` used to be cut to 80 chars in `ai-memory-hooks::payload`
- *before* the sanitizer ever ran, so a secret straddling that cutoff was
- often left as a fragment too short to match a built-in or `[sanitize]
- extra_patterns` rule — landing in the title, its FTS index, and every
- surface that renders titles (session pages, briefings, handoffs, search)
- unredacted, even though the same observation's body was correctly scrubbed
- first. `title_hint` extraction now keeps the full first line untruncated;
- `Sanitized::new` scrubs the title and only then applies the 80-char display
- cap (`ai_memory_core::sanitize::truncate_for_title`), mirroring the order
- the body already used. (#982)
-- The `/web` page view keeps a leading H1 that is not the page title. It
- dropped the body's first H1 whatever it said, as a duplicate of the title
- in the header, but a frontmatter `title:` outranks the H1 and a setext H1
- never names the page, so a heading like `# Token refresh after sleep`
- under `title: Auth decisions` vanished from the rendered page. An H1 that
- repeats the title is still dropped. (#967)
+- A Kiro v3 resume that falls back to the default session store drops
+ `KIRO_HOME` from the child, but auto-wire still installed hooks and MCP
+ under `KIRO_HOME`; it now wires the default home that resume reads. (#820)
- - `ai-memory run` auto-wired only the first config home per agent and
- version: its sentinel ignored where hooks and MCP were installed, so a second
- account (another exported `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, ...) was
- skipped. The sentinel now also keys on the resolved hook and MCP config
- paths. The Codex MCP entry ignored `CODEX_HOME`: `install-mcp` and auto-wire
- now write `$CODEX_HOME/config.toml`, matching `hooks.json`; `uninstall`
- sweeps the legacy `~/.codex/config.toml` too, and `install-hooks` still
- infers the server URL and token from it until the entry is rewritten. (#820)
- - Corrected OMP's install and session paths for named profiles. Hooks and
- `mcp.json` now use the profile's agent directory and ignore
- `PI_CODING_AGENT_DIR`. Profile selection follows `--profile`, then
- `OMP_PROFILE`, then the legacy `PI_PROFILE`. Names are trimmed and
- validated; empty environment values, whitespace-only names and `default`
- select the default profile. Returning to the default profile also drops
- an agent directory inherited from a named parent profile.
- `PI_CONFIG_DIR` changes the `.omp` root relative to the user's home.
- On Linux and macOS, `run omp`, `backfill` and `doctor` read sessions from
- `$XDG_DATA_HOME/omp/sessions` (or `omp/profiles/<name>/sessions` under
- `$XDG_DATA_HOME`) when the corresponding OMP directory exists and the agent
- directory has not been relocated. `run omp` also honors
- `PI_CODING_AGENT_SESSION_DIR` and a leading native `--profile`.
- Uninstall checks the active and default profiles plus the legacy `.omp`
- locations, and an invalid OMP profile no longer stops cleanup for other
- agents. (#820)
- - A whitespace-only `KIMI_CODE_HOME`, `KIRO_HOME` or `GROK_HOME` pointed
- installs at a blank-named directory under the working directory, and a
- whitespace-only relocation variable did the same for `ai-memory run`'s
- native session import. Blank now counts as unset everywhere, as it already
- did for the `CLAUDE_CONFIG_DIR`, `CODEX_HOME` and `PI_CODING_AGENT_DIR`
- installers, and `ai-memory run` drops such a value from the harness it
- launches so the harness uses its default home as well. Crush's managed
- context likewise read a whitespace-only `CRUSH_GLOBAL_CONFIG` or
- `XDG_CONFIG_HOME` as a directory, and now falls back to the default global
- config. (#820)
+- Native `ai-memory upgrade` no longer refuses every Linux install by probing
+ the running executable for write (Linux `ETXTBSY`); it only requires the
+ parent directory to be writable for rename-based replace. (#802)
- - A managed Crush launch with a context packet dropped the `CRUSH.md` and
- `AGENTS.md` Crush loads by default: Crush only adds them while
- `global_context_paths` is empty, and the packet filled it. The launcher now
- adds them first when the user's config lists none, and no longer refuses to
- start over a global `crush.json` Crush accepts (an empty file, `null`, or
- `null` options), read from the path cleaned as Crush cleans it. The global
- `crushrc` beside that config, which Crush stopped reading once the config
- dir moved, is now sourced from its own directory as well. (#820)
- - Two fresh managed Crush launches on one store could import each other's
- transcript: Crush has no hooks to link its session, and after exit `ai-memory
- run` took the newest session there. A fresh launch now claims only the one
- top-level session created while it ran and imports nothing, with a warning,
- when another launch created one too; its title and sub-agent sessions are no
- longer taken for the conversation, and in a data directory outside the
- project only a session that edited a file in the project is claimed. (#820)
- - `ai-memory run crush`, `backfill` and `doctor` looked for Crush sessions only
- in `<cwd>/.crush/crush.db`, so a launch from a project subdirectory, or a
- project whose Crush config sets `options.data_directory`, imported nothing.
- They now find the store as Crush does: `options.data_directory` from Crush's
- JSON configs, else the closest `.crush` up to the git worktree root (not one
- directly in the home), else `<cwd>/.crush`. (#820)
- - Native `ai-memory upgrade` accepts release archives whose entries are
- `./`-prefixed (`tar -C … -czf … .` as in `release.yml`), instead of
- rejecting `Component::CurDir` as an unsafe path. (#802)
- - `ai-memory uninstall` left `ai-memory run`'s auto-wire sentinels in
- `<data_dir>/autowire-state/`, so after the hooks were removed the next
- managed launch of that harness on the same binary version skipped wiring and
- captured nothing. Removing hooks or MCP (a full uninstall, `--only hooks` or
- `--only mcp`) now deletes every sentinel and lists them in the dry-run plan.
- `--only mcp`, `--only instructions` and `--only skills` also no longer delete
- the stored hook bearer that the still-installed hooks read. (#820)
- - Native `ai-memory upgrade` treats Linuxbrew (`/home/linuxbrew/.linuxbrew/`)
- as package-managed and refuses self-replace there. (#802)
- - Native `ai-memory upgrade` container refusal now uses the shared
- `running_in_container` helper (`AI_MEMORY_IN_CONTAINER`, `/.dockerenv`,
- `/run/.containerenv` / Podman), matching staged-hooks detection. (#802)
+- Parallel OpenCode 2 sessions in one directory no longer receive each
+ other's context. Each completed turn's checkpoint retired the automatic
+ handoffs of every other live session there, and the next session to start
+ was handed the handoff of a session still in use (mid-turn, or seconds after
+ its last turn). A checkpoint now spares other live sessions' handoffs; a
+ starting session receives a live session's handoff only once that session
+ has captured nothing for ten minutes, re-checked inside the claim; and the
+ claim retires older handoffs of quiet sessions but not of one in use.
+ (#883)
+- `memory_query`'s vector stream called the generic `Embedder::embed`
+ instead of `embed_query` on the configured embedder, so a
+ query/document-asymmetric embedder (Google's task-typed embeddings, or
+ the new query/document prefixes above) embedded the search query on the
+ document side instead of the query side. Indexed writes are unchanged;
+ only the query-side helper moves onto the query task. (#859, #861)
+- A manual `memory_consolidate` now reconciles the session's durable
+ consolidation job row. The MCP handler wrote the page directly through the
+ consolidator without touching `session_consolidation_jobs`, so a session
+ whose automatic SessionEnd job had reached the terminal `failed` state (that
+ the worker never re-claims) kept showing `failed` even though the operator
+ had just consolidated it. After a successful, non-dry consolidate the handler
+ flips a `failed`/`pending`/`superseded` row for the session to `completed`; a
+ live `running` lease is never touched, so a concurrent automatic worker
+ attempt is left to settle its own row. (#890)
+- Tool-family labels no longer leak into automatic handoffs and session-page
+ titles, and the file-activity handoff warning fires again. Every closed-tool
+ agent stores a call's title as `tool file` / `tool non-file` / … (a partition
+ of the calls, not a tool name); these were surfacing verbatim as `Tools used:
+ tool file, tool non-file` in handoffs and, for a session whose only non-prompt
+ observation was such a call, as the page title. The same spelling meant the
+ "session ended without a normal stop while working with files" heuristic —
+ which only matched the bare `file` spelling of the minority reserved-protocol
+ path — never fired for a real session. A shared recognizer now maps both
+ spellings, drops the labels from the handoff tool list and the title fallback,
+ and drives the file-activity warning from either. (#895)
+- Generated rule slugs (`_rules/<slug>.md`) now fold Latin diacritics to ASCII
+ instead of turning each accented letter into a hyphen: `estável` slugs as
+ `estavel` (was `est-vel`) and `retenção` as `retencao` (was `reten-o`). Long
+ titles are also truncated at a word boundary (the last hyphen inside the
+ 60-char budget) rather than mid-word. Uses the icu_normalizer NFD
+ decomposition ai-memory-core already depends on; no new dependency. (#886)
+- Multi-page consolidation now stores page paths with a `.md` extension.
+ The LLM returns a bare path for a non-rule page (`decisions/smart-model-luna`),
+ and the shared path sanitizer passed it through verbatim, so the page landed
+ extensionless and read back as a non-portable wiki path. The sanitizer now
+ appends `.md` to the filename component when it is missing (idempotent,
+ case-insensitive), fixing the non-rule consolidation, bootstrap, and
+ auto-improve front doors at once. (#885)
+- `ai-memory run`'s auto-wire no longer overwrites an installed session-aware
+ Claude Code MCP bridge with the static HTTP registration. The auto-wire
+ sentinel is keyed by client version, so the MCP step re-ran on every upgrade
+ and replaced the `ai-memory` entry wholesale; a user who had run `install-mcp
+ --client claude-code --session-aware` lost the bridge on the next `ai-memory
+ run` after an upgrade, silently disabling `[auto_scope] per_session` for their
+ MCP calls. Auto-wire now detects an existing session-aware bridge and keeps
+ it. (#888)
- - After a managed launch, `ai-memory run` imported the newest native session
- in the checkout even when a hook in the launched harness had linked the
- run's own session, so a concurrent launch in the same checkout could hand it
- another transcript. The server now records when a session is linked during
- a run (schema migration V67, adding `managed_runs.native_session_linked_at`)
- and reports it in the run status, and the launcher imports that session
- when this checkout's store holds it (a process the child starts inherits
- the run id; OpenCode is checked by the session's recorded directory). An
- older server reports no link and keeps the previous behavior. (#820)
+- On Windows, OpenCode 1 and 2 sessions are found again from their checkout:
+ OpenCode records a session's directory with forward slashes
+ (`C:/Users/me/repo`), so matching only the backslash checkout path found
+ none. `ai-memory doctor` reported `0 local` for OpenCode while it captured
+ sessions there, and `ai-memory run` / `show` could neither discover nor list
+ a native OpenCode session to resume. (#882)
+- Grok Build CLI hooks capture on Windows again. Grok evaluates
+ `~/.grok/hooks/*.json` commands with PowerShell, as Codex does (#515), so
+ the double-quoted executable path in command position parsed as a string
+ expression and every hook exited 1 with a ParserError: sessions ran with
+ the hook installed and nothing was captured. The Windows command now
+ carries PowerShell's `&` call operator for Grok too; re-run
+ `ai-memory install-hooks --agent grok --apply` to rewrite an existing
+ install. (#887)
+- The Linux/macOS Docker wrapper now keeps its native host client in
+ `${XDG_DATA_HOME:-~/.local/share}/ai-memory/native-runner` instead of
+ `~/.cache/ai-memory/native-runner`. `ai-memory run` auto-wires hooks whose
+ command is that client's path (Claude Code, Codex, Kimi Code, Command Code,
+ Kiro CLI v3, Grok, Antigravity CLI), so flushing `~/.cache` left every hook of
+ those harnesses pointing at a missing binary. The wrapper also keeps the
+ release's `hooks/` bundle beside the client, so auto-wire no longer fails
+ with "could not locate hooks directory" for script-based harnesses on a host
+ where `install-hooks` never ran. (#874)
+- Fixed pre-push installation from linked worktrees and preserved the managed
+ block's position during reinstallation. Configured `core.hooksPath` overrides
+ and ambiguous markers are rejected without replacing the existing hook. The
+ block now keeps its shell options and `SSL_CERT_FILE` inside its subshell and
+ propagates a failure explicitly, so user hook commands after it keep their
+ own semantics and a failing test run still blocks the push. (#824)
- - Isolated the pre-push test process from Git's repository environment and
- global/system configuration so fixture commands use their own repositories.
- Existing installations need to run `scripts/install-git-hooks.sh` again. (#824)
+- A Windows service running as `LocalSystem` over a user-owned data
+ directory no longer breaks the wiki git history silently. libgit2's
+ dubious-ownership guard (CVE-2022-24765) fails every wiki commit with
+ `code=Owner` when the process account does not own the repository, but
+ the failure was WARN-only, so capture and search kept working while no
+ wiki checkpoint was ever committed. The startup baseline checkpoint now
+ surfaces an owner-check failure at ERROR with the remedy (run the
+ service as the owning user), and `docs/windows.md` Scenario E documents
+ running the service under a `<serviceaccount>`, corrects the claim that
+ only the data directory is account-sensitive, and notes the WinSW
+ error-1069 / stale-password gotcha for Microsoft-account / PIN / Hello
+ users. The owner check itself is deliberately left enabled. (#872)
+- A Windows folder no longer splits into two projects. The hook router
+ derived a project's *name* from the cwd after
+ `normalize_project_path_key` had ASCII-lowercased the whole
+ drive-letter/UNC path — basename included — so a session in
+ `D:\...\Default Project` was captured under `default project` while the
+ CLI (which keeps the raw basename) used `Default Project`. Because
+ `get_or_create_project` matches names case-sensitively, one folder
+ minted two projects. The router now takes the name from the raw cwd; the
+ cache key and cwd-prefix match keep the case-folded path, so #806 handoff
+ stickiness is unaffected. (#871)
+- Auto-improve review no longer stages a proposal whose LLM-produced page
+ path contains a Windows-illegal character (e.g. a `:` copied from a
+ conventional-commit subject). That path passed the deliberately tolerant
+ `PagePath::new` and only failed later at `ensure_portable` when the
+ proposal was approved, so the learning loop queued work that could not
+ be applied. Paths are now sanitized the same way bootstrap (#847) and
+ per-session consolidation (#848) already sanitize theirs, before
+ validation; a path that is still unportable after sanitizing is rejected
+ instead of staged. (#850)
+- Omitted `temperature` for `gpt-6-*` models in the `codex`,
+ `openai-oauth`, `copilot` and `openai` providers. Codex answered GPT-6
+ requests that carried `temperature` with `400 Unsupported parameter:
+ temperature`, which broke consolidation, lint and bootstrap on a
+ provider or fallback configured with `gpt-6-luna`, `gpt-6-sol` or
+ `gpt-6-astra`. The `openai` provider now also sends
+ `max_completion_tokens` for GPT-6 and no longer applies its local
+ 16,384-token cap to it, matching `gpt-5*`. (#851)
+- `memory_message_pop` and `memory_message_list` no longer return a silent
+ empty result when the inbox scope was *inferred* rather than named. A caller
+ with no explicit `workspace`/`project` and no forwarded hook-session id
+ resolves the shared active-project slot (whichever project published last),
+ so two same-operator agents can have a no-scope pop land on a different inbox
+ than the on-start notice / `memory_briefing` counted — "you have mail"
+ followed by an empty fetch, with no way to tell it was the wrong inbox. An
+ empty read from an inferred scope now reports the `resolved_scope`
+ (workspace + project), the `scope_source`, and a hint to re-run with explicit
+ scope; an explicitly-scoped or session-bound empty read is unchanged. No
+ message is lost — the mis-scoped pop consumes nothing. (#854)
+- `companions/ai-memory-macos/build.sh` no longer fails on machines whose
+ active developer directory is Command Line Tools only: SwiftUI `@State`
+ needs the `SwiftUIMacros` plugin shipped with full Xcode, so the script
+ now exports `DEVELOPER_DIR` to Xcode (or a caller-set path) before
+ `swift build`, with a clear error when no macOS platform is present. (#849)
+- `ai-memory serve` no longer leaked file descriptors from half-open HTTP
+ connections until `EMFILE`, breaking the healthcheck (an unauthenticated
+ availability/DoS). A hook or MCP client whose peer died without sending FIN
+ (laptop sleep, a VPN/Tailscale flap, an abrupt kill) left its accepted
+ socket `ESTABLISHED` forever, since the OS default has TCP keepalive off —
+ each dead peer leaked one fd, exhausting the 1024-fd default in roughly 2-3
+ days of normal churn. Accepted connections now get TCP keepalive via
+ `socket2`, tunable with the new `tcp_keepalive_secs` config key (default
+ 60s; `AI_MEMORY_TCP_KEEPALIVE_SECS=0` disables keepalive). This closes the
+ half-open-socket half of the fd leak; the rmcp session-table half was
+ already fixed in 2.4.0 by the rmcp 2.x bump. (#792)
- - `ai-memory bootstrap` no longer returns a 500 when the LLM emits a page
- path containing a Windows-illegal character (e.g. a `:` copied verbatim
- from a conventional-commit subject like `build(sandbox): orchestrate`).
- Such a path passed the deliberately tolerant `PagePath::new` and only
- failed later at `ensure_portable` inside the atomic wiki write batch,
- which aborted every page in the run, not just the offending one. Bad
- paths are now sanitized (illegal characters replaced with `-`, directory
- shape preserved) before validation, so the run and its other pages
- survive; a path `ensure_portable` still rejects after sanitizing is
- skipped with a warning instead of failing the batch. (#847)
- - Per-session consolidation (`consolidate_session_multi`) had the same
- Windows-illegal-path defect as `ai-memory bootstrap` (#847): an
- LLM-produced page path containing a character like `:` passed the
- deliberately tolerant `PagePath::new` and only failed later at
- `ensure_portable` inside the atomic wiki write batch, losing every other
- page from that session's consolidation run. The path is now sanitized
- the same way bootstrap's is, consistently across rule-routing, per-user
- slot placement, and the session-anchor comparison, before validation;
- a path `ensure_portable` still rejects after sanitizing is skipped with
- a warning instead of failing the batch. (#848)
+- The Windows release checksum (`ai-memory-windows-x86_64.zip.sha256`) is now
+ written with a LF terminator instead of CRLF. `Out-File`'s Windows line
+ ending made `sha256sum -c` fail with `No such file or directory` — the CR
+ is read as part of the filename — on the WSL2 and Git Bash paths where that
+ is the natural command, and placed a stray byte in the release body's
+ checksum block, which concatenates every platform's file. The zip's smoke
+ test now requires LF rather than tolerating either, so the format the
+ release claims is the format it ships. (#838)
+- `purge-session` now removes every page version the session owns at
+ `sessions/<id>.md` (including versions written before OKF sources existed
+ and summaries of sessions that never recorded a summary pointer), while a
+ manual page at the same path survives. (#862)
+- Shell hooks no longer pin a CPU core for minutes on a large payload. The
+ `hooks/_lib.sh` extractors for `cwd`/`workspacePaths`/`workspace_roots`,
+ the session id, and Antigravity's `invocationNum` located each key with
+ `${payload#*"key"}`, which is quadratic in the payload size under dash and
+ bash: a 200 KB Cursor `postToolUse` event spent minutes in
+ `ai_memory_extract_cwd`, and concurrent hooks stayed at 100% CPU before
+ ever reaching the POST. A shared `ai_memory_after_key` helper now finds the
+ first occurrence with one linear `awk` pass (about 50 ms at 200 KB) and
+ feeds the unchanged `sed` parsing, so the extracted values are the same as
+ before. (#870)
+- The generated TypeScript integrations (OpenCode 1 and 2, OMP, Pi,
+ OpenClaw) no longer flash a console window on Windows for every captured
+ event: their `git` lookups set `windowsHide`. The repo-root project lookup
+ behind those spawns is memoized per cwd instead of running two synchronous
+ `git` processes on every event. (#863)
+- A `SessionEnd` whose resolved scope drifted from its session (a
+ `.ai-memory.toml` appeared under the running session) was refused as a
+ foreign-scope end and stranded the session open forever. It now ends the
+ session when owner and agent match and the event comes from the session's
+ own (normalized) cwd; a different cwd, operator or agent is still refused. (#865)
- - Generated TypeScript integrations no longer overwrite each other's spooled
- events written in the same millisecond, and a host that tears its capture
- state down cancels still-pending deliveries after the drain budget instead
- of waiting out each request's timeout. (#865)
+- Shell hooks on macOS no longer corrupt non-ASCII characters in the query
+ string. `/bin/sh` there is bash 3.2, which sign-extends bytes >= 0x80, so
+ `ai_memory_url_encode` sent `é` as `%FFFFFFFFFFFFFFC3%FFFFFFFFFFFFFFA9`
+ instead of `%C3%A9`. An accented cwd reached the server as a different
+ path, and Cursor events and the session-start handoff lookup both use the
+ query `cwd`. (#877)
- `memory_query` now returns `global_scope_hits` (standing `_global` user/team
preferences) for a single-project query whose project is named explicitly
with `workspace`+`project`, not only when scope is omitted. The routing
@@@ -782,7 -170,32 +589,65 @@@
engine indexed it and listed the page in the target's backlinks. The
preprocessor now skips exactly the code blocks and inline code the
renderer's parser reads as code. (#955)
+
++- `observations.title` is now sanitized before it is truncated, not after.
++ `title_hint` used to be cut to 80 chars in `ai-memory-hooks::payload`
++ *before* the sanitizer ever ran, so a secret straddling that cutoff was
++ often left as a fragment too short to match a built-in or `[sanitize]
++ extra_patterns` rule — landing in the title, its FTS index, and every
++ surface that renders titles (session pages, briefings, handoffs, search)
++ unredacted, even though the same observation's body was correctly scrubbed
++ first. `title_hint` extraction now keeps the full first line untruncated;
++ `Sanitized::new` scrubs the title and only then applies the 80-char display
++ cap (`ai_memory_core::sanitize::truncate_for_title`), mirroring the order
++ the body already used. (#982)
++- The `/web` page view keeps a leading H1 that is not the page title. It
++ dropped the body's first H1 whatever it said, as a duplicate of the title
++ in the header, but a frontmatter `title:` outranks the H1 and a setext H1
++ never names the page, so a heading like `# Token refresh after sleep`
++ under `title: Auth decisions` vanished from the rendered page. An H1 that
++ repeats the title is still dropped. (#967)
++- Shell-command `ignore_paths` matching no longer joins an argument vector
++ before splitting it, which broke a path with spaces (`["cat", "private
++ notes/x.md"]`) apart and let one element's stray quote hide the elements
++ after it; each element now counts whole and is split on its own. An invalid
++ `.ai-memory.toml` now makes a shell command metadata-only, like a file tool,
++ instead of keeping its command and output, including one whose command is
++ missing or unparseable (`web_search` runs nothing and is still kept), and the
++ server now does the same when it cannot parse the client's capture marker. A
++ long `bash -lc "<script>"` element is read only as words, not also as one
++ path, so it can no longer exhaust the match budget and drop an innocuous
++ event. Applies to the native hook and the generated plugins; the server
++ accepts the new metadata-only shell form, so upgrade it together with them
++ (an older server drops such an event). (#973)
++- `ai-memory-importer omc-wiki` now reads the frontmatter of a page saved
++ with CRLF line endings or a UTF-8 BOM, as a wiki checked out on Windows
++ with `core.autocrlf=true` is. It missed the fence, so the page's kind,
++ tier, tags and pin were dropped and the YAML block was imported as the
++ top of the body; the fence check now matches the wiki's own parser.
++ (#970)
++- `ai-memory serve --web-ui-dir` no longer panics at startup when the
++ custom SPA's `index.html` starts with a UTF-8 BOM, or has any other
++ non-ASCII text before `<head>`. The `<base href>` injection scanned the
++ page a byte at a time and sliced inside the multi-byte character
++ ("byte index 1 is not a char boundary"); it now steps a whole
++ character. (#969)
++- The `/api/v1` single-page route's `ETag` now covers the whole JSON it
++ returns. It hashed only the markdown body and author, so pinning a page,
++ a frontmatter edit, or a new backlink changed the response without
++ changing the tag, and a client revalidating with `If-None-Match` got
++ `304` and kept the stale page. (#971)
+ - A wikilink or markdown link written inside an inline code span is no
+ longer indexed as a link. The engine skipped only fenced blocks, so a
+ page showing the syntax as code (`` `[[other-project:notes/x]]` ``) got a
+ lint `broken_link` finding for a dependency it does not have, and a
+ local example listed the page in the target's backlinks, while the web
+ page rendered neither as a link. A link whose label is code
+ (`` [`foo`](foo.md) ``) is still indexed. (#968)
+ - `export-okf`'s generated `index.md` no longer has a prose sentence outside
+ its list structure. Some strict OKF v0.2 validators read §11.3 as
+ rejecting it. (#979)
-- `export-okf` now backfills a `title` (derived, same as `derive_title`) and
- a `description` (from `summary`, else `abstract`) on an exported page when
- missing, so a generic OKF consumer sees both §4.1-recommended keys. The
- backfill only ever changes the bundle's copy, never the on-disk wiki file.
- (#979)
-- `export-okf` now rewrites a page's local `[[wikilink]]`s to bundle-relative
- standard Markdown links, since a generic OKF consumer has no idea what
- `[[decisions/b.md]]` means. A cross-project or cross-workspace wikilink has
- no Markdown equivalent and ships untouched, as literal `[[...]]` text.
- (#979)
-- `sources[].author` in conformed frontmatter is now `process:<agent>`
- (e.g. `process:claude-code`) instead of a bare agent name, matching the
- OKF actor grammar's `process:<id>` form for automated processes (#979).
- This changes the default `sources[].author` value written for every page
- from now on; already-written pages are not retroactively rewritten.
+
## [2.4.1] - 2026-09-25
### Changed
diff --cc crates/ai-memory-cli/src/commands/render_shared.rs
index 595a9d17,8bc61b99..5b2f496e
--- a/crates/ai-memory-cli/src/commands/render_shared.rs
+++ b/crates/ai-memory-cli/src/commands/render_shared.rs
@@@ -294,17 -284,9 +299,17 @@@ function captureShellArguments(word: st
// Lexical only, like the native hook: nothing is expanded or executed, so
// variables, command substitution, and `cd` state are not followed. A tool's
// own `workdir` replaces the event cwd for relative arguments.
- function captureMatchCommand(command: string, config: CaptureConfig, workdir?: string): boolean | undefined { const budget = { work: 0 }; const home = homedir(); const base = workdir === undefined ? config.base : /^(?:\/|\\\\|[A-Za-z]:[\\/])/.test(workdir) ? workdir : config.base && captureJoin(config.base, workdir); for (const word of captureShellWords(command)) for (const argument of captureShellArguments(word)) { const expanded = argument.startsWith("~/") ? captureJoin(home, argument.slice(2)) : argument; if ([...expanded].length > CAPTURE_MAX_PATH_CHARS) continue; const absolute = /^(?:\/|\\\\|[A-Za-z]:[\\/])/.test(expanded); if (!absolute && !base) continue; const candidate = captureNormalize(absolute ? expanded : captureJoin(base, expanded)); if (!candidate) continue; const glob = /[*?]/.test(candidate.path); for (const pattern of config.patterns) { if (candidate.windows !== pattern.windows) continue; const under = captureStartsWith(candidate.path, pattern.prefix, pattern.windows); if (!under && !glob) continue; if (under) { const directory = pattern.directory ? captureGlob(pattern.directory, candidate.path, pattern.windows, budget) : false; if (directory !== false) return directory; const match = captureGlob(pattern.path, candidate.path, pattern.windows, budget); if (match !== false) return match; } if (glob) { const reaches = captureGlobReaches(candidate.path, pattern.prefix, pattern.windows, budget); if (reaches !== false) return reaches; } } } return false; }
- function captureTool(payload: Record<string, unknown>): { family: CaptureProtocol["tool_family"]; paths?: string[]; extraction: CaptureProtocol["extraction_state"]; callID?: string; command?: string; workdir?: string } { const name = typeof payload.tool === "string" ? payload.tool.toLowerCase() : ""; const args = payload.args as Record<string, unknown> | undefined; const call = ["tool_use_id","toolUseId","tool_call_id","toolCallId","call_id","callId","callID"].map((k) => payload[k]).find((v): v is string => typeof v === "string" && /^[A-Za-z0-9_.-]{1,128}$/.test(v)); if (["search","grep","glob","find","list","ls","list_files","read_dir"].includes(name)) return { family: "search-list", extraction: "not-applicable", callID: call }; if (["bash","shell","shell_command","exec","execute","run_command","web_search","terminal","execute_bash","execute_cmd"].includes(name)) return { family: "non-file", extraction: "extracted", callID: call, command: captureShellCommand(args), workdir: typeof args?.workdir === "string" && args.workdir.trim() ? args.workdir : undefined }; if (!["read","write","edit","apply_patch","notebookedit","notebook_edit","create_file","delete_file","rename_file","move_file","multi_edit","multiedit","replace","replace_all"].includes(name)) return { family: "unknown", extraction: "extracted", callID: call }; const direct = (o: any): string[] | undefined => { if (!o || typeof o !== "object") return undefined; const r: string[] = []; for (const k of ["file_path","filePath","path","absolute_path","AbsolutePath","notebook_path"]) if (k in o) { if (typeof o[k] !== "string") return undefined; r.push(o[k]); } if ("paths" in o) { if (!Array.isArray(o.paths) || o.paths.some((x: unknown) => typeof x !== "string")) return undefined; r.push(...o.paths); } return r.length && r.length <= CAPTURE_MAX_CANDIDATES ? r : undefined; }; let paths = direct(args); if (["multi_edit","multiedit","replace_all"].includes(name)) { const entries = args?.edits ?? args?.replacements; if (!Array.isArray(entries) || !entries.length || entries.length > CAPTURE_MAX_CANDIDATES) paths = undefined; else { paths = paths ?? []; for (const entry of entries) { const more = direct(entry); if (!more || paths.length + more.length > CAPTURE_MAX_CANDIDATES) { paths = undefined; break; } paths.push(...more); } } } if (!paths || paths.some((p) => !p.trim() || [...p].length > CAPTURE_MAX_PATH_CHARS)) return { family: "file", extraction: "missing-or-malformed", callID: call }; return { family: "file", paths, extraction: "extracted", callID: call }; }
+ function captureMatchCommand(command: string | string[], config: CaptureConfig, workdir?: string): boolean | undefined { const budget = { work: 0 }; const home = homedir(); const base = workdir === undefined ? config.base : /^(?:\/|\\\\|[A-Za-z]:[\\/])/.test(workdir) ? workdir : config.base && captureJoin(config.base, workdir); for (const word of captureShellWordList(command)) for (const argument of captureShellArguments(word)) { const expanded = argument.startsWith("~/") ? captureJoin(home, argument.slice(2)) : argument; if ([...expanded].length > CAPTURE_MAX_PATH_CHARS) continue; const absolute = /^(?:\/|\\\\|[A-Za-z]:[\\/])/.test(expanded); if (!absolute && !base) continue; const candidate = captureNormalize(absolute ? expanded : captureJoin(base, expanded)); if (!candidate) continue; const glob = /[*?]/.test(candidate.path); for (const pattern of config.patterns) { if (candidate.windows !== pattern.windows) continue; const under = captureStartsWith(candidate.path, pattern.prefix, pattern.windows); if (!under && !glob) continue; if (under) { const directory = pattern.directory ? captureGlob(pattern.directory, candidate.path, pattern.windows, budget) : false; if (directory !== false) return directory; const match = captureGlob(pattern.path, candidate.path, pattern.windows, budget); if (match !== false) return match; } if (glob) { const reaches = captureGlobReaches(candidate.path, pattern.prefix, pattern.windows, budget); if (reaches !== false) return reaches; } } } return false; }
+ function captureTool(payload: Record<string, unknown>): { family: CaptureProtocol["tool_family"]; paths?: string[]; extraction: CaptureProtocol["extraction_state"]; callID?: string; command?: string | string[]; shell?: boolean; workdir?: string } { const name = typeof payload.tool === "string" ? payload.tool.toLowerCase() : ""; const args = payload.args as Record<string, unknown> | undefined; const call = ["tool_use_id","toolUseId","tool_call_id","toolCallId","call_id","callId","callID"].map((k) => payload[k]).find((v): v is string => typeof v === "string" && /^[A-Za-z0-9_.-]{1,128}$/.test(v)); if (["search","grep","glob","find","list","ls","list_files","read_dir"].includes(name)) return { family: "search-list", extraction: "not-applicable", callID: call }; if (["bash","shell","shell_command","exec","execute","run_command","web_search","terminal","execute_bash","execute_cmd"].includes(name)) return { family: "non-file", extraction: "extracted", callID: call, command: captureShellCommand(args), shell: name !== "web_search", workdir: typeof args?.workdir === "string" && args.workdir.trim() ? args.workdir : undefined }; if (!["read","write","edit","apply_patch","notebookedit","notebook_edit","create_file","delete_file","rename_file","move_file","multi_edit","multiedit","replace","replace_all"].includes(name)) return { family: "unknown", extraction: "extracted", callID: call }; const direct = (o: any): string[] | undefined => { if (!o || typeof o !== "object") return undefined; const r: string[] = []; for (const k of ["file_path","filePath","path","absolute_path","AbsolutePath","notebook_path"]) if (k in o) { if (typeof o[k] !== "string") return undefined; r.push(o[k]); } if ("paths" in o) { if (!Array.isArray(o.paths) || o.paths.some((x: unknown) => typeof x !== "string")) return undefined; r.push(...o.paths); } return r.length && r.length <= CAPTURE_MAX_CANDIDATES ? r : undefined; }; let paths = direct(args); if (["multi_edit","multiedit","replace_all"].includes(name)) { const entries = args?.edits ?? args?.replacements; if (!Array.isArray(entries) || !entries.length || entries.length > CAPTURE_MAX_CANDIDATES) paths = undefined; else { paths = paths ?? []; for (const entry of entries) { const more = direct(entry); if (!more || paths.length + more.length > CAPTURE_MAX_CANDIDATES) { paths = undefined; break; } paths.push(...more); } } } if (!paths || paths.some((p) => !p.trim() || [...p].length > CAPTURE_MAX_PATH_CHARS)) return { family: "file", extraction: "missing-or-malformed", callID: call }; return { family: "file", paths, extraction: "extracted", callID: call }; }
-function capturePolicy(payload: Record<string, unknown>, cwd: string | undefined): { disposition: CaptureDisposition; protocol?: CaptureProtocol; payload: Record<string, unknown> } { const markerPresent = !!findMarker(cwd); if (CAPTURE_MODE === "allowlist" && !markerPresent) return { disposition: "drop", payload }; const config = captureConfig(cwd); const tool = captureTool(payload); let disposition: CaptureDisposition = "keep"; if (config.state === "invalid" && (tool.family === "file" || tool.shell)) disposition = "metadata-only"; else if (config.state === "active" && tool.family === "search-list") disposition = "drop"; else if (config.state === "active" && tool.family === "file") { if (!tool.paths) disposition = "metadata-only"; else { const candidates = tool.paths.map((p) => captureNormalize(/^(?:\/|\\\\|[A-Za-z]:[\\/])/.test(p) ? p : captureJoin(config.base, p))); if (candidates.some((p) => !p)) disposition = "metadata-only"; else { const budget = { work: 0 }; captureMatch: for (const candidate of candidates as { path: string; windows: boolean }[]) for (const pattern of config.patterns) { if (candidate.windows !== pattern.windows) continue; if (pattern.directory && captureGlob(pattern.directory, candidate.path, pattern.windows, budget)) { disposition = "drop"; break captureMatch; } const match = captureGlob(pattern.path, candidate.path, pattern.windows, budget); if (match === undefined) { disposition = "metadata-only"; break; } if (match) { disposition = "drop"; break captureMatch; } } } } } else if (config.state === "active" && tool.family === "non-file" && tool.command !== undefined && captureMatchCommand(tool.command, config, tool.workdir) !== false) disposition = "drop"; if (config.state === "inactive") return { disposition, payload }; const protocol: CaptureProtocol = { version: CAPTURE_POLICY_V1, disposition, policy_state: config.state, tool_family: tool.family, path_count: tool.paths?.length ?? 0, extraction_state: tool.extraction }; if (disposition === "metadata-only") { const session = payload.sessionID ?? payload.sessionId ?? payload.session_id; const routing = typeof payload.cwd === "string" ? payload.cwd : cwd; return { disposition, protocol, payload: { ...(typeof session === "string" ? { session_id: session } : {}), ...(typeof routing === "string" ? { cwd: routing } : {}), tool_family: tool.family, tool_name: tool.family, ...(tool.callID ? { tool_call_id: tool.callID } : {}), _ai_memory_capture: protocol } }; } if (disposition === "keep") return { disposition, protocol, payload: { ...payload, _ai_memory_capture: protocol } }; return { disposition, protocol, payload }; }
+// An external lifecycle owner (`AI_MEMORY_CAPTURE_OWNER`, any value that is
+// non-empty after trimming) takes over capture for this process: the gate runs
+// before the capture-policy marker scan, so no disposition work, no marker read
+// by this policy, and no queue write, spool write, or capture POST downstream.
+// It does not reach the consumer's own routing work (`applyMarkerParams` runs
+// earlier in postHook), and context delivery (`fetchHandoff`) is a separate
+// path that stays live.
+function captureOwnedExternally(): boolean { const owner = typeof process === "undefined" ? undefined : process.env?.AI_MEMORY_CAPTURE_OWNER; return typeof owner === "string" && owner.trim() !== ""; }
- function capturePolicy(payload: Record<string, unknown>, cwd: string | undefined): { disposition: CaptureDisposition; protocol?: CaptureProtocol; payload: Record<string, unknown> } { if (captureOwnedExternally()) return { disposition: "drop", payload }; const markerPresent = !!findMarker(cwd); if (CAPTURE_MODE === "allowlist" && !markerPresent) return { disposition: "drop", payload }; const config = captureConfig(cwd); const tool = captureTool(payload); let disposition: CaptureDisposition = "keep"; if (config.state === "invalid" && tool.family === "file") disposition = "metadata-only"; else if (config.state === "active" && tool.family === "search-list") disposition = "drop"; else if (config.state === "active" && tool.family === "file") { if (!tool.paths) disposition = "metadata-only"; else { const candidates = tool.paths.map((p) => captureNormalize(/^(?:\/|\\\\|[A-Za-z]:[\\/])/.test(p) ? p : captureJoin(config.base, p))); if (candidates.some((p) => !p)) disposition = "metadata-only"; else { const budget = { work: 0 }; captureMatch: for (const candidate of candidates as { path: string; windows: boolean }[]) for (const pattern of config.patterns) { if (candidate.windows !== pattern.windows) continue; if (pattern.directory && captureGlob(pattern.directory, candidate.path, pattern.windows, budget)) { disposition = "drop"; break captureMatch; } const match = captureGlob(pattern.path, candidate.path, pattern.windows, budget); if (match === undefined) { disposition = "metadata-only"; break; } if (match) { disposition = "drop"; break captureMatch; } } } } } else if (config.state === "active" && tool.family === "non-file" && tool.command !== undefined && captureMatchCommand(tool.command, config, tool.workdir) !== false) disposition = "drop"; if (config.state === "inactive") return { disposition, payload }; const protocol: CaptureProtocol = { version: CAPTURE_POLICY_V1, disposition, policy_state: config.state, tool_family: tool.family, path_count: tool.paths?.length ?? 0, extraction_state: tool.extraction }; if (disposition === "metadata-only") { const session = payload.sessionID ?? payload.sessionId ?? payload.session_id; const routing = typeof payload.cwd === "string" ? payload.cwd : cwd; return { disposition, protocol, payload: { ...(typeof session === "string" ? { session_id: session } : {}), ...(typeof routing === "string" ? { cwd: routing } : {}), tool_family: tool.family, tool_name: tool.family, ...(tool.callID ? { tool_call_id: tool.callID } : {}), _ai_memory_capture: protocol } }; } if (disposition === "keep") return { disposition, protocol, payload: { ...payload, _ai_memory_capture: protocol } }; return { disposition, protocol, payload }; }
++function capturePolicy(payload: Record<string, unknown>, cwd: string | undefined): { disposition: CaptureDisposition; protocol?: CaptureProtocol; payload: Record<string, unknown> } { if (captureOwnedExternally()) return { disposition: "drop", payload }; const markerPresent = !!findMarker(cwd); if (CAPTURE_MODE === "allowlist" && !markerPresent) return { disposition: "drop", payload }; const config = captureConfig(cwd); const tool = captureTool(payload); let disposition: CaptureDisposition = "keep"; if (config.state === "invalid" && (tool.family === "file" || tool.shell)) disposition = "metadata-only"; else if (config.state === "active" && tool.family === "search-list") disposition = "drop"; else if (config.state === "active" && tool.family === "file") { if (!tool.paths) disposition = "metadata-only"; else { const candidates = tool.paths.map((p) => captureNormalize(/^(?:\/|\\\\|[A-Za-z]:[\\/])/.test(p) ? p : captureJoin(config.base, p))); if (candidates.some((p) => !p)) disposition = "metadata-only"; else { const budget = { work: 0 }; captureMatch: for (const candidate of candidates as { path: string; windows: boolean }[]) for (const pattern of config.patterns) { if (candidate.windows !== pattern.windows) continue; if (pattern.directory && captureGlob(pattern.directory, candidate.path, pattern.windows, budget)) { disposition = "drop"; break captureMatch; } const match = captureGlob(pattern.path, candidate.path, pattern.windows, budget); if (match === undefined) { disposition = "metadata-only"; break; } if (match) { disposition = "drop"; break captureMatch; } } } } } else if (config.state === "active" && tool.family === "non-file" && tool.command !== undefined && captureMatchCommand(tool.command, config, tool.workdir) !== false) disposition = "drop"; if (config.state === "inactive") return { disposition, payload }; const protocol: CaptureProtocol = { version: CAPTURE_POLICY_V1, disposition, policy_state: config.state, tool_family: tool.family, path_count: tool.paths?.length ?? 0, extraction_state: tool.extraction }; if (disposition === "metadata-only") { const session = payload.sessionID ?? payload.sessionId ?? payload.session_id; const routing = typeof payload.cwd === "string" ? payload.cwd : cwd; return { disposition, protocol, payload: { ...(typeof session === "string" ? { session_id: session } : {}), ...(typeof routing === "string" ? { cwd: routing } : {}), tool_family: tool.family, tool_name: tool.family, ...(tool.callID ? { tool_call_id: tool.callID } : {}), _ai_memory_capture: protocol } }; } if (disposition === "keep") return { disposition, protocol, payload: { ...payload, _ai_memory_capture: protocol } }; return { disposition, protocol, payload }; }
"##;
TEMPLATE.replace("__AI_MEMORY_CAPTURE_MODE__", capture_mode)
}
diff --cc crates/ai-memory-web/src/routes/api.rs
index 2c00bf6b,d2aaa922..540209d3
--- a/crates/ai-memory-web/src/routes/api.rs
+++ b/crates/ai-memory-web/src/routes/api.rs
@@@ -203,25 -189,38 +203,43 @@@ async fn page_handler
.read_page(meta.workspace_id, meta.project_id, &page_path)
.map_err(|_| not_found("page file not found"))?;
- // ETag is computed over the markdown body PLUS the resolved author
- // identity (P1.7). Author change without body change (e.g. operator
- // rotates a token then user A re-writes a previously-anonymous page)
- // must invalidate the cached response. SHA-256 over a stable
- // concatenation: body || "\n--\n" || username || "\n" || email.
- // The "\n--\n" separator prevents `body=foo, user=bar` from hashing
- // the same as `body=foobar, user=` if either ever happened to slide
- // empty.
- let mut hasher = Sha256::new();
- hasher.update(markdown.body.as_bytes());
- if let Some(author) = meta.author.as_ref() {
- hasher.update(b"\n--\n");
- hasher.update(author.username.as_bytes());
- hasher.update(b"\n");
- if let Some(email) = author.email.as_deref() {
- hasher.update(email.as_bytes());
- }
- }
- let digest = hasher.finalize();
+ let links = state
+ .reader
- .page_links(meta.workspace_id, meta.project_id, meta.path.clone())
++ .page_links(
++ meta.workspace_id,
++ meta.project_id,
++ meta.path.clone(),
++ viewer_of(viewer),
++ )
+ .await
+ .map_err(internal_error)?;
+
+ let page = ApiPage {
+ backlinks: links.backlinks,
+ body_markdown: markdown.body,
+ created_at: meta.created_at,
+ frontmatter: markdown.frontmatter,
+ kind: meta.kind,
+ links: links.links,
+ path: meta.path,
+ pinned: meta.pinned,
+ project: meta.project_name,
+ supersedes: meta.supersedes,
+ tier: meta.tier,
+ title: meta.title,
+ updated_at: meta.updated_at,
+ workspace: meta.workspace_name,
+ author: meta.author,
+ };
+ let json = serde_json::to_vec(&page).map_err(internal_error)?;
+
+ // The ETag is a SHA-256 of the JSON this route returns, so it changes
+ // whenever any of it does. It used to cover only the markdown body and
+ // the author (P1.7), but pinning a page, re-tiering or retitling it in
+ // frontmatter, and another page linking to it all change the response
+ // while the body stays byte-identical, and a client revalidating with
+ // the old tag was told 304 and kept the stale page.
+ let digest = Sha256::digest(&json);
let etag_hex = digest.iter().fold(String::with_capacity(64), |mut s, b| {
use std::fmt::Write as _;
let _ = write!(s, "{b:02x}");
diff --cc docs/security-boundaries.md
index 2f02b04a,d032bd48..7267b8bd
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@@ -35,26 -31,21 +35,26 @@@ boundary not yet built
| 5a | Pages shared: `author_id` is never a read filter (invariant #16) | `ai-memory-store/src/reader.rs` `search_pages`/`page_body_by_ids` — `author_id` is an attribution JOIN only, never a WHERE term | `multi_session.rs` — a page with a **non-null** `author_id` (operator A) is readable by operator B in the same project | STRONG |
| 5b | Page supersession (loser stays reachable) | `ai-memory-store/src/ops.rs` `upsert_page_in_tx` — demote `is_latest=0` (never delete) + `supersedes` chain | `multi_session.rs` `concurrent_writes_to_one_path_supersede_rather_than_destroy`; `retrieval_superseded.rs` | STRONG |
| 6 | Active-project pointer (PerActor, no clobber) | `ai-memory-core/src/active_project.rs` `set_for`/`lookup_for` (fail-closed on `Mismatch`) | `active_project.rs` `parallel_harnesses_of_one_user_keep_separate_pointers`, `two_operators_never_read_each_others_pointer`, `a_session_mismatch_fails_closed_once_anything_has_been_keyed` | STRONG |
+| 6b | Native `_meta` routing coordinate is routing-only (never grants identity) | `ai-memory-mcp/src/server.rs` `attach_native_session` reads only `_meta["ai.opencode/sessionID"]` into `ActorKey.session_id` (trimmed, non-empty-string-validated); `user` still comes from the authenticated `ActorContext`, so a forged `_meta` cannot cross a user/scope boundary — it only selects a session slot behind the existing `active_project` guard | `server.rs` `native_session_metadata_is_routing_only_and_preserves_precedence`, `native_session_metadata_validates_strings_without_granting_identity`; `autoscope_multiuser.rs` `native_metadata_routes_concurrent_reads_and_writes_to_hook_workspaces` (#864) | STRONG |
- | 7 | Sanitizer trust boundary (invariant #6) | `ai-memory-core/src/sanitize.rs` `Sanitized<T>` (private field, only `sanitize()` ctor); `WriterHandle::insert_observation` requires `Sanitized`; `ops` crate-private | Structural (compile-time) + `store/src/lib.rs` `insert_observation_boundary_scrubs_before_disk` + sanitizer scrub unit tests | STRONG (structural) |
+ | 7 | Sanitizer trust boundary (invariant #6) | `ai-memory-core/src/sanitize.rs` `Sanitized<T>` (private field, only `sanitize()` ctor); `Sanitized::new` scrubs the title *before* the 80-char display cap; `WriterHandle::insert_observation` requires `Sanitized`; `ops` crate-private | Structural (compile-time) + `store/src/lib.rs` `insert_observation_boundary_scrubs_before_disk` + sanitizer scrub unit tests + `ai-memory-core::sanitize` `title_is_scrubbed_before_the_80_char_cap_runs` + `ai-memory-hooks::router` `issue_980_user_prompt_title_is_sanitized_before_truncated` (a secret straddling the 80-char boundary is redacted, not stored truncated; #980) | STRONG (structural) |
| 8a | Messaging: recipient-only visibility | `ai-memory-store/src/ops.rs` pop target-select + `reader.rs` `list_messages` (`to_*` predicate) | `agent_messages.rs` `a_message_is_only_visible_to_its_recipient`; `agent_messages_tools.rs` non-recipient cannot pop | STRONG |
| 8b | Messaging: cancel-own-only | `ai-memory-store/src/ops.rs` `cancel_messages` (AND-gated on `from_*` sender coordinate) | `agent_messages.rs` — whole-outbox **and** a foreign **specific-id** cancel refused | STRONG |
| 8c | Messaging: pop-exactly-once | `ai-memory-store/src/ops.rs` `pop_message_in_transaction` atomic CAS `WHERE state='pending'` | `agent_messages.rs` — sequential **and** `tokio::join!` concurrent double-pop yields exactly one `Some` | STRONG |
| 8d | Messaging: inferred-scope read is diagnosed (#854) | `scope.rs` `is_inferred`; `server.rs` `inferred_scope_hint` on empty pop/list | `agent_messages_briefing.rs` `no_scope_pop_that_misses_the_mail_is_diagnosed_not_a_silent_null` | STRONG |
| 9 | Scope resolution fail-closed | `ai-memory-store/src/scope.rs` no-create `lookup_existing_*`; create only via `create_explicit_scope` | `scope.rs` no-auto-create + `unscoped_write_with_unresolvable_coordinate_errors` | STRONG |
-| 10 | Destructive-op live-process refusal + confirm flags (invariant #9) | `ai-memory-cli/src/commands/process_guard.rs` `sibling_processes` + confirm flags in `reset`/`restore`/`reindex`/`uninstall --purge-data`/`purge_project` | `admin_purge.rs` confirm→400; `removal.rs` — injected live-sibling makes each destructive command bail before touching the data dir | STRONG |
-| 10b | Session purge is scope+owner-bound (no cross-session/project over-delete) | `ai-memory-store/src/ops.rs` `purge_session` — selection scoped to `(workspace_id, project_id)` and keyed on this session's own `summary_page_id` **or** `path='sessions/<sid>.md'` + `json_extract(frontmatter_json,'$.session_id')=<sid>` (frontmatter owner, not the recursive latest-chain); `in_scope==0 → NotFound` fail-closed; whole op in one transaction | `ops.rs` `purge_session_leaves_a_sibling_session_in_the_same_project_intact`, `…refuses_a_session_from_another_project_and_deletes_nothing`, `…refuses_a_session_from_another_workspace`, `…does_not_delete_an_identically_pathed_page_in_another_project`, `…removes_older_summary_versions_without_deleting_prior_manual_page` (#862) | STRONG |
+| 10 | Destructive-op live-process refusal + confirm flags (invariant #9); `purge-project`'s `dry_run` always wins over `confirm` so a preview request can never become destructive | `ai-memory-cli/src/commands/process_guard.rs` `sibling_processes` + confirm flags in `reset`/`restore`/`reindex`/`uninstall --purge-data`/`purge_project`; `admin.rs` `handle_purge_project` checks `req.dry_run` unconditionally, before `req.confirm`, mirroring `reclaim-ledger-versions` | `admin_purge.rs` confirm→400; `removal.rs` — injected live-sibling makes each destructive command bail before touching the data dir; `admin_purge.rs` `purge_project_confirm_true_and_dry_run_true_still_only_previews` — `{"confirm": true, "dry_run": true}` deletes nothing (the regression this row now also covers); `ops.rs` `purge_project_dry_run_changes_nothing` — every project-scoped row count, the `purged_scopes` tombstone, and the `audit_log` row are identical before/after a `PurgeMode::Preview` run; `ops.rs` `purge_project_counts_collateral_damage_in_another_project` and `admin_purge.rs` `purge_project_dry_run_and_confirmed_purge_both_report_collateral_damage_in_another_project` — a purge of project P collaterally deletes an observation, and orphans a handoff's session reference, in a *different* project Q (via `sessions` cascading out of P), and both the preview and the confirmed report count it | STRONG |
+| 10b | Session purge is scope+owner-bound (no cross-session/project over-delete); `purge-session`'s `dry_run` always wins over `confirm`, same as `purge-project` | `ai-memory-store/src/ops.rs` `purge_session` — selection scoped to `(workspace_id, project_id)` and keyed on this session's own `summary_page_id` **or** `path='sessions/<sid>.md'` + `json_extract(frontmatter_json,'$.session_id')=<sid>` (frontmatter owner, not the recursive latest-chain); `in_scope==0 → NotFound` fail-closed; whole op in one transaction; `admin.rs` `handle_purge_session` checks `req.dry_run` unconditionally, before `req.confirm` | `ops.rs` `purge_session_leaves_a_sibling_session_in_the_same_project_intact`, `…refuses_a_session_from_another_project_and_deletes_nothing`, `…refuses_a_session_from_another_workspace`, `…does_not_delete_an_identically_pathed_page_in_another_project`, `…removes_older_summary_versions_without_deleting_prior_manual_page` (#862); `admin_purge.rs` `purge_session_confirm_true_and_dry_run_true_still_only_previews` — `{"confirm": true, "dry_run": true}` deletes nothing; `ops.rs` `purge_session_dry_run_changes_nothing` — every table a session purge touches, the `purged_sessions` tombstone, and the `audit_log` row are identical before/after a `PurgeMode::Preview` run; `ops.rs` `purge_session_counts_collateral_damage_in_another_project` and `admin_purge.rs` `purge_session_dry_run_and_confirmed_purge_both_report_collateral_damage_in_another_project` — purging session S collaterally deletes an observation, and orphans a handoff's session reference, in a *different* project (via `S`'s own id cascading), and both the preview and the confirmed report count it; `admin_purge.rs` `purge_session_dry_run_refuses_a_session_outside_its_named_scope` — the same session previewed under a different real project (same workspace) or a different real workspace whose project shares the name both 404 with no counts in the body, with the session's own scope as the 200 control | STRONG |
+| 10c | Ledger reclaim is content-gated, not filename-gated (invariant #16) | `ai-memory-store/src/ops.rs` `reclaim_ledger_versions` — a candidate row must pass `ai_memory_core::log_ledger::body_opens_with_log_ledger` on its own `body`, and only `is_latest=0 AND superseded_at IS NULL` rows are eligible, so decay-owned rows stay with `forget-sweep`; confirm gate in `admin.rs` `handle_reclaim_ledger_versions` | `reclaim_ledger_versions.rs` `a_prose_page_wearing_the_ledger_name_keeps_its_whole_version_chain`, `an_ordinary_page_chain_in_another_project_is_untouched`, `a_decay_tombstone_stays_with_the_sweep_that_owns_it`; `admin_reclaim_ledger_versions.rs` `deleting_without_confirm_is_refused_and_changes_nothing` (with dry-run and confirmed controls) | STRONG |
+| 10d | Workspace delete's own row counts are scope-bound to `workspace_id` (a workspace's *own* rows are never over- or under-counted by a sibling workspace's), its cross-workspace observation/handoff cascade is reported by both preview and confirm rather than prevented (same as `purge-project` one level down), the non-empty guard fails closed without `force`, and `delete-workspace`'s `dry_run` always wins | `ai-memory-store/src/ops.rs` `delete_workspace` — every direct count and the `DELETE FROM workspaces` itself are scoped by `workspace_id = ?1`; the two `collateral_*` counts are scoped by `workspace_id != ?1` so a row is counted as one or the other but never both; `projects_deleted > 0 && !force → WorkspaceNotEmpty` fail-closed, and a missing workspace is `NotFound`, both checked identically under `PurgeMode::Preview` and `PurgeMode::Commit`; whole op in one transaction; `admin.rs` `handle_delete_workspace` checks `req.dry_run` unconditionally, before building the confirmed path, mirroring `reclaim-ledger-versions`/`purge-project`; root-only gate is the shared `/admin/*` multi-user auth ladder, not a separate check | `admin_move.rs` `delete_workspace_dry_run_never_counts_a_different_workspaces_rows` — previewing workspace A counts only its own project/page/session/observation/handoff rows, not workspace B's (which holds two like-named projects and its own full row set), and a session living in B that stamps an observation directly into A is counted in A's own `observations_deleted`, never in `collateral_observations_deleted` (the two counts are mutually exclusive by construction); `admin_move.rs` `delete_workspace_force_true_and_dry_run_true_still_only_previews` — `{"force": true, "dry_run": true}` deletes nothing; `ops.rs` `delete_workspace_dry_run_changes_nothing` — every table's row count, including `workspaces` itself and the `purged_scopes` tombstone (the two tables a confirmed delete's own transaction writes to), is identical before/after a `PurgeMode::Preview` run; `ops.rs` `delete_workspace_dry_run_and_confirmed_delete_both_report_collateral_damage_in_another_workspace` and `admin_move.rs` of the same name — deleting workspace W collaterally deletes an observation, and orphans a handoff's session reference, in a *different* workspace (via `sessions` cascading out of W), and both the preview and the confirmed response count it identically — the cascade itself is reported, not blocked, by either; `admin_move.rs` `delete_workspace_dry_run_refuses_non_empty_without_force` / `delete_workspace_dry_run_nonexistent_workspace_returns_404` — same `409`/`404` a confirmed delete would give; `admin.rs` `multiuser_delete_workspace_dry_run_rejects_db_user_and_anonymous` — root reaches the preview handler (404 control), DB user gets 403, anonymous gets 401 | STRONG |
+| 10e | Reconcile-tombstone of a disk-deleted page is opt-in, soft, scope-bound, and false-positive-guarded (invariant #16, #929 delete-half) | `ai-memory-wiki/src/watcher.rs` — off by default (`[maintenance] reconcile_tombstones_deleted_pages`); a page is tombstoned only after its file is observed missing on two consecutive passes (streak resets if the path's `PageId` changed), re-verified against the live filesystem immediately before acting, with reserved/indexed-but-unwalked paths (`bootstrap.md`, `_meta.md`, `_pending/`, `sessions/*.md`) excluded and a circuit breaker that skips a whole scope when `> max(3, 50%)` of its pages look missing or a non-partial walk finds nothing; `ai-memory-store/src/ops.rs` `soft_delete_for_reconcile_if_latest` is a soft tombstone (`is_latest=0` + `superseded_at`, decay's shape) through the single writer actor in one transaction — never a filesystem write — scoped to the page's own `(workspace_id, project_id)` | `watcher.rs` `reconcile_delete_disabled_by_default_never_tombstones_a_missing_page`, `reconcile_delete_cross_project_isolation` (project A's deletion never tombstones project B's same-path page), `reconcile_tombstone_refuses_a_stale_latest_id`, `reconcile_tombstone_refuses_when_the_file_still_exists`, `reconcile_tombstone_never_touches_the_filesystem`; `ops.rs` `reconcile_tombstone_resurrects_instead_of_orphaning_on_recreate` | STRONG |
| 11a | Hook backpressure (202/429) + bounded fan-out (invariant #5) | `ai-memory-hooks/src/router.rs` semaphore→429, 202 immediately, `MAX_HOOK_BATCH_ITEMS`, bounded LRU limiter | `router.rs` `handle_hook_returns_429_when_ingest_saturated`, `ingest_rate_limiter_is_bounded` | STRONG |
- | 11b | Capture exclusions drop before storage | `ai-memory-hooks` `capture_policy.rs` `inspect`→`Drop` (before semaphore/spawn), including shell commands whose arguments name an ignored path (`match_command`); generated OpenCode/OMP/Pi/OpenClaw integrations mirror it in `render_shared.rs` `ts_capture_policy_v1` (`captureMatchCommand`) | `capture_policy.rs` per-agent `…honors_exclusions` tests, `shell_fixture_vectors` (shared `capture-policy.json` `shell` drop/keep vectors: tool aliases incl. OpenClaw/Devin `exec`, `workdir`, glob directories, Windows paths), `shell_tool_shapes_of_every_adapter_honor_exclusions`, `fixture_vectors` (incl. TS-adapter `bash`/`exec` vectors); `router.rs` `capture_protocol_shell_decisions_survive_server_reinspection`; `hook.rs` `shell_command_reading_an_ignored_path_is_dropped_before_spool`; `render_shared.rs` `generated_capture_policy_v1_node_runtime_evidence` (runs the same fixture sections against the emitted TypeScript; `#[ignore]` locally, run with `--ignored` under Node 24 by the Linux CI test job) | STRONG |
+ | 11b | Capture exclusions drop before storage | `ai-memory-hooks` `capture_policy.rs` `inspect`→`Drop` (before semaphore/spawn), including shell commands whose arguments name an ignored path (`match_command`; argv elements matched whole and tokenized); an invalid marker makes file and shell calls metadata-only, and the server admits a metadata-only shell body only under an invalid marker (`router.rs` `metadata_protocol_is_legal`); generated OpenCode/OMP/Pi/OpenClaw integrations mirror it in `render_shared.rs` `ts_capture_policy_v1` (`captureMatchCommand`) | `capture_policy.rs` per-agent `…honors_exclusions` tests, `shell_fixture_vectors` (shared `capture-policy.json` `shell` drop/keep vectors: tool aliases incl. OpenClaw/Devin `exec`, `workdir`, glob directories, Windows paths), `shell_tool_shapes_of_every_adapter_honor_exclusions`, `fixture_vectors` (incl. TS-adapter `bash`/`exec` vectors); `shell_matching_is_off_when_inactive_and_fails_closed_when_invalid_or_over_budget`; `router.rs` `capture_protocol_shell_decisions_survive_server_reinspection`, `capture_protocol_invalid_marker_shell_is_metadata_only` (active metadata-only shell refused, older client's invalid-marker keep stripped, commandless control kept), `capture_protocol_unparseable_marker_strips_shell_events` (server fallback for an unparseable marker), `capture_protocol_invalid_shell_metadata_claim_must_be_canonical` (a stripped shell claim with a path count or non-`extracted` state is refused); `capture_policy.rs` `invalid_marker_strips_shell_calls_with_unparseable_commands`, `long_bash_lc_script_in_argv_is_not_dropped_by_the_match_budget`; `hook.rs` `shell_command_reading_an_ignored_path_is_dropped_before_spool`; `render_shared.rs` `generated_capture_policy_v1_node_runtime_evidence` (runs the same fixture sections against the emitted TypeScript; `#[ignore]` locally, run with `--ignored` under Node 24 by the Linux CI test job) | STRONG |
| 11c | Capture hook ≤200ms budget (invariant #5) | `hooks/_lib.sh` capture path `curl --max-time 0.2` (context-fetch 1.0s and background drain 2.0s are separate, larger-budget paths) | none (shell-script timeout; hard to unit-test) — watch on any capture-path change | WATCH |
| 12 | Network/auth posture | `config.rs` loopback `DEFAULT_BIND`; `serve.rs` `validate_http_exposure`, `require_allowed_host`; `auth.rs` `require_bearer` | `serve.rs` host-guard (missing→400 / forged→403), non-loopback-requires-token; `auth.rs` wrong-token 401 | STRONG |
-| 13 | Managed-run transcript attribution (concurrent launches in one checkout, invariant #16) | `ai-memory-store/src/workstream.rs` `link_native_session` stamps `native_session_linked_at` on its own run only, both `finish` updates drop the stamp when the session changes, `run_status` reports it; `ai-memory-cli/src/commands/run.rs` `resolve_native_session_after_run` takes a linked session only when `ai-memory-workstream` `native_session_in_checkout` holds it for this checkout (OpenCode by recorded directory), and never falls back to a link it set aside | `multi_session.rs` `a_session_linked_by_one_managed_run_is_not_another_runs`; `run.rs` `a_session_linked_during_the_run_wins_over_discovery` (concurrent newer session, another checkout's link refused, no fallback to it, unlinked control); `transcript.rs` `native_session_in_checkout_checks_the_opencode_directory`; `store/src/lib.rs` `managed_run_status_reports_a_link_made_during_the_run` | PARTIAL: a run whose child links nothing still falls back to discovering the newest session in the checkout |
-| 14 | Client-supplied event time is bounded and self-scoped (#919) | `ai-memory-hooks/src/payload.rs` `HookEnvelope::occurred_at_micros` — a `/hook` caller's optional `occurred_at` must be `> 0` and `<= now + 5min`; it only sets the caller's *own* admitted session's `started_at`/`ended_at`/`created_at`, never another session/project/user, and the ingest dedup `seen_at`/TTL stays on `now` | `payload.rs` `occurred_at_micros_rejects_a_far_future_timestamp`, `…_rejects_non_positive_values`, `…_rejects_garbage_strings` | MEDIUM — self-scoped numeric bound; no cross-tenant surface (a client already controls its own content) |
-| — | Per-project authorization (#708) | proposal only — `docs/design-per-project-authz.md` (`authorize_project` choke point + unscoped-read/raw-id bypass classes) | none yet — the design's "Verification plan" tests (authz matrix, unscoped-read-leak, raw-id-authz, ship-inert) land WITH the code | FUTURE |
+| 13 | Managed-run transcript attribution (concurrent launches in one checkout, invariant #16) | `ai-memory-store/src/workstream.rs` `link_native_session` stamps `native_session_linked_at` on its own run only, both `finish` updates drop the stamp when the session changes, `run_status` reports it; `ai-memory-cli/src/commands/run.rs` `resolve_native_session_after_run` takes a linked session only when `ai-memory-workstream` `native_session_in_checkout` holds it for this checkout (OpenCode by recorded directory), never falls back to a link it set aside, and turns an `AmbiguousNativeSession` into a warning with nothing imported; `ai-memory-workstream/src/transcript.rs` `discover_crush` claims only the one top-level session created (or, with `--continue`, touched) during the run, and in a data directory outside the project only one that edited a file in it | `multi_session.rs` `a_session_linked_by_one_managed_run_is_not_another_runs`; `run.rs` `a_session_linked_during_the_run_wins_over_discovery` (concurrent newer session, another checkout's link refused, no fallback to it, unlinked control); `transcript.rs` `native_session_in_checkout_checks_the_opencode_directory`; `store/src/lib.rs` `managed_run_status_reports_a_link_made_during_the_run`; `run.rs` `ambiguous_crush_discovery_keeps_the_run`; `transcript.rs` `crush_discovery_claims_only_the_session_the_run_created`, `crush_discovery_in_a_shared_store_claims_only_an_edit_here` | PARTIAL: a run whose child links nothing still falls back to discovering the newest session in the checkout; Crush, which has no hooks, relies on that discovery alone and claims nothing when it is ambiguous |
+| 14 | Per-project authorization (#708) | `ai-memory-store/src/project_authz.rs` `authorize_project` / `ProjectAuthz::authorize` choke point (V68 `project_grants` + `projects.access_mode`, default `open`; V69 `projects.created_by` feeds `is_creator`); `scope.rs` `ScopeResolver::with_project_authz` (reader pool for reads, writer actor for writes) and its free forms `authorize_scope_for` / `*_guarded`, attached for every DB user by `ai-memory-mcp` `scope_resolver_as`, `ai-memory-web` `authorize_read` / `lookup_project`, and `ai-memory-hooks` (`grants.rs` `authorize_resolved` for run/workstream ids, the capture check in `router.rs`); read-shaped mutations resolve at `ProjectAccess::Write` (`resolve_existing_args(.., need)`); unscoped reads filtered before `LIMIT` by `reader.rs` `readable_repository_sql`; `WriterHandle::authorize_project` as defense in depth. Page ids are never taken from a caller (only derived from already-authorized hits), so there is no page-id entry point to guard | `tests/suite/project_authz.rs` (decision matrix, ship-inert, resolver gate); `tests/suite/access_mode.rs` `every_caller_against_both_modes`, `a_restricted_project_admits_the_team_and_refuses_the_outsider`, `new_projects_follow_the_server_default_and_admit_their_creator`; `scope.rs` `the_argument_shape_does_not_decide_the_level`, `a_user_reaches_only_what_they_were_granted`, `creating_authorizes_against_a_project_that_already_exists`, `a_refused_scope_fails_the_search_instead_of_shortening_it`; `grants.rs` `search_finds_only_what_the_viewer_may_read`, `the_limit_counts_only_what_the_viewer_may_see`, `the_workspace_handoff_comes_only_from_readable_repositories`; `ai-memory-mcp` `server.rs` `a_reader_may_read_everything_and_change_nothing`, `bob_cannot_read_alices_page_in_a_restricted_project`, `bob_cannot_find_alices_page_by_searching_in_a_restricted_project`, `bob_cannot_consolidate_a_session_in_alices_repository`, `a_restricted_projects_queues_need_write`; `ai-memory-hooks` `a_capture_needs_writer_on_the_repository_it_lands_in`, `session_start_delivers_nothing_from_a_repository_the_viewer_cannot_read`, `run_and_workstream_ids_only_answer_someone_who_may_reach_the_repository`; `ai-memory-web` `web_reads_honour_grants_in_a_restricted_project`, `metadata_shows_only_what_the_viewer_may_read` — each with a granted or open-project control, and proven to fail with the choke point (18 tests) or the SQL filter (9 tests) neutralized | STRONG — slice 3 closed both bypass classes (unscoped reads, raw-id entry points) and added the root-only management surface. Out of scope by design: per-project administrators (granting/restricting is root-only), and access modes, creators and grants live only in SQLite, so `reindex` resets them |
+| 14b | Repository identity routing (#708) | `ai-memory-store/src/ops.rs` `resolve_project_by_identity` — one transaction; an identity already on a project is never overwritten; an unclaimed project is claimed only when the capturing user may write it (the choke point's `resolve_project_authz` on the same transaction), otherwise it is returned unclaimed; a different identity under the same name splits into a new project with no shared `repo_path`; `ai-memory-hooks/src/router.rs` `cache_key_for` keys the path cache by identity too; `ai-memory-core/src/repository_identity.rs` strips credentials from remote URLs client-side, and the server accepts only the routing rungs (`explicit`, `git_remote`) from the wire | `tests/suite/identity_resolution.rs` `an_outsider_cannot_take_an_unclaimed_projects_identity` (control: `an_existing_project_is_claimed_in_place`), `two_unrelated_repositories_with_one_folder_name_stay_apart`, `a_created_or_split_project_admits_its_creator`; `router.rs` `one_path_with_two_remotes_is_two_projects`, `two_api_checkouts_with_different_remotes_get_two_projects` (a manifest rung on the wire is ignored); `repository_identity.rs` credential and normalisation tables — the claim guard and the cache key each proven to fail their test when removed | STRONG — first claimant wins: in a restricted workspace a user who creates a project under a remote identity first holds it until root grants others |
+| 14c | Client-supplied event time is bounded and self-scoped (#919) | `ai-memory-hooks/src/payload.rs` `HookEnvelope::occurred_at_micros` — a `/hook` caller's optional `occurred_at` must be `> 0` and `<= now + 5min`; it only sets the caller's *own* admitted session's `started_at`/`ended_at`/`created_at`, never another session/project/user, and the ingest dedup `seen_at`/TTL stays on `now` | `payload.rs` `occurred_at_micros_rejects_a_far_future_timestamp`, `…_rejects_non_positive_values`, `…_rejects_garbage_strings` | MEDIUM — self-scoped numeric bound; no cross-tenant surface (a client already controls its own content) |
## Keeping this current (the standing protocol)