Skip to content

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

Rust

Merge PR #873 into main

AkitaOnRailsb55e7847f356
diff --cc CHANGELOG.md
index 1c6271ff,9e852b42..437d1df9
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -7,1467 -7,18 +7,1478 @@@ and this project adheres to [Semantic V
## [Unreleased]
+ ### Added
+ - `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. On a 102-query golden set 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 — the
+ hosted mean sat on the server's 20 s completion timeout, which made the
+ reranker stall every query before falling back in production.
+
### Fixed
+- 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)
+- `memory_query` now embeds the search text with `embed_query` rather than
+ the generic `embed()` method. Google's embedder implements `embed()` as
+ `embed_document` (`RETRIEVAL_DOCUMENT`), the same task type used when
+ indexing wiki pages, so hybrid search compared a document vector to
+ document vectors and the vector stream could not separate query from
+ passage. Indexed writes are unchanged; only the query-side helper moves
+ onto `RETRIEVAL_QUERY`. Symmetric embedders (OpenAI, Voyage, local) keep
+ the same vector they already returned from `embed()`. (#861)
+- 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)
+
+## [2.4.0] - 2026-09-21
+
+### Security
+- Bumped `rmcp` to 2.x (2.2.0), resolving three MCP transport advisories:
+ GHSA-9pj6-vhgr-3mwh (unauthenticated Streamable-HTTP session-table leak /
+ DoS), GHSA-33f5-2c5q-wgwj (missing OAuth resource-field validation), and
+ GHSA-9g45-5xwm-f3wc (custom headers leaking to cross-origin redirect
+ targets). Behavior-preserving: the only source change is the
+ `rmcp::model::Content` → `ContentBlock` rename (imported under the prior
+ name), the feature set is unchanged, and the 23-tool MCP surface is
+ unaffected. (#794)
+
+### Added
+- macOS menu bar companion (`companions/ai-memory-macos`) that bundles the
+ `ai-memory` binary and `hooks/` tree, governs the existing LaunchAgent, and
+ opens the built-in web UI, `ai-memory status`, `config.toml`, the data
+ directory, and logs. Durable memory stays in
+ `~/Library/Application Support/ai-memory`; replacing the `.app` does not
+ rewrite it. Documented as a README quick-start, an
+ [`install.md`](docs/install.md#macos-menu-bar-app) path, a cookbook
+ recipe, and [`docs/macos.md`](docs/macos.md) Scenario D. (#809)
+- LLM "dream" pass — cross-session rewrite/merge of cold clusters, scheduled on
+ idle (design-memory-aging.md buckets B2/B3/B4). Where A3 collapses
+ near-duplicate cold clusters *extractively* (zero-LLM, keep-token union), the
+ dream pass hands each cold cluster to the configured provider to be rewritten
+ into ONE coherent page. It is **opt-in LLM, OFF by default, and gated on an R2
+ number before it may default on**: it runs only when the new `[dream] enabled`
+ flag is set AND a provider AND an embedder are configured — a provider-less
+ store keeps the zero-LLM A3 path untouched (invariant #13). **It never deletes
+ a source** (invariant #16): the highest-retention member is rewritten and every
+ merged-away member is *superseded* with a merge-note stub pointing at it, so the
+ full pre-merge body stays reachable via the supersession chain + git and
+ `restore-page` recovers it; `page_evidence` (`reconsolidation` +
+ `b2_dream:<id>`) records which members fed each merge (the hallucinated-merge
+ guard). The rewrite routes through the existing gated apply path
+ (`preflight_admission(Consolidate)` → `Wiki::apply_batch`, single-writer actor,
+ invariant #2) with **`dry_run` first** (a dry run returns the plan and calls
+ neither the LLM nor the writer), and uses **JSON-schema structured output only**
+ (invariant #7). Scheduling (B3) runs the pass only after a configurable idle
+ window with no client activity and **cancels it the moment the operator
+ returns** (a cheap cancellation flag polled between clusters), bounded to a
+ capped number of clusters per run (invariant #5). Work is ordered
+ **surprisal-first** (B4): most-novel clusters — those farthest from the nearest
+ existing page — first. Every run returns an observable `DreamReport` (clusters
+ considered, merged, pages rewritten/superseded, skipped, cancelled) so a bad
+ run is never silent. New `[dream]` config section; no new migration (reuses
+ `page_evidence` + supersession); no new MCP tool (still 23) (#816).
+- Belief-strength confidence over the `page_evidence` substrate
+ (design-memory-aging.md bucket B1 / design-hindsight-borrowings.md §3): a
+ read-time, **zero-LLM** `confidence` derived per page version from its
+ evidence — distinct supporting sessions (breadth, not raw count), recency of
+ the newest sighting, and live `contradicts` count — bounded to
+ `[0.0, 0.95]`. It is **exposed inertly** everywhere it helps diagnosis:
+ `memory_query(explain=true)` now reports `confidence` and `evidence_count`
+ per hit (and `belief_factor` when folding is on), and `memory_status` reports
+ the project's `evidence_rows` count — none of which changes ranking. It can
+ optionally be **folded into ranking authority** as one more bounded factor
+ inside the existing `[0.55, 1.50]` clamp (never a new multiplier tower) via
+ the new `[retrieval] belief_authority_weight` config key, which **defaults to
+ `0.0` (OFF)** so upgrades rank byte-identically. The anti-entrenchment guards
+ are baked in: breadth weighting by distinct sessions, recency shading, a
+ hard confidence cap, and — the caller-side guard for invariant #16 — **a
+ supersession always wins regardless of evidence** (a superseded version's
+ stale evidence never boosts it, and confidence never gates whether a write or
+ correction takes). Turning the authority factor on is **gated on a positive
+ R2 delta** (retrieval-triple / QA), not yet performed (#815).
+- Zero-LLM contradiction detection surfaced through `memory_lint`
+ (design-memory-aging.md bucket A5): the lint pass now flags likely-conflicting
+ pages by cosine-similarity band. Cold knowledge pages (semantic / procedural)
+ whose already-stored embeddings sit in the **0.4–0.75 cosine-similarity band** —
+ "same topic, but not a near-duplicate", the shape of a likely contradiction
+ (a pair ≥ 0.75 is A3 dedup territory; < 0.4 is unrelated) — get an advisory
+ `contradiction` lint finding naming both pages, with timestamp-based
+ resolution advice (the newer page supersedes on a timestamp basis; reconcile).
+ It is fully **zero generative LLM**: it reads only existing embeddings and
+ cosine (invariant #13), so with no embedder configured — or no embeddings for
+ the configured `(provider, model, dim)` triple — it is a clean no-op, not an
+ error, and never a provider call. It runs on the user-invoked `memory_lint`
+ (MCP and admin) and is **advisory-only and non-destructive**: it emits a
+ finding and never deletes, edits, or supersedes a page (invariant #16), and
+ never persists an edge (the `links` table's `contradicts` edges are
+ body-derived and rewritten on every page write, so a programmatic edge would
+ be silently wiped) — hence **no new migration**, and no new MCP tool (still
+ 23). The scan is bounded: one embeddings load over the already-bounded cold
+ set, capped page and finding counts, deterministic ordering (invariant #2)
+ (#814).
+- Cold-cluster dedup of near-duplicate episodic pages (design-memory-aging.md
+ bucket A3): the forget-sweep can now cluster near-duplicate cold episodic
+ pages by embedding (cosine-distance DBSCAN with an adaptive k-distance eps,
+ `minPts = 2`) and collapse each cluster to one survivor — the highest-retention
+ member, its body the *extractive union* of the cluster's keep-tokens, so every
+ member's durable facts survive — superseding the other members with a merge
+ note that points at the survivor. It runs only over the bounded cold-episodic
+ candidate set the sweep already materialises (never O(N²) over the whole
+ corpus), is **opt-in and off by default** via `[decay] dedup_cold_clusters`
+ (a `false` default), and fully **zero generative LLM**: it reads only
+ already-stored embeddings, so with no embedder configured — or no embeddings
+ for the configured `(provider, model, dim)` triple — it is a clean no-op, not
+ an error. The eps is clamped to a conservative ceiling (`[decay] dedup_max_eps`,
+ default cosine distance ≈ 0.15) so it errs toward NOT merging. **Non-destructive
+ and reversible**: no source is ever hard-deleted — every merged-away member
+ stays reachable via the supersession chain and git history and is recoverable
+ with `restore-page` (invariant #16) — and the merge provenance is recorded in
+ `page_evidence`. Every run reports its collapses in the `SweepReport`. Reuses
+ existing tables: **no new migration**, and no new MCP tool (still 23). Ships
+ opt-in/off; the R2 recall no-regression proof is the gate before any future
+ default-on (#812).
+- Entropy / boilerplate pre-filter before consolidation (design-memory-aging.md
+ bucket A4): a pure, zero-LLM Shannon-entropy + boilerplate gate that skips
+ low-information session pages (near-empty, whitespace, single-character, or
+ highly-repetitive boilerplate) from the cross-session experience consolidation
+ pass *before* they reach the LLM prompt, the eval gate, or `apply_batch`.
+ It is **advisory and non-destructive** — a skipped page is not consolidated,
+ never deleted (invariant #16) — and **opt-in / off by default** via
+ `[auto_improve.scheduler.experience_entropy_filter]` (a `false` default with
+ conservative, validated thresholds tuned so a terse-but-informative note with
+ a file path and an error code is KEPT), so an upgrade changes no consolidation
+ output until an operator opts in. Every run surfaces the skip count in the
+ experience report warnings. No schema change and no new MCP tool (still 23)
+ (#812).
+- Extractive tier-down of cold episodic pages (design-memory-aging.md bucket
+ A2): instead of evicting a cold episodic page, the forget-sweep can now
+ *compact* it — keeping the L0 frontmatter `abstract:`, an L1 first-paragraph
+ summary, and an L2 regex-mined keep-token set (file paths, URLs, inline-code
+ spans, error codes, `UPPER_SNAKE` constants and long identifiers), and
+ dropping the prose body. Tier-down beats eviction because the durable facts
+ survive while the expensive, low-signal prose does not. It is **opt-in and
+ off by default** via `[decay] compact_cold_episodic` (a `false` default, so an
+ upgrade changes nothing until an operator opts in), fully zero-LLM (regex
+ only), and **reversible and non-destructive**: the rewrite goes through the
+ wiki layer, so the full pre-compaction body stays reachable in git history and
+ the supersession chain and is recoverable with `restore-page`. A new `V65`
+ migration adds a nullable `pages.compacted_at` marker (additive `ADD COLUMN`,
+ no backfill; populated lazily by the sweep from a `compacted: true` frontmatter
+ mirror) so the sweep and the curator tell a deliberately-short compacted page
+ from a cold one — a compacted page is never re-compacted, re-evicted, or
+ re-reported as cold. Only unpinned episodic pages compact; pinned/semantic/
+ procedural pages are never touched. Every run reports what it compacted in the
+ `SweepReport`. Ships opt-in/off; the R2 recall no-regression proof is the gate
+ before any future default-on. No new MCP tool (still 23) (#808).
+- Per-tier retention half-life curves (design-memory-aging.md bucket A1): the
+ forget-sweep's decay rate can now be tuned per memory tier via an opt-in
+ `[decay.half_life_days]` config table, replacing the single global λ. Each
+ key (`working` / `episodic` / `semantic` / `procedural`) is a half-life in
+ *days*, converted internally to `λ = ln(2) / days`, so an operator can keep
+ episodic session history longer and working-tier scratch shorter (the
+ mcp-memory-service 365/180/90/30 shape). An omitted key falls back to the
+ scalar `[decay] lambda`, so the default (no table) is byte-identical to the
+ previous single-λ behaviour — an upgrade changes no score and mass-evicts
+ nothing on the first post-upgrade sweep. Pure math + config: no new column,
+ no migration, and no new MCP tool (still 23) (#807).
+- Access reinforcement on the remaining read paths (design-memory-aging.md
+ bucket C1): `memory_read_page` (a direct by-path/by-query read), its
+ `include_related` link-graph walk (the walked neighbours, not just the seed),
+ and `memory_explore` (the pages it surfaces — rules, slots, recent, pinned,
+ settled) now bump `access_count` + `last_accessed_at` exactly as
+ `memory_query` and `memory_recent` already do. A page a human opens directly,
+ or one the graph surfaces, is *used* and now resists decay like a search hit.
+ Reuses the sanctioned reinforcement path: fire-and-forget on the single-writer
+ actor, throttled to ≤1 per (page, operator) per minute, and FTS-exempt. It is
+ strictly additive — reinforcement only raises retention scores, never blocks,
+ never touches the response payloads, and adds no new MCP tool (still 23)
+ (#798).
+- Reasoning tier on the LLM synthesis paths: an opt-in `reasoning` argument on
+ `memory_query` (its `answer` path) and `memory_explore` (borrowed from
+ Honcho's reasoning-effort ladder; targets the 2.4 line). The knob is a schema
+ enum `minimal` (default) / `low` / `medium` / `high` / `max`; an unknown value
+ is rejected. Because the provider-neutral `ChatRequest` carries no per-request
+ reasoning/effort field (the provider-level `reasoning_effort` is fixed at
+ construction from config), the tier maps honestly to a per-tier max-token
+ budget scaled off each path's base budget (answer 2 000, explore 16 000):
+ `minimal` = 1x, `low` = 1.5x, `medium` = 2x, `high` = 3x, `max` = 4x — a
+ higher tier gives the model more room to reason before its output is
+ truncated. It only tunes the answer path: `reasoning` is inert unless the LLM
+ path actually runs (`answer: true` with a provider, or `memory_explore` with a
+ provider), so the zero-LLM default path is untouched. Omitting `reasoning`, or
+ passing `minimal`, is byte-identical to before. No new MCP tool (still 23)
+ (#783).
+- Dialectic answer on `memory_query`: an opt-in, off-by-default `answer`
+ argument (borrowed from Honcho's dialectic endpoint; targets the 2.4 line).
+ When `answer: true` AND the server has an LLM provider configured, the query
+ synthesizes a concise, cited natural-language answer over the top retrieved
+ hits and attaches it as `answer: { text, citations }`, where `citations` are
+ the page paths the answer drew from (JSON-schema structured output, grounded
+ strictly in the retrieved snippets). When `answer: true` but no provider is
+ configured, the normal hits are returned plus a short `answer_unavailable`
+ note rather than an error. With `answer` omitted/`false` (the default), no LLM
+ provider is accessed and the response is byte-identical to before, so the
+ zero-LLM default path is untouched. Applies to the normal single-project /
+ `scopes` search; `global` and `as_of` queries ignore it. Honest caveat: the
+ feature is new and its answer quality is not yet eval-validated — treat the
+ synthesized answer as a convenience over the same hits and still open the
+ cited pages before acting (#782).
+- "Pin before search": `memory_query` gained an opt-in `pin_first` argument and
+ `memory_briefing` now carries a bounded `pinned` list (default off/absent;
+ targets the 2.4 line). Pinned pages previously earned only a small post-RRF
+ authority bump; they were never surfaced *ahead of* the search, and the
+ briefing never listed them by the `pinned` column. With `pin_first: true`, a
+ single-project `memory_query` prepends the project's bounded pinned latest
+ pages (newest first, cap 10) ahead of the fused hits, deduped by page id so a
+ pinned page that also matches the query appears once (marked `pinned: true`),
+ and re-truncates to the requested limit; `scopes`, `global`, and `as_of`
+ queries ignore it. A project-scoped `memory_briefing` snapshot now includes a
+ bounded `pinned` list of pinned latest pages (distinct from the `_slots/`
+ path-prefixed `slots`) so SessionStart hot-context can show standing context.
+ Both are backed by the new `ReaderPool::list_pinned_pages`; default off/empty
+ is byte-identical to the previous query ordering and briefing shape (#780).
+- `memory_read_page` gained an opt-in related-pages graph walk (default false;
+ targets the 2.4 line). Passing `include_related: true` adds a `related` array
+ of the pages reachable from the read page through the link graph — a bounded
+ breadth-first walk that reuses the single-hop link primitive per node,
+ following both outgoing links and incoming back-links out to `related_depth`
+ hops (default 1, hard-capped at 3). Each entry carries its
+ path/title/kind/workspace/project plus the hop `depth` and edge `direction`
+ (`link`/`backlink`) it was reached by; the walk is cross-project aware,
+ dedup- and cycle-safe via a global visited set, and bounded by a total-node
+ cap. Default-off behaviour is byte-identical to the previous single-page
+ response (no `related` field) (#775).
+- `memory_query` gained an opt-in `include_superseded` argument (default false;
+ targets the 2.4 line). When set, project and explicit-scope searches also
+ return superseded (older) page versions across the FTS/entity/vector/graph
+ streams, each hit labelled `superseded: true` so callers can tell historical
+ versions from the current one; the current version is never marked. Default-off
+ behaviour is byte-identical to the previous latest-only retrieval, and
+ `global=true` and `as_of` time-travel are unaffected (#773).
+- `memory_status` now reports which project answered: a `scope` object with
+ `workspace`, `project`, and `resolved_by` (`explicit`, `session`,
+ `shared_slot`, `startup_seed`, `default`, or `default_after_mismatch`). An
+ unscoped call from a static MCP client, whose transport session id is not a
+ lifecycle-hook session id, returned plausible counts for a project it never
+ named, with nothing in the response to question them; `resolved_by` now makes
+ that visible. The server also logs a warning whenever an unscoped MCP read is
+ resolved by the startup seed or by the default after a session mismatch,
+ rather than by the caller's own hook session (#757, #774).
+
+### Docs
+- Stopped recommending `AI_MEMORY_LLM_MODEL=gpt-5-mini` for the `openai-oauth`
+ provider in `docs/llm-providers.md` and `docs/install.md`. The Codex/ChatGPT
+ backend only accepts a small server-defined set of model ids and rejects
+ others (including `gpt-5-mini`) with a deterministic 400; the docs now advise
+ leaving the provider default (`gpt-5.5`) for `openai-oauth`/`codex`, keep
+ `claude-haiku-4-5` for `anthropic-oauth`, and qualify `gpt-5-mini` for
+ `copilot` as unverified. (#831)
+- `docs/llm-providers.md` now covers the `opencode` LLM provider, which has
+ shipped since 1.x but was missing from the recommended-defaults table:
+ `OPENCODE_API_KEY` as the only credential, Go as the default endpoint, Zen
+ via `AI_MEMORY_LLM_BASE_URL`, the built-in default model, per-catalogue
+ model ids, and which model goes through the Responses endpoint (#763).
+- Refreshed the LongMemEval-S retrieval benchmarks on the 2.4 tree and
+ populated the full-dataset R2 A/B (`docs/benchmarks/`): local embeddings add
+ +0.149 hit@5 / +0.254 recall@10 over zero-LLM FTS, with a clean
+ baseline-vs-baseline determinism check and **no default-ranking regression**
+ vs 2.3.x (the 2.4 features are opt-in / off by default).
+
+### Fixed
+- A failed scheduled `auto_improve` review no longer removes its session from
+ the queue permanently. The scheduler claims a session before reviewing it,
+ and the candidate query excludes any session that holds a claim — but nothing
+ ever released one, so a review that failed (a hung provider call, or a
+ proposal the reviewer could not stage) left a claim with no run row and that
+ session was skipped by every later tick. The state was silent: the tick
+ reported `errors=1` once and clean runs from then on, and the only exit was a
+ hand-written `DELETE`. A claim now records the failure and releases, so the
+ next tick retries it, and parks after 3 attempts with the last error kept so a
+ deterministic failure stops costing a review every tick instead of vanishing.
+ The tick summary counts `parked` separately from `errors`. (#833)
+- The auto-improve reviewer now excludes `sessions/` pages from its own
+ recent-page context so those slots go to durable pages (`decisions/`,
+ `gotchas/`, `_rules/`, …) it might otherwise re-propose. Session pages are
+ never valid proposal targets and previously dominated the recency-ordered
+ list, crowding durable knowledge out of the reviewer's view. The exclusion is
+ scoped to the reviewer only — the SessionStart briefing and `memory_briefing`
+ still include session pages. `docs/auto-improvement-loop.md` now documents
+ that only `_rules/`/`procedures/` page bodies reach the reviewer and that the
+ recent-page list is recency-ordered, with configurable patchable prefixes and
+ embedding-nearest dedup noted as deferred future work. (#834)
+- Auto-improve proposal staging no longer discards an entire run when one
+ proposal is a create/update misclassification. A `Create` whose target page
+ already exists, or an `Update`/patch whose target is missing, previously
+ aborted the staging transaction, dropping every sibling proposal and the run
+ row over one probabilistic LLM mislabel. Those two cases now skip just the
+ offending proposal (reported as `skipped`, like a pending-target collision)
+ and keep the rest of the run. Two proposals in one run targeting the same
+ path remain a hard error, and a create-on-existing is never coerced to an
+ update (the page could be pinned). (#832)
+- The Windows Docker wrapper (`bin/ai-memory.ps1`) now forwards the same
+ provider credentials and host-config env vars as the POSIX wrapper into the
+ helper container. A host-exported `GEMINI_API_KEY` / `GOOGLE_API_KEY`,
+ Copilot token, `OPENCODE_API_KEY`, `CLAUDE_CONFIG_DIR`, or
+ `AI_MEMORY_WORKSTREAM_ID` previously never reached `Config::load`, so
+ `llm-test`, Copilot auth, OpenCode, and a relocated Claude config all
+ reported "not configured" on native Windows Docker Desktop even though the
+ same export worked through `bin/ai-memory`. The POSIX wrapper also now
+ forwards `OPENCODE_API_KEY`. (#803)
+- `Config::load` now treats Windows `%USERPROFILE%` (then `dirs::home_dir`) as
+ the operator home when `AI_MEMORY_HOME` and `$HOME` are unset. Native
+ Windows often has no `HOME`, so the #103 catch-all guard — skip a stored
+ `repo_path` equal to the user profile so it cannot prefix-match every
+ project beneath it — was inert there and a home-directory project could
+ swallow unrelated cwds. (#804)
+- Automatic handoff selection and cwd-prefix project matching now treat
+ Windows drive-letter and UNC paths as case-insensitive. A Linux server
+ (the Docker Desktop helper) comparing host cwds from Explorer, Git, and
+ PowerShell previously required a byte-exact match, so `C:\Users\…\repo`
+ vs `c:\users\…\repo` missed the pending auto-handoff and could mint a
+ fragment project. Unix paths stay case-sensitive. (#806)
+- Fixed `Ctrl+C` at the native-session chooser leaving the launcher alive and
+ renewing its workstream lease. Cancelling now releases the acquired run and
+ exits without waiting for Enter or linking a native session (#795).
+- The privacy strip now redacts Windows credential paths (`C:\Users\…\.ssh`,
+ `.aws`, `.kube`, `.gnupg`, `.config\gcloud`). The previous patterns required
+ a POSIX `/` separator, so a captured tool result that echoed a native
+ Windows path stored the profile directory and key file name verbatim. (#805)
+- The privacy strip now redacts secrets written in JSON. The quote before a
+ value put it outside the value character class, so `{"db_password":"..."}`
+ was stored verbatim while the identical YAML form was redacted, and JSON is
+ the shape most captured tool payloads arrive in. The same rule now also
+ accepts an auth scheme word before the value, so
+ `Authorization: Basic <base64>` (which carries `user:password`) is redacted
+ like the `Bearer` form already was, and covers two unprefixed names the
+ generic env rule missed: Azure `AccountKey=` and npm `_authToken=`. (#800)
+- Terminal escape sequences, NUL and bidi override characters are stripped
+ from captured text instead of being stored. Page bodies and observations are
+ replayed to a terminal by `ai-memory read-page` and `ai-memory search`, where
+ an escape rewrites the screen or the window title and a bidi override
+ reverses what the reader sees; a NUL additionally made the markdown file
+ binary, costing it `grep` and git diffs. Tabs, newlines and carriage returns
+ are kept. (#800)
+- A page write is refused when another live page in the same project differs
+ from it only by case or Unicode normalization. Such a pair is one file on
+ macOS (APFS) and Windows (NTFS), so creating the second silently overwrote
+ the first page's file while the index kept both rows, so reads for either path
+ then returned the survivor's body, and the wiki watcher superseded the
+ overwritten row, losing the original content from disk and index alike. The
+ refusal names both paths, applies on every platform (the wiki is synced
+ between them), and leaves supersedes of an existing path untouched.
+ `reindex` skips such a pair instead of failing the whole rebuild, reports the
+ count, and logs each one. (#799)
+
+## [2.3.2] - 2026-09-20
+
+### Changed
+- `memory_consolidate` accepts an omitted `session_id`. Omitting the field (or
+ sending `null`) no longer fails deserialization with `missing field
+ session_id`; the tool consolidates the latest completed session in the
+ resolved project — the same default `memory_auto_improve` and
+ `memory_read_session_observations` already use. Pass an explicit UUID to
+ target a specific session, and `dry_run=true` for the cheap admission
+ preflight. A project with no completed session now fails as
+ `no completed session in <scope>` instead of a deserialization error.
+- A consolidation LLM call that fails on a transient provider error (`429`, any
+ `5xx`, a transport timeout or connect failure) is retried twice, two seconds
+ apart, before the failure is reported — the same bounded policy `bootstrap`
+ already applies to its chunks. Deterministic failures (auth, schema, a
+ malformed-request `4xx`, unparseable or truncated output) are still reported
+ on the first attempt, since retrying them only burns another call.
+
+### Fixed
+- CLI commands no longer fail at startup when an `[[llm_fallbacks]]` profile's
+ `api_key_env` variable is absent from the invoking shell. `Config::load`
+ validated every fallback credential eagerly, so read-only commands such as
+ `ai-memory status` exited with `llm_fallbacks[0].api_key_env=... is set but
+ the environment variable is missing or empty` even when the running server
+ had the key injected by its service wrapper, which pushed operators to export
+ provider keys in every shell. The missing credential is now enforced where it
+ is needed: `ai-memory serve` still refuses to start without it, and building
+ the LLM chain still fails rather than silently dropping the fallback. Every
+ other profile check (provider, model, base URL) still runs at load for every
+ command (#762).
+- `backfill --dry-run` recorded a completed attempt and suppressed the next
+ automatic import. Planning now leaves the backfill sentinel untouched, even
+ for populated projects or an opted-out automatic invocation (#785).
+- `ai-memory serve` no longer hard-fails to take its single-instance lock on a
+ transient error under load. Acquiring the serve lock now retries `open` and
+ `try_lock_exclusive` a few times with a short (~25ms) backoff when they hit a
+ transient failure (EMFILE/ENFILE fd exhaustion, EINTR), mirroring
+ `acquire_drain_lock`. A genuinely contended lock (`WouldBlock`, another server
+ holds it) is never retried and still refuses startup immediately. The
+ serve-lock tests also assert with the concrete errno so any remaining
+ environmental flake is diagnosable rather than silent (#745).
+- GitHub Copilot completion requests now select the model-advertised API
+ endpoint from `/models`: existing Chat Completions remains preferred when
+ available, while Responses-only models use `/responses`. Responses requests
+ preserve strict JSON Schema structured-output constraints and report empty,
+ refused, or rejected output without silently downgrading the contract. A model
+ the `/models` catalogue does not enumerate (enterprise/custom deployments,
+ aliases, a model newer than the list) falls back to Chat Completions with a
+ warning instead of erroring, matching the graceful fallback already used when
+ `/models` is unavailable. As a related behavior change, a Copilot chat
+ completion that returns empty content now reports `UnexpectedShape` rather
+ than yielding an empty string. (#761)
+- The V62 page-ingestion-window migration no longer runs its backfill inside a
+ single migration transaction, which on a large store ran for hours and grew
+ the WAL to roughly the size of the database with no progress. V62 is now
+ DDL-only (the two columns plus their index); the window backfill moved to a
+ chunked, resumable, WAL-bounded boot-path step that processes pages in bounded
+ batches, checkpoints the WAL (`TRUNCATE`) between each, and logs progress. The
+ end state is byte-identical to the original V62, the step resumes rather than
+ restarts if interrupted, and it is a fast no-op on a store that already applied
+ the original V62. Because that reshape changes the migration's checksum, the
+ runner now intentionally tolerates a divergent checksum on an already-applied
+ migration (`abort_divergent = false`) so correctly-migrated stores still open;
+ the schema-ahead guard (`abort_missing`) is unchanged (#776).
+- Page writes now refuse git-reserved and non-portable page paths (a `.git`
+ component or an 8.3 `git~1`..`git~4` alias, Windows-reserved names and
+ characters) on every write funnel, including MCP `memory_write_page` and
+ consolidation `apply_batch`; reads of already-stored pages stay tolerant so
+ a bad row never breaks a listing. The git-reserved check is byte-safe and no
+ longer panics on a 5-byte multibyte path component (#781).
+- The generated OpenCode and OpenCode 2 plugins now forward a subagent session's
+ `parentID` as the `agent_id` marker, so `[capture] drop_subagent_captures` can
+ recognize and drop OpenCode subagent sessions. Previously both plugins emitted
+ only `title`/`projectID` on `session.created`, so the marker never reached the
+ server and the opt-in was a silent no-op for OpenCode. Root sessions (no
+ `parentID`) stay unmarked (#755).
+- Scope-resolution failures over MCP now answer with `invalid params`
+ (`-32602`) instead of an opaque internal error (`-32603`), the same split the
+ web route applies with its 400/404: a malformed scope argument, or a
+ workspace/project name that does not resolve, is caller input, while a
+ missing writer handle or an underlying store failure stays internal. The
+ messages are unchanged.
+- `memory_consolidate` treats a blank `session_id` (`""` or whitespace) exactly
+ like an omitted one — the resolved project's latest completed session — and a
+ malformed id now fails as `invalid params`, the code `memory_auto_improve`
+ already uses for the same argument.
+
+- `backfill` returned success even when imports failed, and `--quiet` hid
+ their diagnostics. It now reports errors on stderr, includes failure counts
+ in the human summary, and exits nonzero after emitting its report (#786).
+
+## [2.3.1] - 2026-09-17
+
+### Added
+- `DATA_HANDLING.md`, `docs/sso.md`, and `docs/airgapped-install.md`,
+ consolidating existing data-flow, OIDC, and offline-install facts from
+ `SECURITY.md`/`docs/install.md`/`docs/local-embeddings.md` into the shape
+ enterprise security/legal review typically asks for before approving a dev
+ tool. No behavior change; a small addendum to `SECURITY.md`'s reporting
+ section adds a fallback contact path for reporters who can't use GitHub's
+ private-advisory flow.
+
+### Fixed
+- `export-okf` no longer refuses to export any project that has captured an
+ observation. The bundle walk skipped the reserved names `index.md` and
+ `log.md`, but not the rotated hook ledger `log-YYYY-MM.md` the server itself
+ appends to — which carries no frontmatter, so `okf::is_conformant` failed it
+ and aborted the whole export with `422 page log-YYYY-MM.md is not
+ OKF-conformant; run the server once to migrate before exporting`. Migrating
+ could not help: the OKF migration deliberately skips ledgers (#669), so the
+ file the export demanded be conformed stays frontmatter-less forever. The
+ ledger is raw capture rather than a concept file, so it is now dropped from
+ the bundle exactly as `log.md` already was, sharing the migration scan's
+ content gate — a prose page that happens to be named `log-2026-09.md` still
+ ships and still has to declare a `type`. (#748)
+
+## [2.3.0] - 2026-09-16
+
+### Added
+- `ai-memory run <harness>` now auto-installs that harness's ai-memory hooks and
+ MCP server the first time it launches the harness, if they are not already
+ wired — so managed launch (the recommended way to start a harness) captures
+ and can query memory without a separate `install-hooks` / `install-mcp` step.
+ It is idempotent and one-time per harness + binary version (a per-agent
+ sentinel under `<data_dir>/autowire-state/`), preserves any unrelated user
+ config the installers touch, runs before the child spawns so the harness picks
+ up the fresh hooks, and is best-effort (a failure warns and the launch still
+ proceeds). Harnesses without installer support (e.g. Crush) are skipped
+ cleanly, and Pi wires hooks but has no MCP client to write. Opt out with
+ `ai-memory run --no-autowire`, `AI_MEMORY_RUN_AUTOWIRE=false`, or
+ `run_autowire = false`. Documented as the preferred launch path ("if in
+ doubt, run with ai-memory").
+- Boot-time backfill of pre-hook local history, on by default. When a project's
+ ai-memory store is brand new (empty), the SessionStart hook triggers a
+ one-time, bounded import of that project's existing local harness transcripts
+ so installing hooks mid-project no longer starts amnesiac about the very
+ session you are resuming. It replays each local transcript through `/hook` —
+ the same ingress live capture uses — so the history becomes real sessions and
+ observations that consolidate into pages and are searchable via `memory_query`,
+ **sanitized and bounded on the server exactly like live capture** and
+ attributed to the original harness. It only ever bootstraps an empty project
+ (never overwrites an established one; live capture from install-time forward
+ and backfill of before-install history do not overlap), is hard-capped (newest
+ 25 sessions, 50k events), and runs detached so session start is never blocked.
+ New `ai-memory backfill`
+ subcommand runs it by hand (`--dry-run`, `--force`, `--session`, `--json`).
+ Opt out with `AI_MEMORY_BACKFILL_ON_START=false` / `backfill_on_start = false`.
+- New `ai-memory doctor` command: a capture-coverage check that, for the current
+ project, compares every known harness's local (on-disk) native session store
+ against what the server actually captured (`GET /admin/sessions/by-agent`) and
+ warns when a harness ran here recently but has zero captured sessions — the
+ silent "its hook was never installed" gap — printing the exact
+ `install-hooks --agent <name> --apply` to fix it. Read-only on the local side;
+ supports `--json`, `--since-days`, and explicit `--workspace`/`--project`.
+- New task-oriented `docs/cookbook.md` cheat sheet ("I want to do X" → how:
+ recall, durable rules, importing a knowledge base and reading a specific
+ document, two agents working together), linked from the README docs table, to
+ make it clearer what ai-memory does and how to use it (#726).
+- Codex assistant-final-turn capture: `install-hooks --agent codex --capture-assistant`
+ now captures the assistant's final message on `Stop`, the same double opt-in
+ (client flag + server `capture_assistant = true`) and sanitize/bound pipeline
+ as Claude Code. Codex's `Stop` payload carries `last_assistant_message`
+ (verified on codex-cli 0.154.0); the installer previously refused the flag for
+ Codex and now bakes it on a native hook platform. Only `(Codex, Stop)` is added
+ — Codex has no `SubagentStop` (#743).
+- Cross-project agent messaging: a directed, claim-once inbox/queue so an agent
+ in one project can hand a self-contained request to an agent in another
+ project without pulling that project's context into its own session. Four new
+ MCP tools (`memory_message_send` / `memory_message_list` / `memory_message_pop`
+ / `memory_message_cancel`, bringing the surface to 23) plus `ai-memory message
+ send|list|pop|cancel` CLI subcommands and `/admin/messages*` routes, backed by
+ the new `agent_messages` table (migration V64). Messages are addressed to a
+ project (any session there can pop; claim-once); the sender can retract a
+ pending message; an unknown recipient fails closed; each inbox is depth-capped.
+ A popped message is treated as untrusted cross-project input — secret-scrubbed
+ and size-capped on send, fenced with a security notice and sender provenance on
+ pop, and never auto-injected into context. See `docs/agent-messaging.md`.
+- The session-start "hot context" block now appends a non-consuming inbox notice
+ (a static count only — never message text) when a project has pending
+ cross-project mail, and `memory_briefing` reports `pending_message_count`.
+- Added an independent `codex` LLM provider that follows the Codex CLI account
+ selected by `CODEX_HOME`, reloads its read-only `auth.json` credentials before
+ each operation, and delegates expired-token recovery to
+ `codex app-server --stdio` (#716).
+- `install-mcp --flavor <moonshot|bedrock|gemini>` pins the tool-schema dialect
+ in the URL written into a client's config. The installer already picks one for
+ the clients whose upstream is fixed — Kimi Code is always Moonshot, Kiro always
+ Bedrock — but a client that fronts several models cannot be pinned by its name
+ alone, and there was no installer path to `?flavor=gemini` for any of them. A
+ Command Code or OpenCode install routed to Vertex needed the marker added by
+ hand or every model call 400'd at `tools/list`; the same client on a non-Google
+ model does not, which is why this is an explicit choice rather than another
+ per-client default. `vertex` is accepted as an alias. `uninstall` now matches
+ every marker on every client, so an entry pinned this way is still removed
+ (#735).
+- `AI_MEMORY_EMBEDDING_PROVIDER=copilot` adds GitHub Copilot as an embedding
+ provider, reusing the `copilot` LLM provider's OAuth login and GitHub-token
+ exchange (no separate API key). Defaults to `text-embedding-3-small`,
+ 1536-dim; calls Copilot's `/embeddings` endpoint following the
+ OpenAI-compatible contract Copilot documents for chat (#739).
+
+### Fixed
+- `install-hooks --apply` now preserves an existing `--capture-assistant` opt-in
+ on a bare re-apply (one with no `--capture-assistant` flag). Previously a
+ refresh without the flag silently stripped assistant capture; this most
+ affected the new `ai-memory run` auto-wire, which always re-applies without the
+ flag. The flag still explicitly enables it; an unset flag now keeps whatever is
+ already installed (Claude Code and Codex).
+- `install-hooks --apply` no longer aborts the entire install when the hook
+ bearer token cannot be persisted under the data dir. This bit the docker
+ wrapper, where `data_dir` is `/data` — a container volume the host hooks
+ never read from and that the container user frequently cannot write — so the
+ persist step failed with `Permission denied` and left the operator with *no*
+ hooks and no capture at all. The installer now falls back to embedding the
+ credential inline in the rendered hook config (the pre-#552 behavior), warns
+ that the token is then readable in that file and how to restore the secure
+ on-disk path (a writable host data dir, e.g.
+ `AI_MEMORY_DATA_DIR=$HOME/.local/share/ai-memory` for the docker wrapper, or
+ a native binary), and completes the install so capture keeps working.
+
+## [2.2.2] - 2026-09-15
+
+### Security
+- Updated `rustls` 0.23.40 → 0.23.45 for [RUSTSEC-2026-0285](https://rustsec.org/advisories/RUSTSEC-2026-0285),
+ in which a TLS 1.3 handshake message that follows a key-changing message in
+ the same record can be accepted at the wrong encryption level. `rustls` is a
+ direct dependency — it installs the process-wide crypto provider the MCP
+ bridge needs for HTTPS — and is also the TLS implementation every outbound
+ HTTPS call resolves to through reqwest, so the advisory failed `cargo audit`
+ and `cargo deny check` on every open pull request that inherited `main`'s
+ lockfile, including ones that change no Rust at all. `Cargo.toml` already
+ allows compatible 0.23 patch releases, so this is a lockfile-only change
+ needing no manifest or public-surface edit; the same resolution moves
+ `rustls-webpki` 0.103.13 → 0.103.15 and nothing else (#731).
+
+### Fixed
+- The native `ai-memory hook` session-id state file
+ (`<data_dir>/hook-state/<agent>-session-id`), introduced for Devin in #178,
+ now also covers ZCode. ZCode's hook payloads do not reliably carry a session
+ id, it fires `Stop` at the end of every turn, and it has no `SessionEnd`
+ event — without a persisted id, each turn with an id-less payload opened a
+ fresh server-side session that nothing ever closed (observed in production:
+ 4 sessions with NULL `ended_at` and 398 observations stuck in episodic).
+ ZCode events without a native id now share one stable stored id per agent
+ session; events carrying a native id are passed through untouched. The stored
+ id is cleared by `finalize-session --agent zcode` (which now also removes the
+ state file) or overwritten by the next `session-start`; `Stop` never clears
+ it. Other agents are unaffected: payloads that carry a session id short-circuit
+ the state file exactly as before.
+- `memory_feedback`'s `signal` (FeedbackKind) JSON schema now declares a
+ top-level `type: "string"`, so strict function-calling gateways (Moonshot/Kimi
+ and other schema validators) accept the `tools/list` surface instead of
+ rejecting the enum for a missing type (#735, #741).
+- Cursor lifecycle events are no longer stored twice on a host where both
+ `install-hooks --agent cursor` and `install-hooks --agent claude-code` are
+ applied. Cursor also runs the commands in Claude Code's settings, and since
+ 2.1.0 that copy is re-attributed to `cursor` by its `cursor_version`, so it
+ landed in the same session as the native event. The `--agent claude-code`
+ hook now drops a Cursor-marked payload when `~/.cursor/hooks.json` already
+ registers an ai-memory `--agent cursor` hook; without Cursor's own hooks the
+ Claude Code path keeps capturing Cursor sessions as before (#721).
+- `install-hooks --agent cursor --apply` now warns about existing
+ `~/.cursor/hooks.json` entries that mention ai-memory but are not ai-memory
+ hook entries, such as a pre-2.1.0 shim that injected `cwd`. Those entries
+ are kept beside the native ones, so every event would otherwise be captured
+ twice without any sign (#721).
+- The POSIX shell hook bundle's spool reader no longer builds the decoded value
+ in memory. `ai_memory_json_field` appended to a string that grows to the whole
+ value, so reading a multi-megabyte entry — one large tool result is enough —
+ took minutes of CPU, and a drain pass reads every entry three times (`url`,
+ `body`, `token`) while one detached pass starts behind every delivery that
+ succeeds. Once an outage had filled the spool, the passes accumulated faster
+ than they retired and saturated the machine. The value is now bounded by a
+ single regex pass over the JSON string grammar, unescaped with `gsub` over
+ whole segments and written straight to stdout, for identical output and exit
+ codes. A 2.2 MB entry of `grep` output — the shape that caused the incident,
+ where every literal backslash is an escaped pair — goes from 732 s to 5.5 s
+ under the awk macOS ships and from 9-10 s to about 1 s under mawk and gawk
+ (#727).
+- The POSIX shell hook bundle now assigns an `ingest_key` before its initial
+ delivery and preserves that key when spooling the event, preventing a replay
+ from creating a duplicate observation when the server committed the first
+ request but its response was lost (#729).
+- `install-hooks` reapply is idempotent again on Windows for agents whose
+ native command uses an underscore executable name (`ai_memory`): the hook
+ ownership predicate recognized only the hyphenated `ai-memory`, so a reapply
+ reported `Updated` and failed to dedup its own prior Antigravity/Cursor/Kimi
+ Code entries. It now matches both forms while still requiring the full
+ `hook --event … --agent … --server-url …` argv signature (#740).
+- The POSIX shell hook bundle's `ai_memory_json_string` now escapes every JSON
+ control character (U+0000–U+001F) as `\u00XX`, not just backslash, quote, tab
+ and CR. A replayed tool result carrying an ANSI colour escape (0x1b) reached
+ stdout bare, so the managed-workstream SessionStart packet — and any handoff
+ whose summary held a control byte — was rejected as invalid JSON and the
+ resuming session started with no context. The escaping is linear and reuses
+ the same BusyBox replacement-doubling probe as the four existing escapes
+ (#732).
+
+## [2.2.1] - 2026-09-12
+
+### Fixed
+- The POSIX shell hook bundle no longer drops a lifecycle event when the
+ server is unreachable or answers 5xx. A failed delivery is written to
+ `<data_dir>/hook-spool/` in the same on-disk contract `ai-memory hook-drain`
+ reads (same filename shape, same `SpoolEntry` JSON, same 0600/0700 modes,
+ tmp+rename), with an `ingest_key` minted once at spool time so a shell drain
+ and a concurrent `hook-drain` cannot double-ingest; the backlog is flushed
+ behind the next delivery that succeeds, detached from the hook so the agent
+ never waits. A 4xx stays a permanent rejection and is not retried. This is
+ the durability the generated TypeScript integrations got in #580, for the
+ path the docker deploy installs. The PowerShell bundle is unchanged (#719).
+- The POSIX shell hook bundle's `POST /hook` now hard-timeouts at 200 ms
+ rather than 500 ms, which is the budget invariant 5 documents for a script
+ hook. A real loopback round trip runs about 0.3 ms, so a local install is
+ unaffected; against a remote server the tighter ceiling is safe only because
+ a missed window now spools instead of dropping (above). The handoff GET keeps
+ its 1 s: it is fed synchronously to the agent's context, and truncating an
+ almost-ready handoff costs more than it saves (#719).
+- `ai-memory restore` no longer rejects the GNU-sparse SQLite entry that
+ `ai-memory backup` itself produces. `tar::Builder`'s default sparse
+ detection archives `db/memory.sqlite` as a GNU-sparse entry (header type
+ `S`) whenever the SQLite snapshot has real holes on disk, which
+ `validate_restore_entry`'s `is_file()`/`is_dir()` check rejected as an
+ "unsupported entry type" — a verified, valid backup could not be restored,
+ with no recovery path but hand-editing the archive. `tar` already expands
+ GNU-sparse blocks to their full logical content while iterating entries, so
+ restore now accepts the type and unpacks it exactly like a regular file
+ (#718).
+
+## [2.2.0] - 2026-09-12
+
+### Added
+- Retrieval `explain` now names the **typed edge** a graph-stream neighbour
+ was reached by: `memory_query(explain=true)` reports `graph_via.edge` =
+ `causes` / `fixes` / `contradicts` (omitted for a plain `references` link), so
+ it is visible *why* a page surfaced through the link graph. Retrieval ranking
+ is unchanged — this is explanation only; typed-edge weighting and `contradicts`
+ capping are deferred behind the eval harness (docs/design-hindsight-borrowings.md P3).
+- Page-grain ingestion windows (`pages.valid_from` / `valid_to`, V62) and
+ a second `as_of` stream: `memory_query(as_of=T)` now fuses the entity
+ timeline with version-filtered full-text search over the page versions
+ alive at T, using the default path's RRF (k=60) plus the same bounded
+ authority adjustment — current-index relevance over knowledge valid at T. This
+ answers entity-less pages and paraphrased audit questions ("which
+ database were we on during the outage?") that the entity-only lookup
+ missed. `explain=true` reports both streams (`streams_active:
+ ["entity", "fts"]`) with per-stream ranks and RRF contributions.
+ Vector, graph, and the raw-observation fallback stay out of audit mode;
+ the default (no `as_of`) path is unchanged. Every retire path
+ (supersede, decay, reorg graveyard, move-regenerate) closes both grains
+ in the same transaction, and the V62 backfill closes successor-less
+ retirements at the decay marker, existing entity-link close, or
+ `updated_at` fallback, preserving recorded reorg/move history.
+ Phase B world-time stays deferred. (#656)
+- `[retrieval]` section with two opt-in ranking signals, both off by default
+ so unconfigured stores rank exactly as before. `query_intent` routes
+ lexically session-recall queries ("上次 / 之前那次…的会话 / last time /
+ yesterday …") past the default session-page authority penalty
+ (×0.77 combined kind/tier), with `session_recall_bonus` (default 0.25)
+ sizing the lift; `abstract_vectors` adds a fifth RRF stream over the new
+ `page_abstract_embeddings` table (V61) — the L0 layer: a page's
+ frontmatter `abstract:` line is embedded on its own, at write time when an
+ embedder is attached and by the same backfill as the body otherwise
+ (a one-line summary embeds far more sharply than a
+ multi-thousand-character body). Measured on a 138-query golden set over a
+ production two-year wiki (FTS5 + entity + vector + graph, mis-tei
+ Qwen3-Embedding-8B): hit@1 0.609 → 0.746 (+22%), NDCG@10 0.782 → 0.879
+ (+12%) with both enabled; every unrouted category keeps its exact
+ baseline ordering. Cross-checked on an independently built 99-query
+ golden set against the same store: hit@1 0.556 → 0.626, NDCG@10
+ 0.712 → 0.779 (+9.4%). Both signals are visible per hit in
+ `memory_query(explain=true)` (`intent`, `intent_boost`,
+ `abstract_rank`, `rrf.abstract`). (#672)
+- `memory_handoff_list` lets no-stdout and MCP-only clients inspect open
+ project handoffs without claiming or expiring them, then
+ `memory_handoff_accept` can claim that exact `handoff_id` once. Grok,
+ Zero, and other clients that discard SessionStart stdout no longer have
+ to recover a baton by blindly accepting the latest row. Listing is
+ owner-filtered like accept (own plus shared; root-only `any_owner`);
+ it is not a second claim path, and Grok SessionStart still does not
+ fetch `/handoff`. (#664)
+- `install-instructions --compact` writes a slimmer managed routing block for
+ projects that already have the detailed ai-memory Agent Skills installed. The
+ compact block keeps the same start/end markers (so refresh/uninstall still
+ find it), the untrusted-history security scaffold, and the cross-harness
+ memory-of-record guidance; `full_block` and the default remain unchanged.
+ (#675)
+- `memory_install_self_routing` accepts `compact: Option<bool>` so agent-driven
+ refreshes of a compact-installed file preserve the compact routing block
+ instead of rewriting it back to full. (#685)
+- The `openai-compat` provider now sends OpenRouter's app-attribution
+ headers (`HTTP-Referer`, `X-Title`) by default when its base URL points
+ at `openrouter.ai`, so ai-memory's usage shows up on OpenRouter's app
+ leaderboard. An explicit `AI_MEMORY_LLM_HEADERS` entry for either header
+ still wins, and a non-OpenRouter compat endpoint (Ollama, vLLM, LM
+ Studio) never receives them. (#686)
+- `ai-memory run` now accepts any `claude*`-prefixed harness name
+ (`claude-corp`, `claude-personal`, ...), all resolving to the same
+ `ManagedHarness::Claude`/`AgentKind::ClaudeCode` — no new session store,
+ migration, or agent kind. This is for callers juggling more than one
+ Claude account (e.g. Corporate and Personal): name each account's `PATH`
+ wrapper script `claude-<account>` and pair it with `--executable
+ claude-<account>` (bare names already resolve through `PATH`) so
+ `ai-memory run claude-corp --executable claude-corp` and `ai-memory run
+ claude-personal --executable claude-personal` each launch the right
+ binary while reading clearly in shell history (#687).
+- `install-mcp --client muse` registers ai-memory with Meta's Muse Code,
+ merging a native streamable-HTTP entry with bearer `headers` into the
+ snake_case `mcp_servers` map of `~/.config/muse/settings.json` and
+ preserving sibling servers. The writer adds the mandatory
+ `"schema_version": 1` when it is absent — without that key every `muse`
+ command fails at startup with `malformed settings file` — and never
+ rewrites an existing value, so a future schema is not downgraded. The entry
+ sets `"mode": "optional"` because Muse defaults it to `required`, which
+ aborts the whole run when the memory server is unreachable. MCP-only:
+ Muse documents a lifecycle hook surface, but the output contract of its
+ `SessionStart` event is not specified, so capture and managed workstreams
+ are not claimed. Skills need no extra step — Muse reads `~/.agents/skills`,
+ which `install-skills` already writes (#659).
+- Belief-strength evidence substrate (P2, `docs/design-hindsight-borrowings.md`
+ §3): a new append-only `page_evidence` table (V63,
+ `(page_id, source_kind, source_id, created_at)`, `source_kind` one of
+ `session`/`observation`/`feedback`/`reconsolidation`) records what
+ produced or reaffirmed each page version, written in the same
+ transaction as the page upsert. Rule-based and zero-LLM — the
+ consolidator cites the session(s) it drew on for both the single-page
+ and batch write paths, so the substrate populates on the default path
+ with no provider configured. `hybrid_search_explained` (and therefore
+ `memory_query(explain=true)`) now reports `evidence_count` per hit,
+ batch-fetched once after fusion; the default (non-explained) path and
+ ranking are unchanged — evidence is inert data and an explain field
+ this release, not a ranking input. The confidence-into-`PageAuthority`
+ step described in the design doc is deferred behind the planned R2
+ retrieval eval.
+- Standing-answer boot surfacing (P4, `docs/design-hindsight-borrowings.md`
+ §5): `memory_briefing` accepts an opt-in `settled_first: bool` (default
+ `false`, unchanged briefing shape). When `true`, the snapshot's new
+ `settled` array leads with the project's highest-standing `rule`/`decision`
+ pages — up to 8, ordered by `page_evidence` count (P2) then recency — so an
+ agent can boot from settled answers instead of re-deriving them. Pure SQL,
+ no LLM call; every other briefing field, and the default `settled_first:
+ false` path, are byte-for-byte unchanged.
+
+### Changed
+- The privacy sanitizer now redacts to a **typed marker** — `[REDACTED:<kind>]`
+ (e.g. `[REDACTED:github_token]`, `[REDACTED:jwt]`, `[REDACTED:env_secret]`,
+ `[REDACTED:custom]` for operator patterns) — instead of a bare `[REDACTED]`,
+ so a later reader knows *what kind* of secret was present without it leaking.
+ Redaction stays complete and idempotent; the trust boundary is unchanged.
+ Note: this changes the durable sanitized string, so pages written before the
+ upgrade keep `[REDACTED]` while new writes carry the label (see
+ `docs/design-hindsight-borrowings.md` P1).
+
+### Fixed
+- Preserved recorded entity-link retirement timestamps when backfilling
+ page ingestion windows for historical reorg/move-regenerate pages,
+ preventing empty page windows when `updated_at` still held creation
+ time. Clarified current-index ranking and snapshot-based rollback. (#682)
+
+## [2.1.2] - 2026-09-11
+
+### Changed
+- The managed routing snippet distinguishes a reviewed decision record kept in
+ the repository (an ADR directory, a Keep the Why `context/` tree) from a
+ harness-local memory store: decisions go into the repo's record under its
+ convention, ai-memory keeps recall, handoffs and session history and does not
+ duplicate the record as a page. `docs/usage.md` ("Repo-native decision
+ records") and `docs/marker-file.md` say to list such a directory in
+ `[capture] ignore_paths`, and why (#700).
+- The managed routing snippet now states that Claude Code loads `CLAUDE.md` and
+ does not read `AGENTS.md`: a project whose canonical instruction file is
+ `AGENTS.md` needs a bare `@AGENTS.md` import line in `CLAUDE.md`, or the rules
+ written there are absent from context at session start and reach the agent only
+ if it opens the file. `docs/install.md` and `docs/usage.md` carry the same note
+ beside the `--target AGENTS.md` guidance, and this repository's own `CLAUDE.md`
+ now uses the import instead of a prose pointer (#680).
+
+### Fixed
+- A `purge-session` whose page-file cleanup failed was undone by the next
+ watcher pass. The cleanup failure is reported in `files_failed` and leaves
+ the database rows deleted while `sessions/<id>.md` is still on disk; nothing
+ on the reindex path consulted the `purged_sessions` tombstone, so the
+ reconcile tick 30 seconds later indexed the leftover file and the purged
+ session's body was searchable again. The wiki reindex now skips a page whose
+ session is tombstoned, the way it already skips a tombstoned scope, loading
+ the tombstones once per directory per pass rather than once per page. The
+ pass reports them as `skipped_purged_sessions` (#701).
+- The Docker wrapper (`bin/ai-memory`) now forwards `GEMINI_API_KEY` and
+ `GOOGLE_API_KEY` into the container. Every other provider credential was on
+ the `-e` forwarding allowlist, but these two were missing, so
+ `AI_MEMORY_LLM_PROVIDER=gemini` (or the gemini embedder) reached the server
+ while its key did not — the process then failed with `provider not
+ configured: GEMINI_API_KEY or GOOGLE_API_KEY` even though the operator had
+ exported it (#698).
+- `serve` no longer re-archives the whole data directory on every boot once the
+ pre-migration backup receipt's archive has been deleted and auto-improve
+ `_pending/` sidecars exist. The OKF conformance scan that feeds the backup
+ gate flagged those staging sidecars (which carry no frontmatter and are never
+ migrated — SQLite owns their approval state) as nonconformant, so it kept
+ falling through to a full archive. The scan now skips the project-root
+ `_pending/` subtree — a nested `notes/_pending/` page still migrates — matching
+ the watcher indexer and the existing ledger skip (#695, same class as #669).
+- A bare `LLM_BASE_URL` in the environment no longer redirects providers that
+ talk to a fixed vendor endpoint. The variable is a cross-tool convention an
+ operator exports once for a local Ollama, and ai-memory fed it to every
+ provider: a `gemini` server then POSTed to
+ `http://localhost:11434/v1beta/models/<model>:generateContent` and got Ollama's
+ plain-text `404 page not found`, surfacing as
+ `502 Bad Gateway: {"error":"provider error 404: 404 page not found"}` on
+ bootstrap and consolidation. It now reaches only the dialects whose endpoint
+ the operator supplies anyway — `openai-compat`, which has none without it, and
+ `opencode`, whose Zen catalogue is an override — and is ignored elsewhere with
+ a startup `warn!` naming the provider and the URL. An explicit `llm_base_url`
+ (or `AI_MEMORY_LLM_BASE_URL`) still configures any provider, so proxying a
+ vendor endpoint on purpose is unchanged. `ai-memory llm-test` resolves the base
+ URL the same way, so it reproduces what `serve` will do instead of inheriting
+ the same ambient override (#691).
+- Admin requests that fail for a reason the server owns are now logged
+ server-side instead of existing only in the response body. `POST
+ /admin/bootstrap` and the auto-improve routes serialized the error into JSON
+ and told the log nothing, so an upstream provider failure could break every
+ bootstrap while the log showed only the run starting — and a scheduled
+ auto-improve tick, which has no client to print the body, failed with no
+ operator-visible trace at all. A 5xx now emits a `warn!` naming the status,
+ the operation, and the error. A 4xx stays quiet: the caller was told and the
+ caller was at fault, so logging those would let any client fill the log at
+ will (#692).
+- `purge-session` took the wiki mutation guard only for the file cleanup, after
+ the database deletion had already committed. A watcher reindex could reinsert
+ the still-present page in that gap and keep only the row, and a concurrent page
+ write could lose its file to the cleanup. The purge now holds the guard across
+ both steps, so reindexes, page writes and wiki moves finish before it starts
+ and wait until it is done (#696, follow-up to #653).
+- Fixed empty native Codex tool observations by recognizing its top-level
+ tool fields and preserving safe tool-family/call-ID metadata plus bounded,
+ sanitized responses for recognized tools. Unknown tools and capture-excluded
+ file operations retained their existing content restrictions; buffering,
+ retry idempotency, and Stop/SessionEnd semantics were preserved. Corrected
+ the install guide's outdated claim that Codex lacks native SessionEnd (#697).
+- Reads no longer report an empty project after the daemon restarts
+ mid-session. The active-project pointer lives in process memory, so a
+ restart — the one the packages' own post-upgrade note tells you to run —
+ dropped it, and `memory_status`, `memory_briefing`, and every other
+ unscoped read then resolved through the baked default scope and answered
+ zero counts through the success path, with nothing in the log to
+ distinguish "scope unresolved" from "project genuinely empty". `serve` now
+ seeds a read-side fallback at startup from the most recently active project
+ recorded in the database, bounded by the same TTL as a per-key entry, so a
+ keyed miss right after a restart degrades to real data. The seed serves
+ reads only: keyed per-actor entries are never reconstructed, an unscoped
+ write resolves exactly where it did before, and the first hook event
+ supersedes the seed — so pre-publish and eviction reads keep degrading
+ exactly as they do today (#678).
+- The from-source AUR `PKGBUILD` now builds and tests on constrained AUR
+ builders. Release LTO was disabled (`options=('!debug' '!lto')`) so the
+ final link no longer gets OOM-killed on low-memory build hosts, and the
+ `check()` step pins `CARGO_HOME` to the registry `build()` already
+ populated before it repoints `HOME` at an empty test home, so the
+ `--frozen` test run can resolve the packages it fetched instead of
+ failing offline (#677).
+- CLI server errors now name the request. A non-2xx response from the
+ configured server printed only `server returned 404 Not Found: <body>`,
+ so a failure gave no clue which endpoint answered. The message now leads
+ with the request method and path: `GET /admin/open-sessions: server
+ returned 404 Not Found: <body>`. The error keeps the path only, so a
+ token in the URL userinfo or query string never reaches a log line. (#679)
+- Wiki auto-commits stage what the wiki wrote instead of walking the
+ whole tree, keep the repository open between commits, and no longer
+ drop the commit when another session is writing a file at the same
+ time. A session end now costs what it wrote, not the size of the wiki,
+ and the git history no longer silently misses snapshots under
+ concurrent sessions (#674).
+- The generated pi/omp and OpenClaw TypeScript integrations registered their
+ session-end lifecycle event (`session_shutdown` for pi/omp, `session_end`
+ for OpenClaw) with a synchronous, fire-and-forget handler. The host tears
+ down the runtime as soon as a synchronous handler returns, killing the
+ in-flight `session-end` POST before it completes, so the server never
+ learned the session had ended: `sessions.ended_at` stayed `NULL`, and no
+ summary or handoff was produced. The handlers are now `async` and await a
+ bounded (2s) drain of the pending request(s) before returning, mirroring
+ the joinable dispose-drain already used by the OpenCode integration (#676).
+- The `bin/ai-memory` container wrapper now matches multi-architecture image
+ manifests against the host's platform architecture, eliminating a
+ false-positive "a newer image is available on Docker Hub" warning on x86_64
+ and Podman. Additionally, `emit_docker_run_script` now preserves volume mount
+ modes (such as `:Z` on SELinux/Podman environments) and filters transient
+ runtime environment variables (`HOSTNAME`, `container=podman`). (#673)
+- `ai-memory serve` now stops on Ctrl-C and on SIGTERM, on both transports.
+ The stdio transport listened for no signal at all, and the HTTP transport
+ listened for SIGINT alone — so SIGTERM, what `docker stop`, `docker compose
+ down` and `systemctl stop` send, reached no handler on either. What that
+ cost depended on whether the server was PID 1. In the container it is (the
+ image's ENTRYPOINT is exec form, with no init shim), and for PID 1 the
+ kernel discards a signal whose handler is not installed: the signal was not
+ merely unhandled, it was invisible, so `docker stop` sat out its whole grace
+ period and ended in SIGKILL, `docker kill` was the only way out, and Ctrl-C
+ on stdio did nothing at all. Everywhere else — under the native systemd
+ unit, or a plain `ai-memory serve` in a terminal — the process is not PID 1,
+ so the same signal fell through to the kernel's default disposition and
+ killed it instantly instead, with no drain at all: the durable SessionEnd
+ consolidation worker was cut off mid-flight rather than drained. Both
+ transports now listen for SIGINT and SIGTERM, log which one arrived, and
+ bound the drain at five seconds so a stateful or SSE MCP client holding a
+ connection open cannot stall the exit — a stop that used to be instant and
+ unclean now takes up to those five seconds and drains. The listeners are
+ installed before the transport starts, so a signal arriving during a slow
+ boot — migrations, the pre-migration archive — is handled rather than lost,
+ and no container init shim (`tini`, `docker run --init`) is needed for the
+ server to stop as PID 1 (#699).
+
+## [2.1.1] - 2026-09-07
+
+### Changed
+- The managed routing snippet now states that ai-memory is the cross-harness
+ memory of record: when the surrounding harness has its own local memory
+ feature, durable project facts should be captured in ai-memory rather than
+ duplicated in a harness-local store that other agents cannot see (#671).
+
+### Fixed
+- A nested `.ai-memory.toml` marker whose only content is a `[capture]`
+ section (e.g. one that just sets `ignore_paths`) no longer resets scope
+ resolution to `default` / basename. The native binary, the POSIX shell
+ hooks, and the generated TypeScript integrations all used to resolve
+ `workspace`/`project` and the other forwarded root-level settings
+ (`project_strategy`, `drop_subagent_captures`, `[recall] default_global`,
+ `[briefing]` keys) from the single nearest marker — the same one that
+ decided `[capture]`/`ignore_paths` — so a capture-only marker in a
+ subdirectory silently shadowed an ancestor marker's declared
+ workspace/project and captures landed in the wrong scope. Scope and the
+ other forwarded settings now resolve from the nearest marker that
+ declares more than `[capture]`, while `[capture]`/`ignore_paths` keeps
+ reading the nearest marker unchanged — a marker that declares nothing
+ else is scope/settings-transparent. Applies to the native `ai-memory`
+ binary, the POSIX shell hooks (`hooks/_lib.sh`), and the generated
+ TypeScript integrations for every adapter that resolves scope client-side
+ (OpenCode, OpenCode2, pi, OMP, OpenClaw); outputs remain byte-identical
+ otherwise. (#668)
+- Wiki auto-commits no longer re-hash the whole tree. Since the #594 guard,
+ every commit cleared the git index and re-read every page, so a session
+ end cost the size of the wiki and grew with it; the LongMemEval harness
+ saw its ingest rate fall from 141 to 50 session ends a minute as the tree
+ grew. Staging now goes through libgit2's stat cache and re-hashes the tree
+ only when the tree write fails, which is the #594 case and is now covered
+ by a test that removes a blob from the object store. Commits on one wiki
+ are also serialized: two session ends at once used to collide on the index
+ lock, and the losing snapshot was dropped with a warning. (#665)
+- Preserved typed relation edges in multi-page consolidation. Batch updates
+ now include the same closed `causes` / `fixes` / `contradicts` schema as
+ single-page consolidation and carry non-empty relations into wiki
+ frontmatter and the link index, instead of silently discarding them. (#667)
+- OKF-conformed event ledgers are skipped by the indexer again, so a migrated
+ store stops growing without bound. The reserved-file check treated any
+ `log.md` / `log-YYYY-MM.md` carrying YAML frontmatter as an ordinary page,
+ but the OKF v0.2 migration stamps frontmatter on every `.md` under `wiki/`,
+ ledgers included. A migrated store therefore indexed its ledgers, and each
+ hook `append_event` superseded them: one `pages` row per appended line,
+ holding the whole multi-megabyte ledger body. One affected store reached
+ 6,539 page versions and 14 GB from 101 live pages within four days of
+ migrating. The check now reads past the frontmatter fence and classifies on
+ the first body line, so a real page that happens to be named `log.md` is
+ still indexed. (#660)
+- `install-hooks --apply --capture-mode allowlist` no longer captures
+ repositories with no `.ai-memory.toml` marker on the five generated
+ TypeScript integrations (`pi`, `omp`, `opencode`, `opencode2`,
+ `openclaw`). The native `ai-memory hook` path already gated every
+ lifecycle event on marker presence before spooling or sending anything
+ (`repository_admits_capture` in `ai-memory-hooks::capture_policy`), but
+ the generated adapters POST to `<server>/hook` directly and had only
+ ported the `ignore_paths` denylist logic into their shared
+ `capturePolicy` — never the allowlist admit gate — so an unmarked
+ repository was still fully captured while the CLI printed that the
+ protection was active. The shared template now bakes the selected
+ `--capture-mode` into a `CAPTURE_MODE` constant and gates on
+ marker *presence* (not on marker configuration state, so a marker with
+ an empty `[capture]` section still opts a repository in) before any
+ per-event disposition runs. The install-time "enforced"/"NOT in force"
+ messaging is corrected to match: a script-fallback install is now the
+ only path flagged as unenforced. (#661)
+- A UTF-8 BOM on a hand-edited wiki page that has no frontmatter no longer
+ rides into the page body. `markdown::parse` stripped the mark before looking
+ for the frontmatter fence, but the no-frontmatter path returned the untouched
+ input as the body, so the mark stayed in front of the first line. Two things
+ followed from that: `derive_title` no longer read the leading `# ` as a
+ heading, so the page was indexed under its filename instead of its title, and
+ the OKF v0.2 file pass (which conforms frontmatter and leaves the body alone)
+ re-emitted the mark after the closing `---` fence, where it is a stray
+ zero-width no-break space rather than a byte-order mark. Both paths now drop
+ the leading BOM, which is what the frontmatter path already did. (#663)
+- `serve` no longer re-archives the whole data dir on every start once a
+ monthly log ledger exists. The OKF conformance migration's
+ `nonconformant_files` scan flagged every frontmatter-less `log-YYYY-MM.md`
+ / `log.md` event ledger as a pre-OKF page (`okf::is_conformant` requires a
+ `type` key and a ledger has none), so the pre-migration backup gate saw a
+ non-empty pending list and took a full `tar.gz` snapshot on every boot —
+ the flip side of #660, which taught only the watcher's indexer to skip
+ ledgers by content. The migration scan now shares that same content-gated
+ check (a reserved-looking filename is excluded only when its first body
+ line is a hook log entry), moved into a shared `ledger` module so both
+ call sites stay in sync; a page literally named `log-2026-09.md` whose
+ body is prose is still migrated. (#669)
+- SessionEnd no longer writes an ephemeral `sessions/<id>.md` page for a
+ session that logged no real work. `is_lifecycle_only_session` treated a
+ session as skippable only when every observation was `SessionStart` or
+ `SessionEnd`, so a single `Stop` observation — which OpenCode fires for
+ purely internal work like branch-naming, alongside `session.created` +
+ `session.idle` with no user prompt and no tool use — was enough to make
+ the session look substantive and get a wiki page synthesized for it,
+ flooding the wiki with no-op session pages. "Substantive" is now defined
+ positively instead of negatively: a session counts as real work only if
+ it contains a `UserPrompt`, `PreToolUse`, or `PostToolUse` observation
+ (`is_ephemeral_session` in `ai-memory-hooks`). The atomic store-side
+ check (`end_lifecycle_only_session_in_tx` in `ai-memory-store`) moved to
+ the same positive `kind IN ('user-prompt', 'pre-tool-use',
+ 'post-tool-use')` test so the two stay in agreement, and the
+ PreCompact/PostCompaction checkpoint path gates on the same test rather
+ than only `observations.is_empty()`. Provider-agnostic: this fixes the
+ class for any harness that fires lifecycle-only `Stop`/`Notification`
+ events, not just OpenCode. (#662)
+
+## [2.1.0] - 2026-09-06
+
+### Added
+- Ordered LLM provider fallback chains (#648). `[[llm_fallbacks]]` in
+ `config.toml` configures one or more additional providers, each with its
+ own `provider`, `model`, optional `base_url`, and optional `api_key_env`
+ (the environment-variable *name* holding that profile's key — never the
+ key itself in config). The primary provider (`llm_provider`) always runs
+ first; fallbacks run only after a transient failure
+ (`LlmError::is_transient()`: 429, 5xx, timeout, connection error) advances
+ past the current candidate, in declaration order, with the original
+ request, JSON schema, and logical operation id preserved on every
+ attempt. A deterministic failure (400/401/403/404/422, an unsupported
+ schema, or a malformed response) still stops immediately — the same
+ policy a single provider already had. Each candidate carries a 30s
+ in-memory circuit: a transient failure opens it, a success closes it,
+ and a restart clears all circuit state. `Config::load` validates every
+ profile and resolves its credential once, at startup — a missing/empty
+ provider or model, an unknown provider, or a `RequiredApiKey` provider
+ with no resolved `api_key_env` fails startup rather than leaving a
+ latent fallback that only fails once the primary is already down; a
+ provider with a native credential source (OpenAI OAuth, Copilot) needs
+ no `api_key_env`. `GET /admin/status` (and `ai-memory status`) now
+ reports each candidate's provider/model label, last-selected/last
+ success/error state, and circuit-open-until timestamp alongside the
+ existing top-level LLM provider/model fields, which are unchanged for
+ every existing single-provider deployment.
+- `bootstrap --resume` recovers an interrupted run from durable per-chunk
+ progress instead of re-paying for every LLM call (#621). Each chunk's pages
+ are recorded (keyed by a fingerprint of the pruned sources + chunk budget, so
+ a re-run after new commits re-chunks and starts fresh) and `--resume` seeds
+ them and skips those chunks; the wiki write stays atomic (nothing lands until
+ the whole run completes) and progress is cleared on success. It adopts only
+ the **contiguous** prefix of completed chunks and re-runs from the first gap
+ or unreadable row (#635), so a resumed run can never diverge from a clean one
+ by seeding a later chunk with context an earlier, still-missing chunk never
+ produced. Complements the transient-retry from 2.0.3 (#617): retry reduces
+ how often you need resume; resume covers the crash / restart case.
+- Added first-party OpenCode 2.0 beta (`opencode2`) support.
+ `install-mcp --client opencode2` merges the V2 `mcp.servers` remote entry
+ (no `enabled` field, `oauth: false` for header credentials);
+ `install-hooks --agent opencode2` writes an `ai-memory-opencode2.ts`
+ plugin in the beta `{ id, setup }` shape (no runtime dependency:
+ `Plugin.define` is identity), with handoff injection through the
+ `context` hook and the same `session.*` lifecycle coverage as v1;
+ `ai-memory run opencode2` launches through the `opencode2` binary and
+ imports the beta `session_v2`/`session_message` transcript. The beta
+ shares v1's config dir, session store, and agent kind, so no store
+ migration ships. Verified live against beta-18999 (hook capture,
+ handoff loop, managed launch/resume/import, `opencode↔opencode2`
+ session resume). Two beta caveats are documented: back up
+ `~/.local/share/opencode` first (the beta has migrated the shared
+ database in place before), and move its background service off port
+ 49374 when ai-memory serves there. Managed ledger-delta
+ acknowledgement does not fire through the shared background service
+ (redelivery, never loss); see the managed-workstreams notes (#622).
+- `install-hooks --agent codex` now wires Codex's `SessionEnd` hook, so a
+ finished Codex session gets the same automatic end-of-session summary
+ and cross-agent handoff Claude Code already gets. Codex shipped a
+ first-class `SessionEnd` event in Codex CLI 0.145.0 (openai/codex#33895);
+ the `hooks/codex/session-end.{sh,ps1}` scripts already existed and only
+ needed adding to the Codex hook profile. On older Codex the event key is
+ inert; `ai-memory finalize-session --agent codex` remains the fallback.
+ `merge_codex_payload` no longer strips a `SessionEnd` key on every apply
+ — a third-party `SessionEnd` hook is preserved alongside ours. ([#604])
+- `AI_MEMORY_LLM_HEADERS` (`llm_headers` in `config.toml`) attaches extra
+ HTTP headers to every LLM chat request, for gateways that require a
+ caller-identifying header. Entries are `Name=Value` or `Name: Value`,
+ comma separated in the env var. Parsed and validated once at the
+ configuration boundary, so a malformed entry fails at startup rather than
+ on the first consolidation pass, and providers consume typed header
+ material instead of operator strings. Headers ai-memory sets itself
+ (`authorization`, `content-type`, `x-api-key`, `x-goog-api-key`,
+ `anthropic-version`, `anthropic-beta`, `openai-beta`, `host`,
+ `content-length`) are refused: `reqwest` appends rather than replaces, so a
+ duplicate would break the request instead of overriding it. Values are
+ marked sensitive on the wire and never logged — the `Debug` output carries
+ header names only. ([#606])
+
+### Changed
+- Every LLM chat request now sends `User-Agent: ai-memory/<version>`.
+ `reqwest` sends no user agent unless one is configured, so provider
+ requests previously arrived anonymous, and gateways that require callers to
+ identify themselves reported ai-memory as an unknown client. An
+ `AI_MEMORY_LLM_HEADERS` entry for `user-agent` overrides it. The Copilot
+ provider is unchanged: it keeps `GitHubCopilotChat/<version>`, the
+ editor-plugin agent GitHub's Copilot API expects. ([#606])
+- `x-opencode-session` and the `opencode` user agent, both shipped in 2.0.2,
+ are now operator-overridable like any other header: an
+ `AI_MEMORY_LLM_HEADERS` entry for either name takes precedence over the
+ provider's default. The default remains 2.0.2's — one `LlmOperationId` per
+ logical operation, stable across retries and the strict/tolerant fallback —
+ so nothing changes unless an operator asks for it. Override the session
+ header to tell several ai-memory instances apart in OpenCode's metrics.
+ ([#606])
+- The session-start brief's `[briefing] max_chars` now bounds the whole
+ rendered brief, and its floor rose from 500 to 1500 chars. The scaffold the
+ brief may never drop — the security notice plus both untrusted-history
+ markers and the closing instruction — costs 832 chars by itself, so any
+ budget under that could only ever have been honoured by dropping the
+ boundary that marks the brief as untrusted. A project whose marker sets a
+ smaller `max_chars` now gets 1500. (#657)
+- The build is self-contained on every platform: the vendored web stylesheet
+ is now the default and `TAILWIND_BUILD=1 cargo build -p ai-memory-web`
+ regenerates it, so no command needs `TAILWIND_SKIP=1` any more. CI
+ regenerates the bundle on Linux and fails if the committed
+ `static/tailwind.css` is stale, a check that did not exist before.
+- Developer loop: `cargo t` (everyday, skips `slow`/`stress` modules) and
+ `cargo tf` (everything) aliases over cargo-nextest, integration tests that
+ compile into each crate's own test harness from `tests/suite/` (78 test
+ binaries down to 11 in the everyday loop; only the CLI keeps a separate one,
+ and the evals harness builds only under `--workspace`), a dev profile that
+ keeps only line tables, and an opt-in pre-push hook that runs the full tier.
+ `bin/release` and the documented gate also run `git diff --check`. Measured:
+ workspace edit-to-result ~380s to ~150s on macOS; the warm everyday test run
+ 28s to 19s on a 32-thread Windows box.
+
+### Fixed
+- The `bin/ai-memory` container wrapper now runs on Podman without Docker
+ (#636). It auto-selects the engine (`AI_MEMORY_DOCKER` override → `docker` →
+ `podman`), defaults to the fully-qualified `docker.io/akitaonrails/ai-memory`
+ image so Podman's non-interactive short-name resolution does not fail, and
+ preserves the selected engine in the standalone-container recovery script
+ `ai-memory upgrade` emits instead of hard-coding `docker`.
+- The OpenCode provider now sends `gpt-5.6-luna` requests to OpenCode Go's
+ Responses endpoint. Luna is not served through Chat Completions, where plain
+ and structured ai-memory calls returned HTTP 500 (#618).
+- `AI_MEMORY_LLM_BASE_URL` now works with `AI_MEMORY_LLM_PROVIDER=opencode`.
+ The provider hardcoded OpenCode's **Go** endpoint and the factory dropped
+ the configured base URL without a word, so Zen's general catalogue at
+ `https://opencode.ai/zen/v1` was unreachable through it — Zen and Go are
+ separate products, not two spellings of one. Go remains the default, so
+ existing setups are unaffected; an override keeps the `x-opencode-session`
+ default and the user agent, since both endpoints correlate requests the
+ same way. Model ids are per catalogue, so set `AI_MEMORY_LLM_MODEL`
+ explicitly when overriding. `OPENCODE_ZEN_BASE_URL` is deprecated in
+ favour of `OPENCODE_GO_BASE_URL`: the constant named Zen but has always
+ held Go's URL. It keeps its value, so code compiled against it is
+ unaffected. ([#606])
+- Fixed `purge-session` leaving the live `sessions/<id>.md` wiki file behind
+ after deleting the session's SQLite rows. The admin endpoint now removes the
+ scoped page file after the DB purge commits, reports actual cleanup through
+ `files_deleted` / `files_failed`, and marks `purge_session` observer webhooks
+ with `partial_failure: true` when file cleanup fails, so a later wiki reindex
+ cannot resurrect the purged session. (#653)
+- `[briefing] max_chars` is now the size of the brief the agent actually
+ receives. Page bodies were budgeted, but every section rendered *after*
+ them escaped the accounting: the truncation notice, the crowded-out core
+ page list, the recently-updated pointers, the closing untrusted-history
+ fence and the agent footer. The escape pass that neutralises an untrusted
+ `<!-- ai-memory:untrusted-history -->` marker inside a page body then
+ lengthened the text by a further 6 chars per marker, after the count. A
+ 4000-char budget rendered 6577 chars, and the 500-char floor rendered
+ 3054 — six times what the operator asked for, on every opted-in session
+ start. Bodies are now served first, the pointer sections are sized
+ against what the bodies left (the omitted list degrading to a bare count
+ when not even the paths fit), and the mandatory scaffold is reserved
+ before a single body char is spent. The regression test asserting this
+ was named `render_session_brief_enforces_budget` but only checked the
+ brief's contents, never its length. (#657)
+- Authentication-disabled HTTP servers now ignore stale or unexpected Bearer
+ headers and preserve anonymous access. Previously, a client retaining an old
+ `AI_MEMORY_AUTH_TOKEN` received `401 Unauthorized` even though the server
+ reported `auth=false`; invalid Bearers remain rejected whenever static or
+ human authentication is enabled. (#639)
+- Cursor sessions no longer land in the default `default/scratch` bucket.
+ Cursor sends the workspace directory only as `workspace_roots` — its
+ `sessionStart` / `sessionEnd` payloads carry no `cwd` key at all, and its
+ tool events send `cwd: ""` — so cwd resolution produced nothing and the
+ server fell back to its default project for every Cursor event. Both the
+ native `ai-memory hook` path and the POSIX/PowerShell hook scripts now read
+ `workspace_roots` (alongside Antigravity's `workspacePaths`) and treat an
+ empty `cwd` as absent rather than as an answer.
+- Cursor sessions are no longer attributed to `claude-code`. The Cursor CLI
+ also runs the hook commands declared in Claude Code's
+ `~/.claude/settings.json`, which `install-hooks --agent claude-code`
+ hardcoded to `--agent claude-code`, so a Cursor-driven session was stored
+ with `agent_kind = claude-code`. Hook payloads carrying Cursor's
+ `cursor_version` marker are now attributed to `cursor` regardless of the
+ `?agent=` the hook command declared.
+- A project that first materializes while the server is running is now
+ self-describing immediately, instead of only after the next startup
+ backfill (#643). Scope manifests (`_meta.md`) were written at startup and on
+ the rename/move admin paths, so a session in a checkout the server had not
+ seen before produced a scope directory with pages but no manifest. Stop the
+ server in that window and `reindex` could not rebuild that tree — the one
+ situation where an operator most needs the rebuild to work. The manifest is
+ now written with the scope's first page, one store lookup per scope per
+ process, byte-identical to what the backfill writes so restarts still do not
+ churn the wiki's git history. The startup backfill is unchanged and remains
+ the repair path for trees written by older releases.
+- `ai-memory reindex` now names the exact missing or unreadable scope
+ `_meta.md` path instead of collapsing the filesystem error to a bare `No such
+ file or directory (os error 2)`. This makes the existing startup-backfill
+ workaround discoverable when a scope was first created during the server's
+ last run. (#643)
+- Generated routing instructions and all project-scoped managed Agent Skills now
+ distinguish session-aware MCP clients from static clients. Static clients are
+ told to pass exact `workspace` + `project` values from `.ai-memory.toml` or
+ operator configuration on every project-scoped call, preventing another
+ session's last active project from capturing reads or writes; global searches
+ and global preference writes retain their scope-free argument rules (#372).
+- Consolidation prompt assembly no longer re-renders the whole observation
+ projection and re-scores every observation after each pruned one. With a few
+ hundred long observations the quadratic loop cost ~14s per prompt; pruning
+ now works from per-observation scores and block sizes computed once, with
+ byte-identical output.
+
+### Security
+- A purged project or workspace can no longer be resurrected by a later
+ `reindex` (#607, data-layer audit follow-up, item 2). `purge_project` /
+ `delete_workspace` commit the DB deletion first and remove on-disk files
+ afterward, best-effort; a crash or failure in that window left the markdown
+ directory (`_meta.md` included) on disk with no row, and `reindex` rebuilt
+ the scope from that manifest — silently undoing the purge. Each purge now
+ writes a `purged_scopes` tombstone in the same transaction as the deletion
+ (a whole-workspace delete uses a `zeroblob(16)` sentinel project id), and
+ `reindex_all` skips any tombstoned scope instead of recreating it. The
+ inert files are left for a later purge or manual cleanup; reindex stays
+ non-destructive.
+- Concurrent writes to the *same* page path are now serialized (#607, item 3).
+ Per-page writes take the shared side of the wiki mutation lock, so two
+ writes to one `(workspace, project, path)` could interleave their
+ file-rename and DB-upsert and transiently leave the on-disk markdown
+ disagreeing with the DB `is_latest` row (self-healing on reindex, no data
+ loss). A per-path async lock now serializes same-path writers while
+ different paths still proceed concurrently; batches acquire their paths in a
+ fixed global order so they cannot deadlock.
+
+## [2.0.3] - 2026-09-04
+
+### Changed
+- Release, Docker, and the `cargo install --git` snippet now build with
+ `--locked` (#628). Without it `cargo install` re-resolves dependencies and
+ ignores the committed `Cargo.lock`, so a source install could silently pull
+ a different `schemars` than the one tested — a plausible source of
+ build-to-build structured-output schema drift. A unit guard also asserts the
+ strict-schema normalizer keeps `required` equal to `properties` (and closes
+ open maps), catching that drift class at build time rather than in
+ production.
+- The `_pending/auto-improve/` sidecar no longer renders a `status:` line
+ (#624). It was written once at staging and could never change from
+ `pending` — no code path updates or garbage-collects the sidecar — so it
+ contradicted design principle 14 (SQLite owns approval status) and misled a
+ human (or a second agent) reading the file. Status lives in
+ `ai-memory pending-writes list` / SQLite; the sidecar is a staging-time
+ snapshot.
+
+### Added
+- `ai-memory status` and the pre-migration backup log now report the data
+ directory's **filesystem free space** (#629). The OKF-migration backup gate
+ proves the archive is writable but said nothing about disk headroom — an
+ operator whose 447 MB safety archive left 77 MB free had the store fail to
+ extend its WAL eight minutes later, unlogged, for hours. This is pure signal
+ (no threshold, no refusal): `status` shows `filesystem free:` beside the
+ storage figures, and the "pre-migration backup verified" line now carries
+ `dest_free_bytes`, so the same number is visible right before a migration.
+
+### Fixed
+- The pre-migration safety archive is now taken **before** the SQLite schema
+ is migrated, so it is a genuine pre-2.0 recovery point a 1.x binary can
+ reopen — restoring the documented "reversible upgrade" (#633). Previously the
+ archive was written inside the wiki migration, which runs *after*
+ `Store::open` has already advanced the DB schema, so the archived `db/` was
+ already at 2.x and a 1.x binary refused it — the documented rollback was
+ impossible. The snapshot now runs in the boot path before `Store::open`,
+ gated to the real 1.x→2.0 upgrade (a fresh install or already-migrated store
+ takes nothing, unchanged) and idempotent; the OKF migration reuses that
+ archive instead of taking a second one. An integration test asserts the
+ archived DB reflects the pre-migration state.
+- Typed edges (`relations`) now actually work on OpenAI-family providers
+ (#630). `ConsolidatedPage.relations` was an open map
+ (`BTreeMap<String, Vec<String>>`), which the strict structured-output
+ normalizer closes to `additionalProperties: false` — OpenAI strict mode
+ cannot express arbitrary-key maps — so the model was structurally unable to
+ emit any `causes`/`fixes`/`contradicts` edge on `openai`, `openai-oauth`,
+ `copilot`, `opencode`, or `openai-compat`; the 2.0 typed-edges feature was
+ silently dead there. `relations` is now a fixed three-field object
+ (`causes`/`fixes`/`contradicts`), which strict mode expresses and which
+ serializes to the identical `relations:` frontmatter — no migration, no
+ downstream change. A schema guard pins the fixed shape.
+- `finalize-session --agent hermes` (and `claude-desktop`, `crush`, `other`)
+ is accepted again (#623). These agents are captured and stored, but
+ `finalize-session` reused the install-oriented agent enum — which is
+ deliberately limited to agents with a first-party installer — so it rejected
+ them at parse time and their sessions could never be closed, summarised, or
+ consolidated. `finalize-session` is agent-agnostic, so `--agent` now accepts
+ any agent the store recognises (a genuine typo is still rejected);
+ `install-hooks`/`setup-agent` stay limited. A drift guard keeps the two sets
+ from diverging again.
+- generated TypeScript integrations (`--agent open-code`, `omp`, `pi`,
+ `openclaw`) authenticate again under `install-hooks --apply`. Since #552
+ the bearer is deliberately omitted from the rendered file and persisted to
+ the 0600 `<data_dir>/auth-token` file, but only the native hook runtimes
+ learned to read it back: the generated TS adapters kept rendering
+ `TOKEN = null` with no runtime resolution, so every request they make
+ (hook capture, spool drain, handoff fetch) goes out unauthenticated and is
+ rejected by a Bearer-enabled server. The templates now render a
+ `resolveToken()` helper (static embed, then `AI_MEMORY_AUTH_TOKEN`, then
+ the auth-token file) used by `authHeaders()` and the spool writer.
+ `fetchHandoff()` in the same adapters also ignored `response.ok`, so a
+ 401 error body could be injected into model context as if it were a
+ handoff; non-OK responses now return `undefined` like other failures.
- `bootstrap` now retries a chunk's LLM call on a transient error before
giving up, instead of letting one blip discard the whole multi-chunk run
(#617). A provider `5xx`/`429` or a transport timeout/connect failure on
diff --cc docs/llm-providers.md
index 3d0e69e5,2719665a..69391e24
--- a/docs/llm-providers.md
+++ b/docs/llm-providers.md
@@@ -191,14 -131,17 +191,17 @@@ request sends the query plus at most 3
to the configured provider; all values are JSON-encoded and treated as
untrusted data. A timeout, provider error, or incomplete/invalid score set
preserves the normal order. `global=true` and supplemental global-preference
- hits keep their existing non-RRF ranking. Concurrent provider calls are capped
- at four; saturated queries keep their local ranking without waiting.
+ at four; saturated queries keep their local ranking without waiting. If the
+ configured provider is too slow for interactive reranking, a judge-endpoint
+ adapter can serve the reranker leg in sub-second time while consolidation
+ keeps the hosted model — see
+ [`docs/jev-reranker-adapter.md`](jev-reranker-adapter.md).
Embeddings are optional and separate from the LLM provider. Set
-`AI_MEMORY_EMBEDDING_PROVIDER=openai`, `voyage`, `google`/`gemini`, or
-`openai-compat` when you want vector retrieval in addition to FTS5 + entity +
-graph-neighbor retrieval. `openai-compat` targets self-hosted engines
-(Ollama, LM Studio, vLLM): it needs no API key and requires explicit
+`AI_MEMORY_EMBEDDING_PROVIDER=openai`, `voyage`, `google`/`gemini`,
+`openai-compat`, or `copilot` when you want vector retrieval in addition to
+FTS5 + entity + graph-neighbor retrieval. `openai-compat` targets self-hosted
+engines (Ollama, LM Studio, vLLM): it needs no API key and requires explicit
`AI_MEMORY_EMBEDDING_BASE_URL`, `AI_MEMORY_EMBEDDING_MODEL`, and
`AI_MEMORY_EMBEDDING_DIM`. The optional `EMBEDDING_API_KEY` credentials the
embedder alone and is checked before `OPENAI_API_KEY` and `LLM_API_KEY`, so