Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: humanizer pass over the documentation
AkitaOnRailscd5b7bfe60ea
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.mdindex f944d28c..ec12d255 100644--- a/.github/pull_request_template.md+++ b/.github/pull_request_template.md@@ -25,23 +25,23 @@<!-- Check exactly one. This drives which release your change ships in(see CONTRIBUTING.md "Versioning and deprecation policy"). -->-- [ ] **Patch** — bug fix, no new surface-- [ ] **Minor** — additive: new flag/subcommand/MCP tool/config key,+- [ ] **Patch**: bug fix, no new surface+- [ ] **Minor**: additive: new flag/subcommand/MCP tool/config key,new agent harness or provider-- [ ] **Major (breaking)** — on-disk format, removed/renamed surface,- breaking MCP schema change — called out in "What changed" above+- [ ] **Major (breaking)**: on-disk format, removed/renamed surface, or+ breaking MCP schema change, called out in "What changed" above## CHANGELOG (merge gate)-- [ ] I added a `CHANGELOG.md` `[Unreleased]` entry — **required** for any+- [ ] I added a `CHANGELOG.md` `[Unreleased]` entry. It is **required** for anyuser-facing change: new flag / env var / endpoint / MCP tool / markerkey, changed behaviour, or an observable bug fix. (Exempt only forinternal refactors, dead-code removal, and test-only churn.)- [ ] Any changed **default** (flag behaviour, config default, env var,response shape) is called out explicitly in "What changed" above.-Reviewers treat a missing entry as blocking — adding it up front is what-keeps your PR merging on the first pass.+Reviewers treat a missing entry as blocking, so add it up front if you want+your PR to merge on the first pass.## Notes for reviewersdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 5ef020a8..1c959a87 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -94,12 +94,6 @@ the block's shell options stay inside it; a failing test run still fails thehook even when your own commands follow the block without `set -e`.Run the installer again to update an existing installation.-The managed test block clears Git's repository environment and disables global-and system Git configuration for Cargo and its children. Fixture commands can-then use their own repositories without inheriting the checkout being pushed.-The publishing Git process and other hook code retain their configuration.-Run the installer again to update an existing installation.-Companions have separate Cargo workspaces. Check each changed companion with`cargo fmt`, `cargo clippy --all-targets -- -D warnings`, and `cargo test`, passingits `--manifest-path`. Changes to the lifecycle relay also need the real-server@@ -120,15 +114,15 @@ subcommand, env var, HTTP/admin endpoint, MCP tool or tool-response field,observable bug fix. Internal refactors, dead-code removal, and test-onlychurn are exempt.-This has been the single most-forgotten obligation across review batches,-so reviewers treat a missing entry as **blocking** — the PR template has a+This has been the most often forgotten obligation across review batches,+so reviewers treat a missing entry as **blocking**, and the PR template has acheckbox for it. Follow the existing entry style (past-tense summary,trailing `([#NNN])` PR/issue reference) and place it under the right`### Added` / `### Changed` / `### Fixed` heading.## Workflow rules (condensed from AGENTS.md)-The full authoritative rules are in [`AGENTS.md`](AGENTS.md) — the single+The full rules are in [`AGENTS.md`](AGENTS.md), the singlecanonical agent/contributor rules file (`CLAUDE.md` is just a pointer toit). Short version:@@ -153,7 +147,7 @@ Highlights for contributors:- Config is read once at startup; never call `std::env::var` outside `Config::load`.- Atomic file writes only: tmp + rename + fsync; never write in-place.- Every wiki page is namespaced by `(workspace_id, project_id)`.-- The CLI is always a thin HTTP client to the running server — it never+- The CLI is always a thin HTTP client to the running server. It neveropens the SQLite file or the wiki directory directly.## Versioning and deprecation policy@@ -175,7 +169,7 @@ than the following major release.### How this affects your PR- Put your CHANGELOG entry under the heading that matches its semver- impact — `### Fixed` for bug fixes, `### Added` for new capabilities,+ impact: `### Fixed` for bug fixes, `### Added` for new capabilities,`### Changed` for altered behaviour. The maintainer reads the`[Unreleased]` section to pick the next version number, so a fix filedunder `Added` (or vice versa) can bump the wrong release.@@ -183,7 +177,7 @@ than the following major release.surface, changed MCP schema), say so explicitly in the PR descriptionso it gets the `breaking-change` label and is scheduled for the nextmajor instead of blocking patch/minor releases.-- Bug fixes ship in the next **patch** release, usually promptly —- they are not held for feature releases. Small additive features (a new+- Bug fixes ship in the next **patch** release, usually promptly, and+ are not held for feature releases. Small additive features (a newagent harness, LLM provider, install client) ship in the next**minor**.diff --git a/DATA_HANDLING.md b/DATA_HANDLING.mdindex a73e1af2..1413f3e8 100644--- a/DATA_HANDLING.md+++ b/DATA_HANDLING.md@@ -1,29 +1,29 @@# Data Handling-This page exists for reviewers who need a single place to answer "what data-does ai-memory collect, where does it live, and what (if anything) leaves the-machine" — typically a security, legal, or data-protection review ahead of-internal approval. It restates facts that already live in-[`SECURITY.md`](SECURITY.md), cited by section below, rather than making new-claims; if the two ever disagree, `SECURITY.md` is authoritative.+This page is for reviewers who need one place to answer "what data does+ai-memory collect, where does it live, and what (if anything) leaves the+machine", usually for a security, legal, or data-protection review ahead of+internal approval. It restates facts from [`SECURITY.md`](SECURITY.md), cited+by section below, and makes no new claims; if the two ever disagree,+`SECURITY.md` is authoritative.## Default: fully local, no telemetryai-memory does not phone home. There is no analytics, crash reporting, or-usage telemetry built into the binary. Everything it stores — wiki pages and-the SQLite database — lives under a single, operator-controlled data+usage telemetry built into the binary. Everything it stores (wiki pages and+the SQLite database) lives under a single, operator-controlled datadirectory on the local filesystem (`SECURITY.md`, "Local dataconfidentiality"). No data leaves the host unless one of the three opt-in-paths below is explicitly enabled — the **embedding provider** being the one-most likely to matter to a reviewer, since it's the default-on question of-whether stored content reaches a cloud API at all.+paths below is explicitly enabled. The **embedding provider** is the one+most likely to matter to a reviewer, since it decides whether stored content+reaches a cloud API at all.The out-of-the-box default is local-only: `config.default.toml` configuresin-process local embeddings (all-MiniLM-L6-v2, 384-dim) with no API key andno data egress. See [`docs/local-embeddings.md`](docs/local-embeddings.md).There is no encryption at rest in v1; ai-memory relies on OS filesystem-permissions (owner-only directories/files on Unix, ACLs on Windows —+permissions (owner-only directories/files on Unix, ACLs on Windows;`SECURITY.md`, same section).## The three opt-in paths that send data externally@@ -38,7 +38,7 @@ and each requires a deliberate config change to turn on.| `AI_MEMORY_RERANKER=llm` | each live query + bounded page titles/snippets |1. **Embedding provider.** This is the broadest path by far, and the one- most likely to answer a reviewer's actual question ("does our source+ most relevant to a reviewer's usual question ("does our sourcematerial reach a cloud provider?"). `OpenAiEmbedder`, `VoyageEmbedder`,and `GoogleEmbedder` each call their provider's embedding endpoint forevery page that needs a vector. This isn't limited to new writes:@@ -53,8 +53,8 @@ and each requires a deliberate config change to turn on.requires a double opt-in: `capture_assistant` on the server *and*`install-hooks --capture-assistant` on the client. Once enabled, capturedtext rides in the session's automatic handoff to the next session and- flows into consolidation/reviewer prompts and — only if you have- separately configured a cloud LLM provider — is sent to that provider. The+ flows into consolidation/reviewer prompts. Only if you have separately+ configured a cloud LLM provider is it sent to that provider. Theflag is global to the install; there is no per-project exclusion once it'son.3. **LLM-based search reranking** (`SECURITY.md`, "Search reranking is an@@ -64,8 +64,8 @@ and each requires a deliberate config change to turn on.recalled snippets on-host.Paths 2 and 3 pass through a sanitizer that strips obvious credentials before-anything is transmitted; the sanitizer is documented as best-effort, not a-guarantee — see the "Stored-content prompt injection" and reranking notes in+anything is transmitted. The sanitizer is documented as best-effort, not a+guarantee; see the "Stored-content prompt injection" and reranking notes in`SECURITY.md` for the exact caveats. The embedding path (1) sends full pagetext to the provider's embedding endpoint and is not sanitized the same way,so it is the path to leave on `local` when stored content must not leave the@@ -73,8 +73,8 @@ server.## Is this "personal data" under GDPR?-ai-memory stores developer-authored artifacts — wiki pages, session-handoffs, entity extractions — derived from coding-agent sessions. It has no+ai-memory stores developer-authored artifacts (wiki pages, session+handoffs, entity extractions) derived from coding-agent sessions. It has nopurpose-built handling for personal data (no user-profile fields, noconsent-tracking, no data-subject-request tooling) because it isn't designedto process personal data as such. In practice this means:@@ -83,11 +83,11 @@ to process personal data as such. In practice this means:commit message with a name, or free text a developer typed), that data isstored and retained exactly like any other memory content, under your ownorganization's control on infrastructure you run.-- ai-memory does not transmit that content anywhere on its own; the two- opt-in paths above are the only export mechanisms, and both are under your+- ai-memory does not transmit that content anywhere on its own; the three+ opt-in paths above are the only export mechanisms, and all are under yourcontrol.- Treat this the same way you'd treat any local database your team- operates — your organization is the data controller and decides retention,+ operates: your organization is the data controller and decides retention,access, and disclosure. This document does not constitute legal advice;confirm classification with your own data-protection function.@@ -98,7 +98,8 @@ data path, so ai-memory does not create a data-processor relationship underGDPR Art. 28. If you configure a cloud LLM or embedding provider (for corefunctionality, capture, or reranking), **that provider** becomes yourprocessor for the data you send it, under whatever agreement you have with-them directly — ai-memory is a conduit, not a party to that relationship.+them directly. ai-memory passes the data along and is not a party to that+relationship.## Deletion / retention@@ -117,21 +118,21 @@ operator action, both on by default:Everything else persists until removed. Deletion is filesystem-level: removingthe data directory removes everything in it. For scoped deletion, a per-project-purge operation exists and is isolation-safe — it cannot delete files or rows+purge operation exists and is isolation-safe: it cannot delete files or rowsbelonging to a different `(workspace_id, project_id)` (`SECURITY.md`,"Per-project isolation").## Network exposure (if you run the server non-loopback)Binding the server beyond `127.0.0.1` is a separate, opt-in operational-choice unrelated to the data-export paths above — it controls who can reach+choice unrelated to the data-export paths above. It controls who can reachthe API, not what ai-memory sends externally. See `SECURITY.md`'s "Networkexposure when binding to non-loopback addresses" section and[`docs/https-via-proxy.md`](docs/https-via-proxy.md) before doing this.## Related documents-- [`SECURITY.md`](SECURITY.md) — threat model, scope, vulnerability reporting.-- [`docs/sso.md`](docs/sso.md) — enterprise identity/SSO integration.-- [`docs/airgapped-install.md`](docs/airgapped-install.md) — offline/air-gapped+- [`SECURITY.md`](SECURITY.md): threat model, scope, vulnerability reporting.+- [`docs/sso.md`](docs/sso.md): enterprise identity/SSO integration.+- [`docs/airgapped-install.md`](docs/airgapped-install.md): offline/air-gappedinstallation.diff --git a/README.md b/README.mdindex 91b4cb28..dcfa66b6 100644--- a/README.md+++ b/README.md@@ -16,74 +16,73 @@## Why ai-memory-Your coding agent already has a memory feature. Claude Code takes its own-notes, Cursor remembers some things, and every platform is adding more. All-of them share the same walls: the notes live on one machine, belong to one-agent, and vanish from view the moment you switch tools — or teammates.+Your coding agent probably has a memory feature already. Claude Code takes its+own notes, Cursor remembers some things, and every platform is adding more. They+all have the same limits: the notes live on one machine, belong to one agent,+and drop out of view when you switch tools or hand the work to a teammate.-ai-memory is what's on the other side of those walls.+ai-memory removes those limits.-- **It follows you across agents.** Twenty-plus harnesses — Claude Code,- Codex, Cursor, Gemini CLI, OpenCode, Grok, Devin, Kimi, Kiro, and more —+- **It follows you across agents.** More than twenty harnesses (Claude Code,+ Codex, Cursor, Gemini CLI, OpenCode, Grok, Devin, Kimi, Kiro, and others)feed one shared memory. Quit Claude Code mid-task, open Codex in the same- directory, and the next agent picks up a real handoff: where you left- off, what failed, what's still open. Handoffs are a protocol here, not a- convention — typed, owned, claimed exactly once.+ directory, and the next agent picks up a handoff that says where you left+ off, what failed, and what is still open. Handoffs are a typed protocol:+ each one has an owner and is claimed exactly once.- **It follows you across projects.** A small profile of how you usually- work — your package manager, test layout, architecture habits — reaches+ work (your package manager, test layout, architecture habits) reachesevery new repository at session start, so you stop re-explaining yourself.- It is a default below each repository's rules file, on by default for a- single user and opt-in, private per person, on a shared server.- See [`docs/cross-project-profile.md`](docs/cross-project-profile.md).+ It sits below each repository's rules file as a default. It is on by+ default for a single user, and on a shared server it is opt-in and private+ per person. See [`docs/cross-project-profile.md`](docs/cross-project-profile.md).-- **It follows you across machines.** Memory lives in a server you run —- on the same laptop, a homelab box, or wherever — so the project you left- on the desktop is the project you resume on the laptop. Same knowledge,- same open questions.+- **It follows you across machines.** Memory lives in a server you run, on+ the same laptop, a homelab box, or anywhere else, so the project you left+ on the desktop is the project you resume on the laptop, with the same+ knowledge and the same open questions.-- **It works for a team.** Point everyone at one server and what one+- **It works for a team.** Point everyone at one server, and what oneperson's sessions learn, everyone's agents can retrieve. Knowledge isshared per project; personal handoffs stay personal. Multi-user auth,- per-person attribution, and an audit log are built in — not a paid tier.+ per-person attribution, and an audit log are built in and are not a paid tier.- **Your memory is plain markdown.** The source of truth is a git-backedwiki of ordinary `.md` files: `grep` it, open it in Obsidian, edit it byhand, `rsync` it. The database is a derived index that can always be- rebuilt from the files. No vector store to babysit, nothing held hostage- in a binary blob.+ rebuilt from the files. There is no vector store to maintain and no+ content locked in a binary blob.- **It captures the work itself, silently.** Lifecycle hooks record what- actually happened — prompts, tool calls, session boundaries — sanitized- at a typed privacy boundary before anything is stored, then consolidated- into readable pages. No "remember this" ceremony. And the default path- uses **zero LLM calls**: capture, search, and handoffs all work with no- API key at all.--- **It ages gracefully, without an LLM.** Memory decays on a schedule you- can tune per tier, and the memory you actually use decays *slower* — open a- page, search it, or reach it through a link and it earns its keep. When- episodic notes go cold they can be compacted down to their durable facts- (file paths, error codes, decisions) instead of dropped, near-duplicates- collapse into one, and likely contradictions get flagged — all with **zero+ happened (prompts, tool calls, session boundaries), sanitize it at a typed+ privacy boundary before anything is stored, and the server consolidates it+ into readable pages. You do not have to ask it to remember anything. The+ default path uses **zero LLM calls**: capture, search, and handoffs all+ work with no API key.++- **It ages memory without an LLM.** Memory decays on a schedule you can+ tune per tier, and memory you use decays *slower*: opening a page,+ searching it, or reaching it through a link counts as use. When episodic+ notes go cold they can be compacted down to their durable facts (file+ paths, error codes, decisions) instead of dropped. Near-duplicates+ collapse into one, and likely contradictions get flagged, all with **zeroAPI calls**. Nothing is hard-deleted: the original stays in git and theversion chain (`restore-page` brings it back). Access-weighted retention is- always on because it can only ever keep memory *longer*; the parts that- rewrite or drop content (compaction, dedup, per-tier curves) stay off by- default until you turn them on.--- **And it can dream, if you let it.** Point it at an LLM and an opt-in- background pass will, while you're idle, rewrite whole clusters of cold- notes into single coherent pages — cancelling the moment you come back to- work. It never deletes a source (the pre-merge versions stay reachable),- it's off by default, and it's gated on a recall eval before it could ever- become default behavior. The zero-LLM path above is what runs unless you- ask for more.--- **It tells you the truth about itself.** One self-contained binary.- Purge commands that say exactly what "deleted" means. A measured write- ceiling (~700/s) instead of a guessed one. An audit log of every- mutation. Boring, in the way infrastructure should be.+ always on because it can only keep memory *longer*. The parts that rewrite+ or drop content (compaction, dedup, per-tier curves) stay off by default+ until you turn them on.++- **It can also "dream", if you let it.** With an LLM configured, an opt-in+ background pass rewrites whole clusters of cold notes into single coherent+ pages while you are idle, and cancels as soon as you come back to work. It+ never deletes a source (the pre-merge versions stay reachable), it is off+ by default, and it has to pass a recall eval before it could become+ default behavior. Unless you ask for more, the zero-LLM path above is what+ runs.++- **It is honest about itself.** It ships as one self-contained binary.+ Purge commands say exactly what "deleted" means. The write ceiling+ (~700/s) is measured, not guessed. An audit log records every mutation.## How it works@@ -97,17 +96,17 @@ capture ──▶ consolidate ──▶ recall ──▶ handoffAgents emit sanitized observations through lifecycle hooks as you work.At session end, observations become coherent markdown pages in theproject's wiki (optionally LLM-written; useful even without). The next-session — any agent, any machine — gets a bounded brief and can search+session, in any agent on any machine, gets a bounded brief and can searcheverything: full-text, entities, links, and (optionally) vectors, fused-into one ranking. Cross-agent handoffs carry the baton explicitly.+into one ranking. Cross-agent handoffs pass the baton explicitly.The full design, including the invariants that keep multi-user andmulti-session use safe, is in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).## Support matrix-Every row below is a first-party integration — MCP registration, lifecycle-hooks, or both — kept honest by CI. The full matrix with per-agent notes and+Every row below is a first-party integration (MCP registration, lifecycle+hooks, or both) checked by CI. The full matrix with per-agent notes andcaveats is in [`docs/support-matrix.md`](docs/support-matrix.md).| Area | Status |@@ -150,29 +149,29 @@ caveats is in [`docs/support-matrix.md`](docs/support-matrix.md).## Coming from another tool?-Most agent-memory tools optimize one thing — extracting atomic facts per turn,-a temporal knowledge graph, an agent-editable memory OS, or a hosted context-API. ai-memory optimizes something different: a **git-backed markdown wiki as-the source of truth**, with a derived index for retrieval, captured-automatically from lifecycle hooks, shared across agents, machines, and people,-and working with **zero LLM calls by default**. Here's what carries over from-each, and what you gain:+Most agent-memory tools optimize for one thing: extracting atomic facts per+turn, a temporal knowledge graph, an agent-editable memory OS, or a hosted+context API. ai-memory is built around a **git-backed markdown wiki as the+source of truth**, with a derived index for retrieval. It captures+automatically from lifecycle hooks, is shared across agents, machines, and+people, and works with **zero LLM calls by default**. This table shows what+carries over from each tool and what you gain:| Coming from… | What's similar | What you gain ||---|---|---|| **Mem0 / fact extractors** (LangMem) | Automatic per-turn capture | Memory compiles into readable **pages** you own and edit, not opaque fact rows; retrieval fuses FTS + entity + graph (+ optional vectors), not vector-only |-| **Zep / Graphiti** (temporal KG) | Temporal reasoning, typed relations | Bi-temporal-lite (`as_of`, version-filtered search) and typed edges without standing up a graph database — on one binary |-| **mcp-memory-service** (closest sibling) | SQLite + local embeddings, hook capture, typed edges, honest numbers — and, on 2.4, per-tier decay curves, extractive compression, DBSCAN cold-cluster dedup, access reinforcement, and contradiction flagging | Human-editable markdown **pages** instead of fact-rows, cross-agent claim-once handoffs, and the same aging machinery done **zero-LLM by default, reversibly** (supersede-not-delete + `restore-page`), and **off by default** |+| **Zep / Graphiti** (temporal KG) | Temporal reasoning, typed relations | Bi-temporal-lite (`as_of`, version-filtered search) and typed edges without standing up a graph database, in one binary |+| **mcp-memory-service** (closest sibling) | SQLite + local embeddings, hook capture, typed edges, honest numbers, and, on 2.4, per-tier decay curves, extractive compression, DBSCAN cold-cluster dedup, access reinforcement, and contradiction flagging | Human-editable markdown **pages** instead of fact-rows, cross-agent claim-once handoffs, and the same aging machinery done **zero-LLM by default, reversibly** (supersede-not-delete + `restore-page`), and **off by default** || **basic-memory** (file-first sibling) | Markdown-on-disk as the source of truth | Automatic lifecycle capture and a derived FTS/entity/graph index on top, cross-agent handoffs, and multi-user sharing built in |-| **Claude Code built-in memory** | "Remember my project" convenience, zero setup | Synced across machines and agents, searchable, team-capable, and captures tool lifecycle — not a per-laptop `MEMORY.md` |-| **Hindsight / OpenViking** (hosted, LLM-required) | Living pages / document memory with a background consolidation loop — and, on 2.4, belief-strength confidence plus an opt-in LLM "dream" rewrite of cold clusters | A self-contained binary that runs zero-LLM by default and keeps memory in files you own; per-project team sharing instead of strict per-bank isolation; the dream/belief features are **opt-in, off by default, and never delete a source** (vs a mandatory LLM loop) |-| **Supermemory / LiquidLM** (hosted memory API) | A managed second brain with automatic ingestion | Git-versioned markdown you own, no required API spend, offline operation, and per-project team sharing — ai-memory remembers *this repo*, not a general vault |+| **Claude Code built-in memory** | "Remember my project" convenience, zero setup | Synced across machines and agents, searchable, team-capable, and captures tool lifecycle, unlike a per-laptop `MEMORY.md` |+| **Hindsight / OpenViking** (hosted, LLM-required) | Living pages / document memory with a background consolidation loop, plus, on 2.4, belief-strength confidence plus an opt-in LLM "dream" rewrite of cold clusters | A self-contained binary that runs zero-LLM by default and keeps memory in files you own; per-project team sharing instead of strict per-bank isolation; the dream/belief features are **opt-in, off by default, and never delete a source** (vs a mandatory LLM loop) |+| **Supermemory / LiquidLM** (hosted memory API) | A managed second brain with automatic ingestion | Git-versioned markdown you own, no required API spend, offline operation, and per-project team sharing; ai-memory remembers *this repo*, not a general vault |-The consistent theme: **files you own** (git-backed markdown), a **zero-LLM-default**, **one self-contained binary**, **cross-agent + cross-machine + team**-sharing, **automatic lifecycle capture**, and **typed, claim-once handoffs**.+Across all of these, ai-memory gives you files you own (git-backed markdown),+a zero-LLM default, one self-contained binary, sharing across agents, machines,+and teams, automatic lifecycle capture, and typed, claim-once handoffs.Opt-in features (LLM consolidation, vector search, the "dream" consolidation-pass, belief-strength in ranking) stay opt-in — and the zero-LLM aging path+pass, belief-strength in ranking) stay opt-in, and the zero-LLM aging path(per-tier decay, extractive compaction, dedup, contradiction flagging,access-weighted retention) works with no API key at all.@@ -188,8 +187,8 @@ triplet embeddings),self-improvement loop), and [A-MEM](https://arxiv.org/abs/2502.12110)(Zettelkasten-style atomic notes).-The full, fair rundown — where each approach wins, where ai-memory differs, the-published benchmark — is in [How ai-memory compares](docs/comparison.md).+The full comparison, covering where each approach wins, where ai-memory+differs, and the published benchmark, is in [How ai-memory compares](docs/comparison.md).## Quick start@@ -237,7 +236,7 @@ A self-contained `.app` that bundles the native `ai-memory` binary and`hooks/` tree, starts the existing LaunchAgent, and opens `/web`,`ai-memory status`, and `config.toml` from the menu bar. Wiki, SQLite,config, and models stay in `~/Library/Application Support/ai-memory`, so-replacing the app is an update — it does not rewrite that tree.+replacing the app is an update and does not rewrite that tree.Needs a Rust toolchain and Xcode / Swift 6 (same as a source build):@@ -271,7 +270,7 @@ The published Docker image includes `linux/amd64` and `linux/arm64` variants,so Apple Silicon Macs and ARM64 Linux hosts can pull `akitaonrails/ai-memory`without `--platform linux/amd64` emulation.-The default quick-start has **no authentication** - the server binds+The default quick-start has **no authentication**. The server bindsto loopback only, so on a single-user laptop nothing else can reachit. Adding a bearer token is a one-line change once you're ready toexpose the server on the LAN; see [Security](#security) below.@@ -340,19 +339,19 @@ The examples use `docker`; replace it with `podman` on a Podman host. Thewrapper automatically uses Podman when Docker is not installed. Set`AI_MEMORY_DOCKER=podman` to force Podman when both engines are available.-On Linux/macOS, that's it. Start a Claude Code session as usual - every-prompt and tool call now lands in ai-memory, and the next session you-open in this project will see a handoff with where you left off.+That completes the setup on Linux/macOS. Start a Claude Code session as+usual: every prompt and tool call now lands in ai-memory, and the next session+you open in this project will see a handoff with where you left off.On macOS the native binary is the recommended path when you do not need-Docker — either the [menu bar app](#macos-menu-bar-app) above or a+Docker, either through the [menu bar app](#macos-menu-bar-app) above or a[release tarball / launchd agent](docs/macos.md). Later updates for thatpath use `ai-memory upgrade` (checksum-verified GitHub release replace + hook-refresh) — see+refresh); see[`docs/install.md#keeping-ai-memory-up-to-date`](docs/install.md#keeping-ai-memory-up-to-date).The same native upgrade path covers Windows x86_64 zip installs under awritable prefix (see [`docs/windows.md`](docs/windows.md) Scenario C).-Wiring another agent is the same two commands with a different name —+Wiring another agent is the same two commands with a different name:`--client codex`, `--agent codex`, and so on for every row of the supportmatrix. OpenCode is version-detected by host-side commands; when generating itsartifacts inside a container, use `setup-agent --agent opencode@@ -361,15 +360,15 @@ the host executable. The `opencode2` aliases remain force-V2 compatibilityspellings. The full per-agent guide, including Windows and remote servers, is[`docs/install.md`](docs/install.md).-Two agents in the same project at once, or teammates on one server? That-works out of the box: the "current project" pointer is isolated per caller+Two agents in the same project at once, or teammates on one server, work+out of the box: the "current project" pointer is isolated per callerby default (v1.39+). See [`docs/auto-scope.md`](docs/auto-scope.md) for theoptional session-aware Claude Code bridge and the details.**If in doubt, start your harness with `ai-memory run`.** It is the preferredway to launch: the first time it runs a harness it auto-installs that harness's-ai-memory hooks + MCP if they are missing (so capture and recall just work —-no separate `install-hooks`/`install-mcp` step to forget), it wires the right+ai-memory hooks + MCP if they are missing (so capture and recall work without+a separate `install-hooks`/`install-mcp` step to forget), it wires the rightproject scope by construction, and it adds cross-harness *session* continuity ontop of shared memory. Everything is idempotent and one-time per harness andconfig home. If the server is unreachable, `run` warns and launches anyway@@ -395,7 +394,7 @@ native process, and it cannot evict another authenticated operator's run. Seethe [managed-workstream recovery notes](docs/managed-workstreams.md#lease-recovery)for the full safety contract.-In `resume`, just type to search, use Up/Down to select a workstream, and Left/Right+In `resume`, type to search, use Up/Down to select a workstream, and Left/Rightto choose its harness. Enter launches the selection; Escape clears a search,then cancels when the search is empty (Ctrl-C always cancels).The list scrolls and loads every checkout-local page;@@ -424,7 +423,7 @@ This flake ships a NixOS module (`nixosModules.default`) with a`systemd.services.ai-memory` unit: a dedicated `ai-memory` system user(`nologin`, no linger) plus a hardened systemd sandbox(`ProtectSystem = "strict"`, empty capability sets,-`MemoryDenyWriteExecute`, `RestrictAddressFamilies`, and the rest — see+`MemoryDenyWriteExecute`, `RestrictAddressFamilies`, and the rest; see[`nix/systemd-sandbox.nix`](nix/systemd-sandbox.nix)). Packaged FHS unitsunder `packaging/systemd/` keep their existing lighter hardening.The flake exports packages for `x86_64-linux`, `aarch64-linux`, and@@ -466,7 +465,7 @@ small typed set for common keys, plus `freeformType` for the rest of`config.toml`). The module renders a generated TOML file and passes`--config`. Top-level `bind`, `port`, and `enableWeb` win over duplicatesettings keys. Anything in `settings` (including `llm_headers`) lands in a-world-readable Nix store path — do not put API keys there.+world-readable Nix store path, so do not put API keys there.Secrets such as `AI_MEMORY_AUTH_TOKEN` never go in `settings` or theworld-readable Nix store. This includes `llm_headers`, which can carry API@@ -474,10 +473,10 @@ credentials; set `AI_MEMORY_LLM_HEADERS` in `ageSecret`, `sopsSecret`, or`environmentFile` instead. These three secret sources are mutually exclusive.Non-loopback binds require one; loopback may omit them and tolerates a missingenvironment file (systemd `EnvironmentFile=-…`). Put TLS in front of a LAN/WAN-bind — see [`docs/https-via-proxy.md`](docs/https-via-proxy.md).+bind; see [`docs/https-via-proxy.md`](docs/https-via-proxy.md).All options and defaults are in [`nix/nixos-module.nix`](nix/nixos-module.nix).-Entirely opt-in — `nix build`, `nix run`, `nix develop`, and the CLI are+The module is entirely opt-in: `nix build`, `nix run`, `nix develop`, and the CLI areunchanged if you don't import it.## Everyday use@@ -498,25 +497,24 @@ readable wiki pages; the next session starts with a handoff.`ai-memory restore-agents -i agent-assets.tar.gz`, then add `--apply` onlyafter reviewing the active skills, plugins, instructions, and destinations.-The full tour — search modes, entities, feedback, briefings, the web-API — is in [`docs/usage.md`](docs/usage.md) and+Search modes, entities, feedback, briefings, and the web API are covered in [`docs/usage.md`](docs/usage.md) and[`docs/use-cases.md`](docs/use-cases.md).## Teams and multiple machines-Run the server somewhere reachable — a homelab box, a LAN host — and+Run the server somewhere reachable, such as a homelab box or a LAN host, andpoint every machine and every teammate at it. Knowledge is shared perproject; personal handoffs stay personal; every write is attributed andaudited. Multi-user auth (passwords, API credentials) is built in.Start with [`docs/users.md`](docs/users.md) for accounts and ownership,-and [`docs/deploy.md`](docs/deploy.md) for the server itself — including-capacity numbers measured rather than guessed, and the one rule that-matters: one server per data directory, never two.+and [`docs/deploy.md`](docs/deploy.md) for the server itself. It includes+measured capacity numbers and the one rule you must follow: one server per+data directory, never two.## Security-The quick-start default is loopback-only with no auth — nothing outside+The quick-start default is loopback-only with no auth, so nothing outsideyour machine can reach it. From there, hardening is incremental: a bearertoken for the LAN, per-user accounts, OIDC device auth for hooks, TLS viaa reverse proxy. Capture is sanitized at a typed privacy boundary before@@ -612,7 +610,7 @@ diagram, crate breakdown, schema notes, and invariants.## License-MIT - see [LICENSE](LICENSE).+MIT. See [LICENSE](LICENSE).## Acknowledgementsdiff --git a/SECURITY.md b/SECURITY.mdindex 0825f609..038401b4 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -46,11 +46,11 @@ what the project is and is not designed to defend against.**Inside a container this check warns instead of refusing.** Publishing aport with `-p` requires binding `0.0.0.0` in the namespace, so the bind- address says nothing about reachability there — that is decided by the+ address says nothing about reachability there. Reachability is decided by thehost-side publish spec, which the process cannot see. In a container thething to check is your own `-p`: `-p 127.0.0.1:49374:49374` is loopback-onlyand safe without a token; anything broader needs `AI_MEMORY_AUTH_TOKEN`.- Note the `Host` allowlist is not a substitute — it defends against DNS+ The `Host` allowlist is not a substitute: it defends against DNSrebinding, where a browser sets the header, and a client that can route tothe port sets `Host` freely. Authentication does not encryptbearer tokens, so use a TLS reverse proxy for traffic beyond loopback; see@@ -96,9 +96,9 @@ what the project is and is not designed to defend against.- **Assistant/Stop capture is opt-in and sanitized (#196).** The assistant'sfinal turn is never persisted by default. Storing it requires a **double- opt-in** — `capture_assistant` on the server and `install-hooks+ opt-in**: `capture_assistant` on the server and `install-hooks--capture-assistant` on the client. When enabled, be aware that:- - The excerpt is sanitized twice — the client scrubs with the built-in+ - The excerpt is sanitized twice. The client scrubs with the built-inpatterns *before* it reaches the spool or wire, and the server re-scrubswith its configured `[sanitize]` patterns before storing. Operator`extra_patterns` run only on the server side, so a secret matched only by an@@ -107,7 +107,7 @@ what the project is and is not designed to defend against.server's `allowlist` cannot restore text the client already replaced with`[REDACTED]`.- Captured assistant text flows into the consolidation and reviewer prompts,- and — if you configure a cloud LLM provider — is sent to that provider.+ and, if you configure a cloud LLM provider, is sent to that provider.The latest excerpt of a session also rides in its automatic handoff, sothe next session that claims the baton receives it as startup context. Itis not rendered into the git-tracked session page.diff --git a/companions/ai-memory-macos/README.md b/companions/ai-memory-macos/README.mdindex 4be08de9..1dddf60f 100644--- a/companions/ai-memory-macos/README.md+++ b/companions/ai-memory-macos/README.md@@ -1,6 +1,6 @@# AI Memory (macOS menu bar)-Self-contained macOS accessory app that **ships the `ai-memory` runtime**, **governs the LaunchAgent**, and **opens the surfaces the tool already has**. It is a wrapper, not a second operator console.+Self-contained macOS accessory app. It ships the `ai-memory` runtime, manages the LaunchAgent, and opens the surfaces the tool already has. It is a wrapper around those tools and does not add a second operator console.This companion is not a root Cargo workspace member. Durable memory stays in the user data directory so replacing the `.app` does not rewrite wiki, SQLite, config, models, or logs.@@ -12,9 +12,9 @@ This companion is not a root Cargo workspace member. Durable memory stays in the| LaunchAgent template | rendered plist in `~/Library/LaunchAgents/` || | logs in `~/Library/Logs/ai-memory/` |-Data directory: `~/Library/Application Support/ai-memory` (the binary’s existing macOS default). Optional override in Settings writes `AI_MEMORY_DATA_DIR` into the LaunchAgent plist only.+Data directory: `~/Library/Application Support/ai-memory` (the binary's existing macOS default). Optional override in Settings writes `AI_MEMORY_DATA_DIR` into the LaunchAgent plist only.-This app does **not** replace `ai-memory status`, `/web`, or hand-editing `config.toml`. Those stay the real tools; the menu opens them.+The app does not replace `ai-memory status`, `/web`, or hand-editing `config.toml`. You keep using those; the menu opens them.## Build@@ -35,12 +35,12 @@ AI Memory.app/Contents/Resources/runtime/packaging/launchd/com.github.akitaonrails.ai-memory.plist```-Drag the `.app` to `/Applications` for a stable LaunchAgent path. Notarization, Developer ID, and a Homebrew cask are out of this companion’s first version.+Drag the `.app` to `/Applications` for a stable LaunchAgent path. Notarization, Developer ID, and a Homebrew cask are out of scope for this companion's first version.## Use1. Open the app (menu bar extra; no Dock icon).-2. **Install & Start Server** — runs bundled `ai-memory init` if `config.toml` is missing, renders the existing launchd template, and `launchctl bootstrap`s `com.github.akitaonrails.ai-memory`.+2. **Install & Start Server** runs the bundled `ai-memory init` if `config.toml` is missing, renders the existing launchd template, and `launchctl bootstrap`s `com.github.akitaonrails.ai-memory`.3. The status item turns green when `GET /admin/status` succeeds.4. **Open Web UI**, **Show Status…** (bundled `ai-memory status`), **Open Config**, **Open Data Directory**, **Open Logs**.@@ -56,4 +56,4 @@ Root `cargo t` / `cargo tf` do not cover this package.## Open in Xcode-Open `companions/ai-memory-macos/Package.swift`. `swift run` from the package directory will not include the staged runtime; use `build.sh` (or set `AI_MEMORY_MENU_RUNTIME` at the tarball-equivalent `runtime/` directory) to govern the service.+Open `companions/ai-memory-macos/Package.swift`. `swift run` from the package directory will not include the staged runtime; use `build.sh` (or set `AI_MEMORY_MENU_RUNTIME` at the tarball-equivalent `runtime/` directory) to manage the service.diff --git a/companions/ai-memory-wikisync/README.md b/companions/ai-memory-wikisync/README.mdindex 17650d20..0eae6a9d 100644--- a/companions/ai-memory-wikisync/README.md+++ b/companions/ai-memory-wikisync/README.md@@ -1,6 +1,6 @@# ai-memory-wikisync-Read-only **team-wiki export** companion for+Read-only team-wiki export companion for[ai-memory](https://github.com/akitaonrails/ai-memory) (issue #986,slice 1). It pulls explicitly allowlisted page families from a runningai-memory server through the public, read-only `/api/v1` surface into a@@ -32,8 +32,8 @@ ai-memory-wikisync export ... --apply- `plan` never writes, not even the state file.- `export --apply` writes/updates markdown files under `--dest` and prints- the `git add` / `git commit` / `git push` commands you may run yourself —- the tool never runs git, never commits, never pushes.+ the `git add` / `git commit` / `git push` commands you may run yourself.+ The tool never runs git, never commits, and never pushes.- `--include FAMILY` is a strict, explicit allowlist of top-level wikidirectories (`_rules`, `decisions`, …). At least one is required and abare `*` is refused: only what you name is exported.@@ -43,16 +43,16 @@ ai-memory-wikisync export ... --apply## What it writes-Exactly the server's canonical page projection: `path`, `title`, `body`.+It writes exactly the server's canonical page projection: `path`, `title`, `body`.The page body (which carries its own `# H1` title) is transportedverbatim. The tool never forges attribution, generated, or syncfrontmatter into page files.-All local bookkeeping lives in **one** state file,+All local bookkeeping lives in one state file,`.ai-memory-wikisync/state.json` (mode 0600, atomically replaced aftereach successful write batch): per page, the SHA-256 of the bytes lastwritten plus the server `ETag` observed at that write. Nothing else is-stored — no tokens, no server credentials.+stored: no tokens and no server credentials.The state is per clone. The state directory carries a `.gitignore` of `*`,so committing the destination never commits the state: two clones that@@ -75,22 +75,22 @@ state; untrack it once with`--dest`; case-fold collisions are refused; symlinked destinations,symlinked components and symlinked state directories are refused; filesare replaced atomically (tmp + rename + fsync).-- **Local edits win until forced.** Each page is classified three ways —+- **Local edits win until forced.** Each page is compared three ways:destination file, last exported state, server body. A file that- diverged from both is reported with a diff summary and **refused**; the- whole batch is refused, nothing is written. `--force` overwrites the+ diverged from both is reported with a diff summary and refused; the+ whole batch is then refused and nothing is written. `--force` overwrites thedivergent files with server content.-- **Never deletes.** Local files — including brand-new local files inside- an allowlisted family — are never deleted. Deletes are slice 4.-- **Untrusted content.** Page bodies are data: transported verbatim,- never executed, never rendered, never interpreted. Paths that would+- **Never deletes.** Local files are never deleted, including brand-new+ local files inside an allowlisted family. Deletes are slice 4.+- **Untrusted content.** Page bodies are data. They are transported+ verbatim and never executed, rendered, or interpreted. Paths that wouldescape `--dest` are refused.## Roadmap (#986)This is slice 1 of the accepted team-wiki sync plan:-1. **This release — read-only export** into a project repository.+1. This release: read-only export into a project repository.2. Conditional mutation seam (compare-and-write) in core, if independentlyjustified.3. Bidirectional apply (repo edits flow back through public write tools).diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 80c6038f..8153513c 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -9,14 +9,14 @@ai-memory is a single Rust binary that gives the coding agents in the[README Support Matrix](../README.md#support-matrix), plus other MCP-capableclients, long-term memory shared across CLIs.-Quit one mid-task; open another in the same directory; continue. No-manual `write_note` ceremony, no copy-pasting summaries between-sessions.--The artifact you accrete is a **Karpathy-style LLM wiki**: a-git-versioned tree of markdown pages on disk that gets *compiled* over-time, appended-to. Pages are versioned in place via-supersession, semantic concepts compound, episodic logs decay. A+You can quit one mid-task, open another in the same directory, and+continue, without manual `write_note` calls or copy-pasting summaries+between sessions.++What accumulates is a **Karpathy-style LLM wiki**: a git-versioned tree+of markdown pages on disk that gets *compiled* and appended to over time.+Pages are versioned in place via supersession, semantic concepts build on+each other, and episodic logs decay. Acompanion SQLite index gives FTS5 + lexical entity + link-neighbor retrieval,with optional vectors; the markdown stays the source of truth.@@ -110,8 +110,8 @@ from hook paths.prompts preserve the source material's dominant natural language and askthe model to connect related pages with path-based wikilinks. The defaultsingle-page and batch prompts lead the user content with their stable- blocks — the fixed batch text (header + field schema) and the project- instructions — followed by the current body / slot and title state, and+ blocks (the fixed batch text, meaning header + field schema, and the+ project instructions), followed by the current body / slot and title state, andonly then the session id and observation dump, so providers with prefixcaching can reuse the stable prefix. In the single-page prompt the currentbody is the session's own page body (`sessions/<id>.md`), so it varies per@@ -155,7 +155,7 @@ from hook paths.compiled wiki pages miss entirely in default, explicit project, or explicit`scopes` mode, bounded raw observation FTS returns fallback `raw_hits`;`global=true` searches compiled wiki pages across projects only. Page hits- bump `access_count` + `last_accessed_at` - the M8 reinforcement term, which+ bump `access_count` + `last_accessed_at`, the M8 reinforcement term, which`memory_feedback` complements with explicit per-page salience. Identifiedoperators also add one `page_access` row per page; an opt-in`[decay] breadth_weight` can reward pages reinforced by several distinct@@ -177,7 +177,7 @@ from hook paths.together with entity-index rows orphaned by the purge. A newer page recreatedat the same path is preserved. Semantic / pinned / freshly-touched pagessurvive. A fourth pass, disabled unless `[decay] observation_retention_days`- is positive, then deletes raw `observations` older than that age — but only+ is positive, then deletes raw `observations` older than that age, but onlyfor sessions already consolidated into a summary page that is still live, soraw capture is never removed while it is the last copy of that session'swork. It runs last so this run's own evictions and hard-deletes already@@ -185,11 +185,11 @@ from hook paths.a multi-million row prune cannot hold the write lock, and repairs`sessions.ended_observation_count` downward in the same transaction. Theprune is irreversible in a specific sense: observations are the input to- consolidation, so a pruned session can never be re-consolidated — not with- a better model, a better prompt, or a fixed consolidator bug — and its+ consolidation, so a pruned session can never be re-consolidated (not with+ a better model, a better prompt, or a fixed consolidator bug), and itssummary page becomes the only surviving account of that session. Freed- SQLite pages are reused, not returned to the OS: the `.db` file does not- shrink, the backup tarball does.+ SQLite pages are reused rather than returned to the OS: the `.db` file does+ not shrink, but the backup tarball does.Scheduled sweep, rule-based lint, and opt-in embedding backfill ticksenumerate every existing workspace/project scope before doing per-projectwork, matching the auto-improvement scheduler's store-wide scope model. A@@ -361,8 +361,8 @@ and older clients cannot bypass it. The typed sanitizer boundary then applies aseparately gated Claude Code assistant/Stop excerpt remains capped at 2 KB.An optional RFC 3339 `occurred_at` on the hook body lets a client supply the-event's own original time — currently only `ai-memory backfill`, replaying a-transcript's per-event timestamps, so imported sessions/observations are+event's own original time. Currently only `ai-memory backfill` does this,+replaying a transcript's per-event timestamps, so imported sessions/observations arestamped with when they actually happened instead of import time. It is readfrom the top level of the body only (unlike the nested `payload`/`event`/`properties`/`info`/`path` search other hook fields use), so a real harness@@ -371,9 +371,9 @@ structure is never mistaken for this field. It is numeric metadata, not text,so it never goes through the sanitizer (outside invariant #6's boundary); itis still client-controlled input over `/hook`, so`HookEnvelope::occurred_at_micros` bounds it (must be > 0 and no more than-five minutes ahead of server time) before trusting it. Anything else —-missing, unparsable, or out of bounds — resolves to `None`, which the store-treats as "now", never an error, keeping hooks fire-and-forget (invariant #5).+five minutes ahead of server time) before trusting it. Anything else+(missing, unparsable, or out of bounds) resolves to `None`, which the store+treats as "now" rather than an error, keeping hooks fire-and-forget (invariant #5).A backfilled session's `ended_at` can therefore land well in the past, whichcan push it below the auto-improve watermark and the experience-pass anchor(both keyed on `ended_at`), and a retention window measured from an@@ -384,20 +384,20 @@ prunable rather than only after it ages in place.**Two layers, one source of truth.**-* `<data_dir>/wiki/` - markdown source of truth. Owned by a `git2`+* `<data_dir>/wiki/`: markdown source of truth. Owned by a `git2`repo so every consolidation pass + every session-end produces a- durable commit. Editable by hand in Obsidian / vim - the watcher+ durable commit. Editable by hand in Obsidian / vim; the watcherreconciles outside edits.-* `<data_dir>/db/memory.sqlite` - derived index. WAL mode. One+* `<data_dir>/db/memory.sqlite`: derived index. WAL mode. Onewriter actor owns the writer `Connection`; reads go through acloneable read-only pool.-* `<data_dir>/raw/` - immutable sanitized managed-workstream JSONL segments.+* `<data_dir>/raw/`: immutable sanitized managed-workstream JSONL segments.Legacy raw fallback recall searches the durable `observations` table viaFTS5; lifecycle HookEnvelope JSON is not a complete transcript archive.-* `<data_dir>/logs/` - rolling daily `tracing` output.-* `<data_dir>/models/` - reserved for bundled embedding models+* `<data_dir>/logs/`: rolling daily `tracing` output.+* `<data_dir>/models/`: reserved for bundled embedding models(M9.5+, when local `ort` lands).-* `<data_dir>/client-projects.json` - private, client-local checkout links for+* `<data_dir>/client-projects.json`: private, client-local checkout links for`ai-memory show`, keyed by credential-free server identity plus workspace andproject. It is not part of the SQLite/wiki source of truth, and no server APIexposes host paths.@@ -406,7 +406,7 @@ prunable rather than only after it ages in place.| Table | What ||---|---|-| `workspaces`, `projects` | Top of the 3-tuple identity coordinate. `projects.identity` / `identity_source` (V70, #708) hold the repository identity a project routes by — an explicit marker `identity` or a normalised git remote, resolved client-side — unique per workspace when set; empty until a capture claims the project. Phase-5 clients explicitly send `IdentityStyle::Path` (#1033) for remote-backed projects, naming them from the full repository path without the host (`acme-api`), and send explicit `host_path` for the pre-v3 opt-out. Server-side omission remains `HostPath` because old clients omitted that historical default; no new wire field is needed. Creation or authorized capture promotion uses that canonical name only when no different hostful identity claims it; otherwise resolution falls back to the existing hostful/legacy-safe name. V76 stores indexed canonical and v2-basename keys derived from that full identity: reads are no-create/no-rename, while an authorized explicit write through the canonical name promotes only `projects.name` in the same resolve-or-create writer transaction and preserves the UUID. Project `_meta.md` carries the optional full identity/source plus derived keys; clean reindex validates them and rebuilds the same UUID/name/coordinate lookup, while older manifests without identity remain valid. Ambiguous cross-forge or multi-candidate keys fail closed. A local marker may additionally send up to 16 validated former names as one transient `aliases` JSON-array query value: lookup stays inside its selected workspace, requires the checkout's full hostful git-remote identity to equal the stored row, returns reads without rename, and lets capture perform only the same authorized UUID-preserving canonical promotion. Aliases are not stored and remain distinct in the hook routing cache. The exact operator-home marker may additionally define bounded `[routes.identity."host/path"]` and `[routes.path."absolute-or-tilde-path"]` blocks: an exact hostful remote match wins the longest component-wise lexical path match, any reachable non-home local settings marker wins both, malformed or ambiguous route maps fail closed, and selected fields reuse the existing marker wire without a server/schema change. `AI_MEMORY_HOME` is authoritative for native callers; portable clients use `HOME`/`USERPROFILE`, and Docker compares its forwarded host cwd. See `docs/marker-file.md#repository-identity`. `projects.access_mode` (V68; `open` default / `restricted`) decides whether any authenticated user or only root, the creator (`projects.created_by`, V69) and grant holders (`project_grants`, V68) reach it, decided by `ai_memory_store::authorize_project` — `docs/users.md#per-project-access`. `projects.profile_contribute` / `profile_consume` (V74) record the marker's `[profile]` opt-outs, forwarded at session start; `profile_candidates`, `profile_harvest_marks` and `profile_entry_ledger` (V75) hold the profile pass's evidence, per-project read position and the entries it wrote. Reserved projects: `scratch`, `_global` (shared preferences; holds the single-user profile under `profile/`), `_profile` (a workspace profile) and `_profile.<user id>` (a private profile, always `restricted`); capture is never attributed to any of them — `docs/cross-project-profile.md`. |+| `workspaces`, `projects` | Top of the 3-tuple identity coordinate. `projects.identity` / `identity_source` (V70, #708) hold the repository identity a project routes by (an explicit marker `identity` or a normalised git remote, resolved client-side), unique per workspace when set; empty until a capture claims the project. Phase-5 clients explicitly send `IdentityStyle::Path` (#1033) for remote-backed projects, naming them from the full repository path without the host (`acme-api`), and send explicit `host_path` for the pre-v3 opt-out. Server-side omission remains `HostPath` because old clients omitted that historical default; no new wire field is needed. Creation or authorized capture promotion uses that canonical name only when no different hostful identity claims it; otherwise resolution falls back to the existing hostful/legacy-safe name. V76 stores indexed canonical and v2-basename keys derived from that full identity: reads are no-create/no-rename, while an authorized explicit write through the canonical name promotes only `projects.name` in the same resolve-or-create writer transaction and preserves the UUID. Project `_meta.md` carries the optional full identity/source plus derived keys; clean reindex validates them and rebuilds the same UUID/name/coordinate lookup, while older manifests without identity remain valid. Ambiguous cross-forge or multi-candidate keys fail closed. A local marker may additionally send up to 16 validated former names as one transient `aliases` JSON-array query value: lookup stays inside its selected workspace, requires the checkout's full hostful git-remote identity to equal the stored row, returns reads without rename, and lets capture perform only the same authorized UUID-preserving canonical promotion. Aliases are not stored and remain distinct in the hook routing cache. The exact operator-home marker may additionally define bounded `[routes.identity."host/path"]` and `[routes.path."absolute-or-tilde-path"]` blocks: an exact hostful remote match wins the longest component-wise lexical path match, any reachable non-home local settings marker wins both, malformed or ambiguous route maps fail closed, and selected fields reuse the existing marker wire without a server/schema change. `AI_MEMORY_HOME` is authoritative for native callers; portable clients use `HOME`/`USERPROFILE`, and Docker compares its forwarded host cwd. See `docs/marker-file.md#repository-identity`. `projects.access_mode` (V68; `open` default / `restricted`) decides whether any authenticated user or only root, the creator (`projects.created_by`, V69) and grant holders (`project_grants`, V68) reach it, decided by `ai_memory_store::authorize_project` (see `docs/users.md#per-project-access`). `projects.profile_contribute` / `profile_consume` (V74) record the marker's `[profile]` opt-outs, forwarded at session start; `profile_candidates`, `profile_harvest_marks` and `profile_entry_ledger` (V75) hold the profile pass's evidence, per-project read position and the entries it wrote. Reserved projects: `scratch`, `_global` (shared preferences; holds the single-user profile under `profile/`), `_profile` (a workspace profile) and `_profile.<user id>` (a private profile, always `restricted`); capture is never attributed to any of them (see `docs/cross-project-profile.md`). || `pages` | Versioned wiki pages with `is_latest` + `supersedes` chain. M8 columns: `last_accessed_at`, `access_count`, and decay-only tombstone marker `superseded_at`. M9 cols: `embedding_provider`, `embedding_model`, `embedding_dim`. V36: `expires_at` (frontmatter TTL). V37: `salience` (NULL = `salience_default`; derived from `page_feedback`). || `pages_fts` | FTS5 virtual table over `(title, body)`, auto-synced by triggers. || `sessions`, `observations` | Sanitized, bounded lifecycle-hook projections. `sessions.ended_observation_count` is the stable generation watermark for resumed-session re-end eligibility; wall clocks are not used for that decision. They are an operational audit trail, not a complete native transcript. |@@ -419,9 +419,9 @@ prunable rather than only after it ages in place.| `page_embeddings` | Optional vector rows for latest pages, with `(provider, model, dim)` denormalised so hybrid search can ignore stale vectors after an embedding config change and report missing-embedding diagnostics. || `page_feedback` | Append-only `memory_feedback` signals (`helpful` / `not_helpful` / `stale` / `wrong`) keyed by page *version*, with an optional sanitized reason and `salience_after`. Source of truth for the derived `pages.salience`; the lint pass reads unresolved stale/wrong rows joined against `is_latest = 1`, so a rewrite retires the finding. || `page_access` | One row per latest page and qualified operator identity. Supplies the optional access-breadth retention term without changing the existing shared access counter. |-| `page_evidence` | V63 append-only record of what produced or reaffirmed each page version — consolidation cites the `session` it ran on, written in the page-upsert transaction and cascaded on purge. Feeds a read-time, zero-LLM **belief-strength `confidence`** (`ai_memory_store::belief`, B1 / `docs/design-hindsight-borrowings.md` P2): a bounded `[0.0, 0.95]` function of distinct supporting sessions (breadth, not raw count), recency of the newest sighting, and live `contradicts` count. Exposed as `confidence` + `evidence_count` in `memory_query(explain=true)`, as `evidence_rows` in `memory_status`, and used to order the opt-in `settled_first` briefing — all **ranking-inert**. It folds into `PageAuthority` only behind `[retrieval] belief_authority_weight` (**default `0.0`/OFF, R2-gated**), as one bounded factor inside the `[0.55, 1.50]` clamp; a supersession always wins regardless of evidence (a superseded version is never boosted). |+| `page_evidence` | V63 append-only record of what produced or reaffirmed each page version: consolidation cites the `session` it ran on, written in the page-upsert transaction and cascaded on purge. Feeds a read-time, zero-LLM **belief-strength `confidence`** (`ai_memory_store::belief`, B1 / `docs/design-hindsight-borrowings.md` P2): a bounded `[0.0, 0.95]` function of distinct supporting sessions (breadth, not raw count), recency of the newest sighting, and live `contradicts` count. Exposed as `confidence` + `evidence_count` in `memory_query(explain=true)`, as `evidence_rows` in `memory_status`, and used to order the opt-in `settled_first` briefing, all **ranking-inert**. It folds into `PageAuthority` only behind `[retrieval] belief_authority_weight` (**default `0.0`/OFF, R2-gated**), as one bounded factor inside the `[0.55, 1.50]` clamp; a supersession always wins regardless of evidence (a superseded version is never boosted). || `agent_messages` | V64 cross-project message inbox/queue (`docs/agent-messaging.md`). Directed, claim-once mail from a sender coordinate to a recipient coordinate; `pending`→`claimed` (popped exactly once, the handoff compare-and-set) or `pending`→`cancelled` (sender retracts). The one table that crosses per-project isolation, so reads are keyed by the recipient coordinate (inbox) or sender coordinate (outbox); `from_owner_user`/`claimed_by_user` are attribution only, never a read filter. Recipient inbox depth is capped. `ON DELETE CASCADE` on both coordinate pairs. |-| `pages.compacted_at` | V65 nullable A2 tier-down marker (`docs/design-memory-aging.md` §A2). Set when the forget-sweep extractively compacts a cold episodic page (opt-in `[decay] compact_cold_episodic`) instead of evicting it; derived at the single page-upsert choke point from a `compacted: true` frontmatter mirror, so the marker and compacted body land in one transaction. Additive `ADD COLUMN`, no backfill — populated lazily by the sweep. The sweep and curator skip a marked page so it is never re-compacted, re-evicted, or re-reported as cold. Reversible: the full pre-compaction body stays in git + the supersession chain. |+| `pages.compacted_at` | V65 nullable A2 tier-down marker (`docs/design-memory-aging.md` §A2). Set when the forget-sweep extractively compacts a cold episodic page (opt-in `[decay] compact_cold_episodic`) instead of evicting it; derived at the single page-upsert choke point from a `compacted: true` frontmatter mirror, so the marker and compacted body land in one transaction. Additive `ADD COLUMN`, no backfill; the sweep populates it lazily. The sweep and curator skip a marked page so it is never re-compacted, re-evicted, or re-reported as cold. Reversible: the full pre-compaction body stays in git + the supersession chain. || `client_activity` | Server-wide MCP tool-call counters split into reads/writes and bucketed by UTC day. The MCP request choke point flushes buffered calls on a one-minute background interval; failed batches retry from bounded memory. Each day stores at most 128 sanitized client labels plus `other`, so an untrusted `clientInfo.name` cannot create traffic-proportional rows. || `auto_improve_proposals` | Staged learning and maintenance edits with immutable target snapshots and append-only decision events. Pending-target uniqueness is scoped by the qualified staging identity; unattributed proposals retain the historical shared bucket. || `entities`, `entity_page_links` | V38 noun index derived from canonical frontmatter. Names are normalized and unique per project; links target immutable page versions while retrieval filters to the latest version. Scope-pairing triggers prevent cross-project links. Powers the fourth RRF retrieval stream. |@@ -446,7 +446,7 @@ true`, the sweep runs a compaction pass *before* the decay-eviction pass: a coldepisodic page that is not already compacted is rewritten through the wiki layerto keep its L0 `abstract:`, an L1 first-paragraph summary, and an L2 regex-minedkeep-token set (paths, URLs, code spans, error codes, identifiers), dropping the-prose — instead of being tombstoned. The rewrite supersedes the prior version,+prose, instead of being tombstoned. The rewrite supersedes the prior version,so the full body stays reachable (git + supersession chain; `restore-page`recovers it). The `V65` `pages.compacted_at` marker makes a compacted pageterminal for the decay pass (never re-compacted, never re-evicted, never@@ -457,8 +457,8 @@ proof gates any future default-on.default-on).** Where A3 collapses near-duplicate cold clusters *extractively*(zero-LLM, keep-token union), the dream pass(`ai-memory-consolidate::dream::run_dream_pass`) hands each cold cluster to the-configured provider to be rewritten into ONE coherent page — the prose-coherent-merge extraction cannot do. It reuses A3's clustering math (`adaptive_eps` /+configured provider to be rewritten into ONE coherent page, a prose-coherent+merge that extraction cannot do. It reuses A3's clustering math (`adaptive_eps` /`dbscan`) over the *same* bounded cold set the forget sweep materialises(`sweep::materialize_cold_set`, invariant #2). It runs only when `[dream]enabled` is set AND a provider AND an embedder are configured; a provider-less@@ -468,14 +468,14 @@ member is *superseded* with a merge-note stub, so the full pre-merge body staysreachable (git + supersession chain; `restore-page` recovers it), and`page_evidence` (`reconsolidation` + `b2_dream:<id>`) records which members fedeach merge (the hallucinated-merge guard). The rewrite routes through the gated-apply path — `preflight_admission(Consolidate)` before the LLM, then-`Wiki::apply_batch` (single-writer actor, invariant #2) — with **`dry_run`+apply path (`preflight_admission(Consolidate)` before the LLM, then+`Wiki::apply_batch` on the single-writer actor, invariant #2) with **`dry_run`first** (returns the plan, calls neither the LLM nor the writer) and**JSON-schema structured output only** (invariant #7). Scheduling (B3, in`serve.rs`) starts a run only after `[dream] idle_window_secs` of no clientactivity (read from the tool router's shared `ActivityClock`) and **cancels it-the moment activity resumes** — a cheap `DreamCancel` flag polled between-clusters — bounded to `max_clusters_per_run` clusters per run (invariant #5).+the moment activity resumes** (a cheap `DreamCancel` flag polled between+clusters), bounded to `max_clusters_per_run` clusters per run (invariant #5).Work is ordered **surprisal-first** (B4): the most-novel clusters, farthest inembedding space from the nearest existing (non-cold) page, first. Every runreturns an observable `DreamReport` so a bad run is never silent. No new@@ -505,9 +505,9 @@ Pages normally link within their own project (`[[decisions/0001.md]]`, or a`label` pointing to `../gotchas/x.md`). A wikilink can also name another projectso that dependencies between projects become explicit edges in the graph:-* `[[project:path.md]]` — a sibling project in the same workspace.-* `[[workspace/project:path.md]]` — a project in another workspace.-* `[[_global:path.md]]` — the reserved `_global` preferences project in+* `[[project:path.md]]`: a sibling project in the same workspace.+* `[[workspace/project:path.md]]`: a project in another workspace.+* `[[_global:path.md]]`: the reserved `_global` preferences project inthe default workspace, even when the source page lives elsewhere.Bare `[[name]]` stays project-local; this is the form that names theshared scope. An explicit `[[workspace/_global:path.md]]` keeps the@@ -519,14 +519,14 @@ project's latest page and records the scope in `links.to_workspace` /`links.to_project` (NULL = the source's own project, the common case).Resolution is deferred-safe: a link to a page that does not exist yetstays `to_page_id = NULL` and is repointed by-`refresh_incoming_links_for_path` when that page later lands — across-projects, not only within one.+`refresh_incoming_links_for_path` when that page later lands, both within+one project and across projects.Because `to_page_id` is a global id and `ReaderPool::page_links` joins byid without a project filter, a resolved cross-project link surfaces as a-backlink on its target for free; `RelatedPage` carries the source's+backlink on its target with no extra work; `RelatedPage` carries the source's`workspace` / `project` so the dependency is labelled and navigable. This-is what turns the per-project wikis into one dependency graph (see also+turns the per-project wikis into one dependency graph (see alsothe `memory_lint` dangling-ref check, the briefing dependents counts, andthe `/api/v1/graph` endpoint).@@ -573,22 +573,22 @@ does not need to ride on the public protocol change.| `memory_read_page` | read-only | Fetch the FULL body of a single wiki page by `path` or by top FTS5 hit for a `query`; optional `workspace` + `project` targets a named sibling workspace/project. Use when an agent needs more than the 24-word snippets from `memory_query`. `include_related=true` also walks the link graph outward from the page (bounded BFS reusing the `page_links` primitive per node: default 1 hop, hard cap 3, global visited set for dedup/cycle-safety, total-node cap 50, cross-project aware) and returns a `related` array of reachable pages, each labelled with its `depth` (hop distance) and `direction` (`link`/`backlink`); default-off is byte-identical (no `related` field). || `memory_read_session_observations` | read-only | Page through ONE session's raw hook observations (`ObservationRecord` with full sanitized body, capped per row by `body_max_chars`), restricted to the rows that landed in the resolved scope and to sessions the caller may see; `total` and `elided_other_scope` report the in-scope count and the rows the session left in another project. `session_id` omitted reads the latest completed visible session. || `memory_status` | read-only | Counts, paths, version, plus the `scope` that answered: `workspace`, `project`, and `resolved_by` (`explicit`, `session`, `shared_slot`, `startup_seed`, `default`, `default_after_mismatch`). Unscoped reads resolved by `startup_seed` or `default_after_mismatch` also log a server warning. |-| `memory_briefing` | read-only | Structured counts/activity/rules/slots/recent snapshot. Project-scoped snapshots also carry a bounded `pinned` list (up to 10) of the project's pinned latest pages (`pinned = 1`, newest first) as standing SessionStart hot-context — distinct from `slots`, which is keyed by the `_slots/` path prefix; empty and omitted from JSON when the project has no pins, so the default shape is unchanged. Opt-in `settled_first: true` leads with up to 8 of the project's highest-standing `rule`/`decision` pages, ordered by evidence count then recency; off by default. `scope` names the workspace/project briefed and `resolved_by` how it was chosen. |+| `memory_briefing` | read-only | Structured counts/activity/rules/slots/recent snapshot. Project-scoped snapshots also carry a bounded `pinned` list (up to 10) of the project's pinned latest pages (`pinned = 1`, newest first) as standing SessionStart hot-context, distinct from `slots`, which is keyed by the `_slots/` path prefix; empty and omitted from JSON when the project has no pins, so the default shape is unchanged. Opt-in `settled_first: true` leads with up to 8 of the project's highest-standing `rule`/`decision` pages, ordered by evidence count then recency; off by default. `scope` names the workspace/project briefed and `resolved_by` how it was chosen. || `memory_explore` | read-only | LLM prose digest over the briefing snapshot, degrading to JSON without a provider. An optional `reasoning` tier (`minimal` (default) / `low` / `medium` / `high` / `max`) scales the digest's max-token budget off its base (16 000; same 1x/1.5x/2x/3x/4x mapping as `memory_query`); inert on the no-provider briefing-only path, and `minimal` is byte-identical. || `memory_handoff_begin` | destructive | Open an owner-scoped handoff for the next agent; `shared=true` deliberately publishes it to the project. Optional `workspace` + `project` targets a named sibling workspace/project. || `memory_handoff_list` | read-only | List open own/shared handoffs with inspectable body and identity fields; does not claim or expire. Root-only `any_owner=true` recovers across operators. Optional `workspace` + `project` targets a named sibling workspace/project. || `memory_handoff_accept` | destructive | Fetch + ack an open own/shared handoff. Pass `handoff_id` from `memory_handoff_list` to claim that exact row; omitting it still claims the latest eligible open handoff (automatic handoffs are cwd-matched). Root-only `any_owner=true` recovers across operators. Optional `workspace` + `project` targets a named sibling workspace/project. Returns `handoff` plus `status`: `claimed` (this call won it), `consumed_by_hook` (the calling session's own SessionStart claimed it, so it is already in context; needs the session id the hook claimed under, i.e. a session-aware client), or `none_pending`. || `memory_handoff_cancel` | destructive | Mark an exact visible open handoff id expired when it was created by mistake; root-only `any_owner=true` recovers across operators. || `memory_message_send` | destructive | Send a directed cross-project message into another project's inbox (V64). Requires `to_workspace` + `to_project`; the recipient must already exist (fail-closed, never created). Body is secret-scrubbed and size-capped. Refuses an inferred sender scope (static clients pass `from_workspace` + `from_project`). The one tool that crosses project isolation on purpose. |-| `memory_message_list` | read-only | List pending mail for this project — `box="inbox"` (poppable, default) or `box="outbox"` (cancellable). Bodies are untrusted cross-project input. An inferred scope adds `resolved_scope` / `scope_source` / `hint`. |+| `memory_message_list` | read-only | List pending mail for this project: `box="inbox"` (poppable, default) or `box="outbox"` (cancellable). Bodies are untrusted cross-project input. An inferred scope adds `resolved_scope` / `scope_source` / `hint`. || `memory_message_pop` | destructive | Claim ONE inbox message exactly once (oldest, or a specific `message_id`); returns it fenced as untrusted input with sender provenance, or `null` when empty. Refuses an inferred scope. || `memory_message_cancel` | destructive | Retract a pending sent message by `message_id`, or clear the whole outbox when omitted. Scoped to the sender project; refuses an inferred scope. |`memory_handoff_list` is the inspect-without-claim path for clients that cannot inject SessionStart stdout. `memory_handoff_cancel` needs an exact id. `ai-memory handoffs` lists the open-handoffs for a project, oldest first, with their ids — read-only, and+handoffs for a project, oldest first, with their ids. It is read-only andcontent-free (identity, provenance and age, never the summary body). Automaticexpiry deliberately spares manual and sibling-directory handoffs, so a-long-lived entry appearing there is that policy working rather than a fault.+long-lived entry there is expected policy behavior, not a fault.| `memory_consolidate` | destructive | LLM-driven page rewrite. `multi_page=true` for atomic fan-out; an update whose path names an existing pinned page is skipped (`_slots/` excepted). Omitting `session_id` (or sending a blank one) consolidates the latest completed session in the resolved project; the same omission on a project with none fails as `no completed session in <scope>`. Consolidation prompts append the target project's active reserved `_prompts/consolidation.md` body as sanitized, 2,000-character-capped, JSON-encoded, untrusted advisory preferences; TTL-expired pages are ignored and a per-call `instructions` argument overrides the page for one call. Both system prompts keep schema, evidence, disclosure, tool-use, and output rules authoritative. || `memory_feedback` | write | Record a quality signal for one page by exact `path`: `helpful`/`not_helpful` step `pages.salience` for sweep-eligible episodic pages, while `stale`/`wrong` floor salience and surface any current page as a `feedback_flagged` lint finding. Never deletes; the path resolves to the current version in the transaction, so a later rewrite clears it. Retrieved content never authorizes feedback by itself. |@@ -596,7 +596,7 @@ long-lived entry appearing there is that policy working rather than a fault.| `memory_write_page` | destructive | Write durable wiki knowledge when the user explicitly asks to remember/annotate it. `scope: "global"` writes into the reserved `_global` preferences scope and `scope: "profile"` into the caller's cross-project profile (path placed under `profile/`); optional `expires_at` sets an RFC3339 or date-only TTL; optional `session_id` cites a session of the same project as evidence, and on `sessions/<id>.md` stamps the session-page frontmatter and settles the queued consolidation job. || `memory_delete_page` | destructive | Delete a single page by exact `path`; `scope: "profile"` deletes from the caller's cross-project profile. Fires the admission chain (op=delete); idempotent. || `memory_forget_sweep` | destructive | Retention pass: evict cold pages through the wiki layer, purge aged tombstone ancestry, and hard-delete TTL-expired pages. `dry_run=true` for preview. |-| `memory_lint` | destructive | Rule-based + LLM contradiction findings → `wiki/_lint/`. Also runs a **zero-LLM contradiction detector** (design-memory-aging.md A5): cold semantic/procedural pages whose already-stored embeddings sit in the `contradiction_band_min`–`contradiction_band_max` cosine-similarity band (default 0.4–0.75; "same topic, not a near-duplicate" — at/above the max is A3 dedup, below the min unrelated) get an advisory `contradiction` finding with newer-wins timestamp advice. Bounded (one embeddings load over the capped cold set, capped findings, deterministic); a clean no-op with no embedder configured; advisory-only — never deletes/edits/supersedes a page and persists no edge (invariants #13, #16, #2), so no migration. On a single-language or single-domain store, background similarity between unrelated pages already sits well above the default floor, so the band measures domain proximity more than conflict and produces noisy findings — raise `contradiction_band_min` (`config.toml` or `AI_MEMORY_CONTRADICTION_BAND_MIN`) for such a store. |+| `memory_lint` | destructive | Rule-based + LLM contradiction findings → `wiki/_lint/`. Also runs a **zero-LLM contradiction detector** (design-memory-aging.md A5): cold semantic/procedural pages whose already-stored embeddings sit in the `contradiction_band_min`–`contradiction_band_max` cosine-similarity band (default 0.4–0.75; "same topic, not a near-duplicate"; at/above the max is A3 dedup, below the min unrelated) get an advisory `contradiction` finding with newer-wins timestamp advice. Bounded (one embeddings load over the capped cold set, capped findings, deterministic); a clean no-op with no embedder configured; advisory-only (never deletes/edits/supersedes a page and persists no edge, invariants #13, #16, #2), so no migration. On a single-language or single-domain store, background similarity between unrelated pages already sits well above the default floor, so the band measures domain proximity more than conflict and produces noisy findings, so raise `contradiction_band_min` (`config.toml` or `AI_MEMORY_CONTRADICTION_BAND_MIN`) for such a store. || `memory_install_self_routing` | read-only | Return the canonical slim routing snippet plus managed Agent Skill payloads and target hints for CLAUDE.md / AGENTS.md installs. |`memory_briefing`, `memory_explore`, `memory_write_page`,@@ -624,8 +624,8 @@ for mistaken handoff creation. `memory_feedback` implements the`prior-art-implementation-findings.md`: it cannot ride on a read toolwithout conflating read and write semantics, and the access counter itsupplements cannot tell "this page answered the question" from "this page-wasted a read". The narrow-surface discipline still holds —-every new tool has to earn its slot — but the count is now 23, not 10.+wasted a read". The narrow-surface discipline still holds (every new tool+has to justify its slot), but the count is now 23, not 10.The managed Agent Skills are a narrow prompt-packaging exception to theotherwise wiki-centered architecture. They are static `SKILL.md` files that@@ -697,10 +697,10 @@ telemetry report page for audit/approval without staging learning-memory edits.`reclaim-ledger-versions` drops the superseded versions of the raw hook eventledger that the pre-2.1.1 indexer left behind (#660). It is a dry run unless`--confirm` is passed. A path is only a candidate when its *content* opens-with a hook log entry — the same+with a hook log entry, using the same`ai_memory_core::log_ledger::body_opens_with_log_ledger` gate the indexer-(#660), the OKF conformance migration (#669) and the bundle export (#748) use-— so a real page named `log-2026-09.md` keeps its whole version chain. Only+(#660), the OKF conformance migration (#669) and the bundle export (#748) use,+so a real page named `log-2026-09.md` keeps its whole version chain. Only`is_latest=0 AND superseded_at IS NULL` rows are eligible, so rows a decaytombstone owns stay with `forget-sweep`. Derived FTS/entity/vector/link rowsgo with the page through the existing `ON DELETE CASCADE`s, and the FTS delete@@ -712,12 +712,14 @@ documents.## Cross-cutting invariants-Carved in M0/M1; every milestone has to respect them. Each comes from+Set in M0/M1; every milestone has to respect them. Each comes froma documented prior-art bug; cite the source when reviewing changesthat touch the relevant area.-1. **One config-read path.** `Config::load()` called once at startup.- No `std::env::var` outside it. (agentmemory #456 / #469.)+1. **One config-read path.** ai-memory's own settings are read once by+ `Config::load()` at startup and never re-read from the environment;+ code that must read process or harness environment takes an injectable+ lookup so tests can stub it. (agentmemory #456 / #469.)2. **Single-writer SQLite actor.** All writes go through one `mpsc`channel to one dedicated OS thread. (cognee #2717.)3. **Indexes commit in the same transaction as the data.** No@@ -1101,13 +1103,13 @@ GITHUB_COPILOT_API_TOKEN optional pre-minted Copilot API tokenCOPILOT_API_URL optional Copilot API base URL override```-**Ordered LLM fallback chain** (opt-in, TOML only — see+**Ordered LLM fallback chain** (opt-in, TOML only; see`docs/llm-provider-fallback.md`, #648): the primary provider above alwaysruns first; `[[llm_fallbacks]]` entries run only after a transient failure(429, 5xx, timeout, connection error), in declaration order, with theoriginal request/schema/operation id preserved on every attempt. Adeterministic failure (4xx other than 429, an unsupported schema, a-malformed response) still stops on the first candidate — no chain-wide+malformed response) still stops on the first candidate, with no chain-wideretry loop.```toml@@ -1129,7 +1131,7 @@ api_key_env = "GEMINI_API_KEY"`api_key_env` is required for any provider that needs an API key(`anthropic`, `openai`, `gemini`, `opencode`; optional for `openai-compat`,-which may run keyless) — it is never inherited from the primary's own+which may run keyless). It is never inherited from the primary's ownfixed env var, so a fallback cannot look configured while actuallyresolving no credential. It is optional only for a provider with a nativecredential source (`openai-oauth`, `copilot`, `anthropic-oauth`), which@@ -1140,7 +1142,7 @@ credential fails startup rather than leaving a latent fallback that onlyfails once the primary is already down. Each candidate carries its own30s in-memory circuit (`ai_memory_llm::fallback::CIRCUIT_COOLDOWN`): atransient failure opens it, a success closes it, and a restart clears all-circuit state — there is no durable circuit or forced chain-wide deadline.+circuit state. There is no durable circuit or forced chain-wide deadline.`GET /admin/status` (`ai-memory status`) reports an `llm_candidates` listalongside the existing `llm`/`embedding` roles: each candidate's@@ -1152,9 +1154,9 @@ timestamp. It is empty for a plain single-provider setup; the top-levelEvery chat request carries `User-Agent: ai-memory/<version>`(`ai_memory_llm::DEFAULT_USER_AGENT`, layered in `build_provider`). `reqwest`-sends no user agent unless configured, so provider requests used to arrive-anonymous — which gateways that require callers to identify themselves report-as an unknown client. `AI_MEMORY_LLM_HEADERS=user-agent=...` overrides it. The+sends no user agent unless configured, so without this header provider+requests arrive anonymous, and gateways that require callers to identify+themselves report them as an unknown client. `AI_MEMORY_LLM_HEADERS=user-agent=...` overrides it. TheCopilot provider keeps `GitHubCopilotChat/<version>` instead, theeditor-plugin agent GitHub's Copilot API expects.@@ -1195,7 +1197,7 @@ EMBEDDING_API_KEY optional embedding-only key; checked before````EMBEDDING_API_KEY` credentials the embedding role alone, so the embedder can-target a different provider than the chat model — `openai` on `api.openai.com`+target a different provider than the chat model: `openai` on `api.openai.com`for the LLM, a cheaper or self-hosted OpenAI-compatible endpoint for vectors.Without it the `openai` embedder takes `OPENAI_API_KEY`, then `LLM_API_KEY`when a custom embedding base URL is set, exactly as before. `voyage` and@@ -1210,8 +1212,8 @@ under the distinct `provider="openai-compat"` identity.`copilot` takes no API key at all: it resolves the same `CopilotAuth` as the`copilot` LLM provider (`auth login copilot`, `COPILOT_GITHUB_TOKEN`, or`GITHUB_COPILOT_API_TOKEN`) and shares its GitHub-token -> short-lived-Copilot-API-token exchange (`CopilotAuthState` in `ai-memory-llm::copilot`) —-no separate exchange path. It defaults to `text-embedding-3-small` / dim 1536+Copilot-API-token exchange (`CopilotAuthState` in `ai-memory-llm::copilot`)+rather than a separate exchange path. It defaults to `text-embedding-3-small` / dim 1536and calls Copilot's `/embeddings` endpoint with the same `vscode-chat`integration headers as chat. That endpoint's wire shape follows theOpenAI-compatible contract Copilot documents for chat, not a published@@ -1219,9 +1221,9 @@ embeddings spec, and is not covered by a live test against Copilot here.## Future work-* **M9.5 - local embeddings via `ort`.** Bundle `bge-small-en-v1.5`+* **M9.5: local embeddings via `ort`.** Bundle `bge-small-en-v1.5`for an API-key-free homelab path. ~200 MB image bloat; trait is- ready, just needs the `OrtBgeSmallEmbedder` impl + tokenizer wiring.+ ready and only needs the `OrtBgeSmallEmbedder` impl + tokenizer wiring.* **`sqlite-vec` integration.** Brute-force cosine works fine to a fewthousand pages; past that, the `sqlite-vec` extension is the nextstep. See [`docs/vector-backend-policy.md`](vector-backend-policy.md)@@ -1233,33 +1235,33 @@ embeddings spec, and is not covered by a live test against Copilot here.future work can add individual merge/supersession/link-fix proposals whilekeeping deletes and semantic rewrites review-gated.* **Richer read surfaces for the web UI.** The multi-workspace read-only- wiki browser shipped in `ai-memory-web` (`/web` — project list, page+ wiki browser shipped in `ai-memory-web` (`/web`: project list, pagetree, page view, search, and the root-only `/web/pending` triage page,whose approve and reject buttons post to the existing`/admin/pending-writes/*` routes). It stays read-only by design: the wiki is amachine-authored record, and a browser edit surface would break the- invariant the whole store rests on (#482). Better *reading* — richer- navigation, diff/history views, graph exploration — is open. See+ invariant the whole store rests on (#482). Better *reading* (richer+ navigation, diff/history views, graph exploration) is open. See[`docs/frontend-api.md`](frontend-api.md#10-known-gaps-and-deliberate-non-goals).* **Real LongMemEval-S harness.** The recall-eval framework exists- ([`crates/ai-memory-consolidate/tests/recall_eval.rs`](../crates/ai-memory-consolidate/tests/recall_eval.rs));+ ([`crates/ai-memory-consolidate/tests/suite/recall_eval.rs`](../crates/ai-memory-consolidate/tests/suite/recall_eval.rs));porting LongMemEval-S itself requires the dataset.## Reading order-* This file - operational summary, you are here.-* [`docs/design-decisions.md`](design-decisions.md) - the full v1 spec.-* [`docs/research-karpathy-llm-wiki.md`](research-karpathy-llm-wiki.md)- - what "Karpathy-faithful" means.+* This file: operational summary, you are here.+* [`docs/design-decisions.md`](design-decisions.md): the full v1 spec.+* [`docs/research-karpathy-llm-wiki.md`](research-karpathy-llm-wiki.md):+ what "Karpathy-faithful" means.* [`docs/research-agentmemory.md`](research-agentmemory.md),[`research-basic-memory.md`](research-basic-memory.md),[`research-cognee.md`](research-cognee.md),[`research-ecc.md`](research-ecc.md),- [`research-codebase-memory-mcp.md`](research-codebase-memory-mcp.md) -+ [`research-codebase-memory-mcp.md`](research-codebase-memory-mcp.md):prior art studied.-* [`docs/auto-improvement-loop.md`](auto-improvement-loop.md) -+* [`docs/auto-improvement-loop.md`](auto-improvement-loop.md):Hermes Agent-inspired learning-loop research and safety boundaries.-* [`docs/issues-*.md`](.) - concrete failure modes we've designed to+* [`docs/issues-*.md`](.): concrete failure modes we've designed toavoid.-* [`CLAUDE.md`](../CLAUDE.md) - per-session operating rules pinned+* [`CLAUDE.md`](../CLAUDE.md): per-session operating rules pinnedinto Claude Code conversations.diff --git a/docs/MIGRATION-2.0.md b/docs/MIGRATION-2.0.mdindex 2a28511e..a2a9d50c 100644--- a/docs/MIGRATION-2.0.md+++ b/docs/MIGRATION-2.0.md@@ -1,21 +1,21 @@# Upgrading to 2.02.0 changes the wiki's on-disk format to the [Open Knowledge Format-v0.2](okf.md). The upgrade is automatic, backup-gated, and reversible.-This page describes exactly what happens and how to go back.+v0.2](okf.md). The upgrade is automatic, runs only after a backup succeeds,+and is reversible. This page describes what happens and how to go back.> **The safety archive is a true pre-migration recovery point.** It is> written **before** the SQLite schema is migrated forward (#633), so its> `db/` is still at the 1.x schema and restoring it lets you start the old> 1.x binary again. (Earlier 2.0.x builds took this archive *after* the DB-> migration, which left it 2.x-only — fixed in 2.0.3.)+> migration, which left it 2.x-only; fixed in 2.0.3.)## What happens on the first 2.0 startWhen `ai-memory serve` starts on a data directory created by 1.x, aone-shot wiki migration runs before the server accepts any traffic:-1. **A full backup is taken first — or nothing happens at all.** The+1. **A full backup is taken first, or nothing happens at all.** Theentire data directory (wiki files, SQLite database, config) iscompressed to a timestamped archive in your home directory:@@ -27,20 +27,20 @@ one-shot wiki migration runs before the server accepts any traffic:home is small; the destination must be outside the data directory.The archive is re-opened and verified after writing. **If the backupcannot be written or verified, the migration aborts and the server- refuses to start** — your data is untouched and the error says why.+ refuses to start**. Your data is untouched and the error says why.The walk skips the runtime `.serve.lock` file (and its- `.serve.lock.holder` sidecar) so the initial-start abort seen on- Windows — where the same `serve` process holds that lock under a- mandatory exclusive `LockFileEx`, making the backup read fail with- `os error 33` — cannot happen. If you are on 2.0.0/2.0.1 and still+ `.serve.lock.holder` sidecar), so the initial-start abort seen on+ Windows cannot happen. There, the same `serve` process holds that lock+ under a mandatory exclusive `LockFileEx`, which made the backup read fail+ with `os error 33`. If you are on 2.0.0/2.0.1 and stillhit it, dropping the container/process (or using a byte-range decoylock above the first 64 KiB with `serve --force`) unblocks theone-time migration; a later patch releases these notes.2. The wiki git history gets a `pre-okf-migration checkpoint` commit.-3. Every page's frontmatter is rewritten **in place** — same page ids,+3. Every page's frontmatter is rewritten **in place**: same page ids,same version rows, bodies untouched, timestamps untouched. No pageis superseded, embeddings stay valid, nothing looks freshly edited.@@ -60,14 +60,14 @@ that never configured an embedding provider: the first start downloadsthe ~87 MB model in the background (checksum-pinned, to`<data_dir>/models/`), the next start enables hybrid search, andexisting pages are embedded automatically by a startup backfill. No-data leaves the machine — inference is in-process. Hosts that cannot+data leaves the machine, because inference is in-process. Hosts that cannotfetch the model keep the old FTS-only behaviour with a warning. Optout with `embedding_provider = "none"`; installs with a configuredprovider are untouched.## Running in a server or container (docker deploys)-Inside a container the home directory is **ephemeral** — it lives in+Inside a container the home directory is **ephemeral**. It lives inthe container layer and is destroyed on the next `docker compose up-d` recreation, which would silently lose the safety archive. Themigration detects containers (the official image's@@ -87,8 +87,8 @@ docker cp ai-memory:/data/backups/ai-memory-backup-okf-v0.2-<date>.tar.gz .````AI_MEMORY_BACKUP_DIR` still wins when set (point it at another-mounted volume if you prefer). Deleting the archive — from inside or-outside the container — clears the homepage notice, same as on a+mounted volume if you prefer). Deleting the archive, from inside or+outside the container, clears the homepage notice, the same as on aworkstation.## After the migration@@ -112,8 +112,8 @@ grep -L "^type:" <data_dir>/wiki/*/*/*/*.md # no output = all pages typed## Restoring the backup-Blunt and complete — returns the entire data directory to its exact-pre-migration state (the archive is taken before both the DB schema and+This is the blunt, complete option. It returns the entire data directory+to its exact pre-migration state (the archive is taken before both the DB schema andthe wiki are migrated, #633), so you can start the old 1.x binary again:```bash@@ -138,7 +138,7 @@ migrates it (as above). An **older 2.0+** binary opening a **newer**wiki refuses to start with `NewerWikiFormat` instead of silently mixingformats. (1.x binaries predate the guard: they can open a migrateddirectory and will tolerate the extra frontmatter, but new writes from-1.x will not carry the OKF keys — avoid mixing. To stay on 1.x cleanly,+1.x will not carry the OKF keys, so avoid mixing. To stay on 1.x cleanly,restore the pre-migration archive, which is captured before the DBmigration and so reopens under 1.x.)diff --git a/docs/ROADMAP-2.0.md b/docs/ROADMAP-2.0.mdindex cfd648b8..17e3409b 100644--- a/docs/ROADMAP-2.0.md+++ b/docs/ROADMAP-2.0.md@@ -36,14 +36,14 @@audits published numbers (mempalace). We publish none until this exists.- In-repo harness, on-demand like `writer_throughput` (`#[ignore]`d or a- `cargo run -p ai-memory-eval` target - the `evals/` crate already+ `cargo run -p ai-memory-eval` target; the `evals/` crate alreadyexists as a home). Fetches/loads the LongMemEval-V2 dataset, ingeststhrough the *real* store (hooks-shaped ingestion, not direct SQL),queries through the real retrieval stack, reports R@k / P@k per taskcategory, zero-LLM and LLM-assisted modes separately.- Deterministic where possible; provider-dependent parts clearly marked.- **Dataset decision (verified 2026-09-01):** V2 is Apache-2.0 on- HuggingFace (`xiaowu0162/longmemeval-v2`) with an official harness -+ HuggingFace (`xiaowu0162/longmemeval-v2`) with an official harness,but its trajectories are WebArena/ServiceNow-style *web-agent*histories, not coding sessions. The numbers competitors publish(agentmemory 0.967 R@5, mcp-memory-service 0.804/0.860) are against@@ -51,8 +51,8 @@ audits published numbers (mempalace). We publish none until this exists.cross-project comparability**, and adopt **V2's five-ability taxonomy**(static state recall, dynamic state tracking, workflow knowledge,environment gotchas, premise awareness) as the rubric for a- coding-agent-native companion eval built from replayed real sessions -- the agentmemory "coding-agent-life" precedent, with our own corpus.+ coding-agent-native companion eval built from replayed real sessions+ (the agentmemory "coding-agent-life" precedent, with our own corpus).- Deliverables: harness, baseline numbers committed to`docs/benchmarks/` with date + commit + hardware, docs on how to run.- Migration: none.@@ -65,9 +65,9 @@ knowledge portable to any OKF-aware consumer.- **Design doc first** (`docs/okf.md`): field-by-field mapping of ourfrontmatter to OKF (`type` required; our `tier`, `kind`, `tags`,- `entities`, TTL fields as extensions - OKF explicitly allows unknown- fields). Decide native conformance vs export-only. Bias: native -- wiki pages *are* OKF files - because "export" forks the truth.+ `entities`, TTL fields as extensions; OKF explicitly allows unknown+ fields). Decide native conformance vs export-only. Bias: native (wiki+ pages *are* OKF files), because "export" forks the truth.- **The migration is the hard part, and it must not churn versions.**Renaming/adding frontmatter across every page via normal writes wouldsupersede every page in every store (version explosion, embedding@@ -78,7 +78,7 @@ knowledge portable to any OKF-aware consumer.user's home (e.g. `~/ai-memory-backup-pre-2.0-<date>.tar.gz`),verifies the archive is readable (entry listing + size sanity)before proceeding, and **aborts the migration if the backup cannot- be written or verified** - no backup, no migration. The archive+ be written or verified**: no backup, no migration. The archivepath is recorded in the wiki meta manifest.- **the HTML wiki homepage surfaces the backup**: after migration,`serve`'s homepage shows a notice with the archive's path, size,@@ -96,8 +96,8 @@ knowledge portable to any OKF-aware consumer.- idempotent: re-running migrates zero pages.- Round-trip tests: our page → OKF file → parsed back identical; foreignOKF bundle imports into a project; migration control test proves the- no-churn property (same ids before/after); backup control test - break- the archive step and the migration must refuse to run; homepage notice+ no-churn property (same ids before/after); backup control test (break+ the archive step and the migration must refuse to run); homepage noticerenders the recorded archive path and clears when the file is gone.- `ai-memory export --okf <dir>` / `import --okf` for the non-nativedirection regardless, for interop with bundles outside the store.@@ -107,39 +107,38 @@ knowledge portable to any OKF-aware consumer.*Why:* `causes` / `fixes` / `contradicts` on the existing `links` model;`contradicts` feeds the lint pass that already exists.-- Schema: `links.relation` (nullable TEXT, default NULL = plain link) -- additive migration, zero rewrite of existing rows.+- Schema: `links.relation` (nullable TEXT, default NULL = plain link),+ an additive migration with zero rewrite of existing rows.- Producers: wikilink syntax extension (`[[page|fixes]]` or frontmatter`relations:`) decided in a short design note; consolidation promptgains the vocabulary (JSON-schema constrained, per invariant 7).- Consumers: lint (contradiction findings from `contradicts` edges),retrieval graph stream (relation-aware weighting only if item 1 shows- it helps - otherwise store, don't weight).+ it helps; otherwise store, don't weight).- Migration: none needed (additive). Docs: usage + graph docs.## Item 4 - Temporal validity on entity links (bi-temporal-lite)-*Why:* "what was true in June" - the one mainstream graph-camp mechanism+*Why:* "what was true in June", the one mainstream graph-camp mechanismworth having. Builds on item 3's schema work.- **Design doc before schema.** Reference: Zep/Graphiti paper. Scopedeliberately small: `valid_from` / `superseded_at` on`entity_page_links` (and possibly typed edges), populated by- supersession events we already emit - when a page version supersedes,+ supersession events we already emit: when a page version supersedes,its entity links inherit the timeline. No world-time vs- ingestion-time split in v1 of this; ingestion-time only, documented as- such honestly.+ ingestion-time split in v1 of this; ingestion-time only, documented as such.- Retrieval: `as_of` parameter on entity queries (additive, defaultnow).- Migration: additive columns; backfill `valid_from` from the page- version's `created_at` - a one-shot data migration inside refinery.+ version's `created_at` as a one-shot data migration inside refinery.## Item 5 - Local embeddings (all-MiniLM class; shipped via candle, not ONNX)*Why:* zero-config hybrid retrieval with no provider; `models/` has beenreserved for this since M9.5. Competitors ship it by default.-- `ort` crate; model NOT bundled in the binary (size) - fetched on+- `ort` crate; model NOT bundled in the binary (size); it is fetched on`ai-memory embed --provider local` first use into `models/`, withchecksum pinning and an offline path (drop the file in manually).- Coexistence is already designed: `(provider, model, dim)` is@@ -151,26 +150,24 @@ reserved for this since M9.5. Competitors ship it by default.configured provider either way.- Watch: `ort`/onnxruntime licensing + build weight on all releasetargets (incl. Windows); a `local-embeddings` cargo feature if the- dependency is heavy. **As built: this watch item decided the- implementation — candle (pure Rust) instead of ort, no native+ dependency is heavy. **As built: this watch item decided the implementation: candle (pure Rust) instead of ort, no nativeruntime, feature `local-embeddings` (default on). Same model, sameuse case; see `docs/local-embeddings.md`.**## Item 6 - Cross-session abstraction ("Experience" stage)*Why:* the frontier the survey names; the narrative layer TriMem argues-for. Most speculative, therefore last - and shaped by whatever items+for. Most speculative, therefore last, and shaped by whatever items1-5 taught us.- A periodic pass (auto-improve is the host; scheduled like existingmaintenance) that reads the last N sessions per project and stages- rewrites of pattern/preference/architecture pages - cross-trajectory,- not per-session. Staged through `pending-writes` exactly like other+ rewrites of pattern/preference/architecture pages, cross-trajectory rather than per-session. Staged through `pending-writes` exactly like otherauto-improve output: reviewable, never silent.- Zero-LLM default preserved: pass is opt-in like consolidation.- Success metric from item 1 plus a curated before/after page-qualityreview; if it cannot demonstrate value, it ships disabled-by-default- with the honest note, or not at all.+ with a note saying so, or not at all.## Item 7 - `status` truthfulness audit (pre-cut, low priority)@@ -180,8 +177,7 @@ from reality. Scheduled deliberately **after** items 1-6 so it auditsthe final surface, not a moving one.- Assessment first, fixes second: for every line `status` prints, trace- it to the source of truth and answer "has this been true so far?" -- counts vs actual rows, FTS coverage vs actual index, embedding+ it to the source of truth and answer "has this been true so far?": counts vs actual rows, FTS coverage vs actual index, embeddingbacklog vs reality, spool depth, server/bind/data-dir provenance.- Then the inverse: what health signal exists that `status` *doesn't*show? 2.0 candidates from items 1-6: `wiki_format` generation and@@ -199,12 +195,12 @@ the final surface, not a moving one.*Why:* feature docs written alongside code default to "what it does";readers deciding whether to ADOPT a feature need "why it exists","when to reach for it" (and when not to), and a real-world example-showing the possibility — the way `docs/local-embeddings.md` leads+showing the possibility, the way `docs/local-embeddings.md` leadswith the egress/paraphrase-recall story before the mechanics.- Sweep every user-facing doc (README sections, docs/*.md, theconfig template comments) and grade each feature's coverage: what /- why / when / example. Fix the gaps — a short scenario ("two+ why / when / example. Fix the gaps: a short scenario ("twoteammates on one server", "resuming on the laptop what the desktopleft off", "asking what we knew about X before the rewrite") beats aflag list.@@ -223,13 +219,12 @@ with the egress/paraphrase-recall story before the mechanics.```Each lands on main individually gated (fmt, clippy -D warnings, full-tests, changelog guards, harness numbers where retrieval is touched) —+tests, changelog guards, harness numbers where retrieval is touched), with**fast Linux CI only per item**; the slow macOS/Windows matrix runsonce, mandatorily, on the release-candidate SHA before the cut (seeAGENTS.md "CI pacing"). 2.0 is cut when:-- all six items (or an explicitly-decided subset - item 6 may justifiably- drop) are merged with docs;+- all six items (or an explicitly-decided subset; item 6 may justifiably drop) are merged with docs;- `docs/MIGRATION-2.0.md` reads as a complete upgrade guide and has beenexercised against a copy of a real 1.x data dir, **including a fullrestore drill from the pre-migration backup archive**;@@ -238,12 +233,11 @@ AGENTS.md "CI pacing"). 2.0 is cut when:- a **pr-post-audit over the whole 2.0 range** (v1.39.0 → therelease candidate) has run clean: every item PR re-verified againstthe final combined tree, cross-PR interactions swept, documentation- ledger checked — findings fixed and re-audited before anything else+ ledger checked, with findings fixed and re-audited before anything elseproceeds;- the full macOS/Windows CI matrix is green on the release-candidateSHA (dispatched, not assumed), and **the user has reviewed the summary- of everything done and explicitly approved the release** — 2.0 is- never cut automatically.+ of everything done and explicitly approved the release**. 2.0 is never cut automatically.Deploy/live-test follows the same v1.39 pipeline: exact-main gates,hosted CI, `compose pull` (never `bin/deploy`), health + status + adiff --git a/docs/admission-webhooks.md b/docs/admission-webhooks.mdindex 3535e687..9940ee44 100644--- a/docs/admission-webhooks.md+++ b/docs/admission-webhooks.md@@ -7,15 +7,15 @@> (return a new frontmatter / body); delete/purge/move hooks are notifications> that can observe, mirror, or reject. Sourced from> `crates/ai-memory-wiki/src/admission.rs` and the wiring in-> `crates/ai-memory-cli/src/commands/serve.rs` — keep both as the-> canonical reference if anything here drifts.+> `crates/ai-memory-cli/src/commands/serve.rs`. If anything here drifts,+> those two files are the canonical reference.## 1. What this is (and isn't)| | What you can do | What you can't do ||---|---|---|-| Chain | Add canonical frontmatter fields (e.g. `contributors`); mirror the write into an external system (git, search index, audit log); reject writes that fail policy (e.g. `validate-no-secrets`). | Talk back to the engine's writer or store directly — the chain only sees one page at a time and mutates it in place. |-| Engine | Stays closed for modification: every new behaviour ships as an independent HTTP service in any language. | The engine doesn't discover or auto-register webhooks — operators name them in config. |+| Chain | Add canonical frontmatter fields (e.g. `contributors`); mirror the write into an external system (git, search index, audit log); reject writes that fail policy (e.g. `validate-no-secrets`). | Talk back to the engine's writer or store directly. The chain only sees one page at a time and mutates it in place. |+| Engine | Stays closed for modification: every new behaviour ships as an independent HTTP service in any language. | The engine doesn't discover or auto-register webhooks; operators name them in config. |If your idea doesn't fit "mutate the page or observe the write", it'sprobably a different extension point (`/hook` ingress, `/admin/*` admin@@ -32,81 +32,81 @@ in a single atomic step (seeinvariants).Webhooks run **sequentially**, in the order declared in config. Each one-sees the (possibly mutated) page from the previous webhook — so a+sees the (possibly mutated) page from the previous webhook, so a`contributors` hook that adds frontmatter is followed by a `git-mirror`hook that mirrors the enriched page.Webhooks fire on these `op` values today (extensible enum):-- `write_page` — direct writes via MCP `memory_write_page`, the CLI+- `write_page`: direct writes via MCP `memory_write_page`, the CLI`write-page`, `/admin/write-page`, the lint rewriter, hook synthesis.-- `consolidate` — LLM consolidation writes from the consolidator+- `consolidate`: LLM consolidation writes from the consolidator(SessionEnd opt-in + PreCompact + manual `memory_consolidate`) and therule-based PreCompact/PostCompaction fallback after a provider failure.**Fires up to twice per consolidation**: once as an admission *preflight*- before the LLM call — with an **empty body** and the target page path (for- multi-page runs, the canonical `sessions/<id>.md` anchor path) — and again+ before the LLM call, with an **empty body** and the target page path (for+ multi-page runs, the canonical `sessions/<id>.md` anchor path), and againas the normal write-time check with the real content. Treat blocking callsas **decisions, not delivery events**: gate on `op` / `actor` / `workspace`/ `project` / path, don't reject solely because the body is empty, anddon't count blocking calls as one-write-happened side effects (use anon-blocking observer webhook for that). Any mutation returned during thepreflight is discarded.-- `delete` — a single page is removed (`Wiki::delete_page`, triggered by the+- `delete`: a single page is removed (`Wiki::delete_page`, triggered by the`memory_delete_page` MCP tool). Carries the page path, no body; fired**before** the file is removed so a mirror can `git rm` the same path. TheSQLite index is deleted directly by the writer actor; the watcher does notreconcile delete events.-- `purge_project` — a whole project is purged (`Wiki::purge_project` →+- `purge_project`: a whole project is purged (`Wiki::purge_project` →`remove_dir_all`, routed from `/admin/purge-project`). Carries theproject in `ctx`, **no** page path; fired before the directory isremoved so a mirror can drop the project.-- `purge_session` — one session is purged (routed from+- `purge_session`: one session is purged (routed from`/admin/purge-session`). Carries the workspace/project in `ctx`, **no** page- path — the operation is driven by session id rather than by path. Fired+ path, because the operation is driven by session id rather than by path. Firedbefore any row is deleted, so a `reject`-policy webhook can refuse the purgewhile the session's data is still intact. Non-blocking observers aredispatched again after the SQL purge and page-file cleanup are durable.-- `purge_workspace` — a whole workspace is purged (routed from+- `purge_workspace`: a whole workspace is purged (routed from`/admin/delete-workspace`). Carries the workspace in `ctx.workspace`, leaves`ctx.project` empty, and has **no** page path; fired before SQL/filedestruction for reject-policy admission and dispatched again to non-blockingobservers after durable work.-- `move_project` — a whole project is moved between workspaces without+- `move_project`: a whole project is moved between workspaces withoutchanging `project_id` (fresh-destination true move). Carries the sourceproject in `ctx.workspace` / `ctx.project`, destination names in`ctx.destination_workspace` / `ctx.destination_project`, and no page path;fired before the directory rename + DB re-stamp so a mirror can rename orreject the project move.-- `move_session` — one session (its rows and its `sessions/<id>.md` page)+- `move_session`: one session (its rows and its `sessions/<id>.md` page)is moved to another project (`/admin/move-session`). Carries the sourceproject in `ctx.workspace` / `ctx.project`, destination names in`ctx.destination_workspace` / `ctx.destination_project`, and no page path;fired before the page file moves and the DB re-stamps so a mirror can moveor reject it.-- `handoff_begin` / `handoff_accept` / `handoff_cancel` — a handoff is created,+- `handoff_begin` / `handoff_accept` / `handoff_cancel`: a handoff is created,consumed, or discarded. Carries the workspace / project and the actingoperator, no page path (handoffs live in their own table, not the wiki tree).Fired by the MCP tools **and** by the automatic hook paths: the SessionEndbaton (`handoff_begin`) and the session-start claim (`handoff_accept`).The three handoff lifecycle ops are dispatched in one fixed order, the same-from every path that raises them: the webhooks that can refuse — `blocking`-with `failure_policy = "reject"` — are awaited **before** the operation, the+from every path that raises them. The webhooks that can refuse (`blocking`+with `failure_policy = "reject"`) are awaited **before** the operation, theoperation then runs, and every other subscriber (observers, blocking or not) isdispatched fire-and-forget **after** it, only if it happened. So no observer istold about an `accept` that found no pending handoff or a `cancel` another-operator's ownership refused — an `accept` with nothing pending is not+operator's ownership refused. An `accept` with nothing pending is notannounced to a decider either, since the engine knows there is nothing to-accept before it asks — and an observer subscribed to one of these ops sees the+accept before it asks. An observer subscribed to one of these ops sees thesame event whether it came from an MCP tool or the hook ingress. (`write_page`and the notification ops below are unchanged: there, a `blocking` webhook is-awaited up front whatever its `failure_policy` — on `write_page` because it can-still mutate the page.)+awaited up front whatever its `failure_policy`; on `write_page` that is because+it can still mutate the page.)What a `reject` costs the caller depends on **which path** raised the op, and-the difference is deliberate. On the MCP tools — `memory_handoff_begin`,-`memory_handoff_accept`, `memory_handoff_cancel` — a refusal aborts the tool+the difference is deliberate. On the MCP tools (`memory_handoff_begin`,+`memory_handoff_accept`, `memory_handoff_cancel`), a refusal aborts the toolcall and is returned to the caller as a JSON-RPC error, exactly like`write_page`: there is a caller who asked for the operation, so it is told theoperation did not happen. On the automatic paths there is no such caller, so a@@ -125,7 +125,7 @@ refusal degrades the lifecycle event instead of failing it:Budgeting the session-start claim: the deciding webhooks are awaited**sequentially**, and the chain stops at the first refusal, so what the operatorwaits for in the worst case is the **sum** of the `timeout_ms` of every-`reject`-policy webhook subscribed to `handoff_accept` — not the largest of them.+`reject`-policy webhook subscribed to `handoff_accept`, not the largest of them.That sum is then capped by the server's 750 ms automatic-claim deadline.`timeout_ms` still defaults to 2000 ms per webhook for ordinary MCP and writepaths; on automatic session-start acceptance, a chain that cannot approve@@ -133,7 +133,7 @@ within 750 ms is treated as a refusal and the baton remains open. Configuresmaller per-webhook values when you need logs to identify which decider timedout rather than the aggregate deadline firing first.-`delete` / `purge_project` / `purge_workspace` / `move_project` / `move_session` are notifications — there is no+`delete` / `purge_project` / `purge_workspace` / `move_project` / `move_session` are notifications with nobody to mutate; a `Reject`-policy webhook still aborts the operation(admission fires BEFORE the SQL destruction in both the `/admin/purge-project`and `/admin/delete-workspace` paths, and before source teardown in@@ -171,28 +171,28 @@ terminal `purge_project` notification is unchanged.### What does NOT fire the chain (by design)-- **`log.md` / `log-YYYY-MM.md` appends** — written on every hook event+- **`log.md` / `log-YYYY-MM.md` appends**: written on every hook event(per prompt/tool-call). Routing each through the chain would mean anHTTP POST per observation, violating the fire-and-forget hook budget. Theper-event log is a local audit artifact; back it up out-of-band (batchedrsync), not per-line.-- **The page bodies behind a handoff** — the `handoff_*` ops above carry only+- **The page bodies behind a handoff**: the `handoff_*` ops above carry onlythe scope and the acting operator. A handoff is SQLite rows, so a file mirrorhas no file change to reconcile from one; what it gets is the lifecycleevent, not a page.-- **Aged decay-history cleanup** — only the old SQLite version chain changes;+- **Aged decay-history cleanup**: only the old SQLite version chain changes;any Markdown file at the path remains authoritative and is reindexed firstwhen necessary. Initial decay eviction and frontmatter TTL expiry use theconditional `delete` admission path.-- **`rename-project`** — a `projects.name` column update; the on-disk path+- **`rename-project`**: a `projects.name` column update; the on-disk pathis the stable UUID, so no file moves and nothing to propagate.-- **`rename-workspace`** — a `workspaces.name` column update plus refreshed+- **`rename-workspace`**: a `workspaces.name` column update plus refreshed`_meta.md` manifests; workspace paths are stable UUIDs, so no file movenotification is needed.-- **`repair-backfill-timestamps`** (`/admin/repair-session-times`) — a+- **`repair-backfill-timestamps`** (`/admin/repair-session-times`): a`sessions.started_at`/`ended_at` column update only; no wiki page or fileis touched, so there is nothing for a mirror to reconcile.-- **External / manual edits on disk** — reconciled by the watcher, not the+- **External / manual edits on disk**: reconciled by the watcher, not theadmission chain (the chain is for the engine's own write path).## 3. Wire contract@@ -248,12 +248,12 @@ serialisation source.| Status | Body | Behaviour ||---|---|---|-| `200 OK` | `{ "page": { "frontmatter": ..., "body": ... } }` — both inner fields optional. Anything missing means "leave that field unchanged". | The engine swaps in the returned values before the next webhook (or the final atomic write). |-| `204 No Content` | (empty) | The engine treats the webhook as a pure observer / side-effect — no mutation, no parse. |+| `200 OK` | `{ "page": { "frontmatter": ..., "body": ... } }`; both inner fields optional. Anything missing means "leave that field unchanged". | The engine swaps in the returned values before the next webhook (or the final atomic write). |+| `204 No Content` | (empty) | The engine treats the webhook as a pure observer / side-effect: no mutation, no parse. || `4xx` / `5xx` | (optional textual body, logged) | See **§4 Failure policy**. |The engine bounds the response read at `MAX_RESPONSE_BYTES` (1 MiB).-Anything beyond that is treated as a no-op with a `warn` log — webhooks+Anything beyond that is treated as a no-op with a `warn` log, since webhookshave no legitimate reason to return more than the page envelope.## 4. Failure policy@@ -261,16 +261,16 @@ have no legitimate reason to return more than the page envelope.Each webhook picks one when the engine can't reach it or it returnsnon-2xx:-- **`ignore` (default, recommended)** — Engine logs a `warn` and+- **`ignore` (default, recommended)**: the engine logs a `warn` andcontinues with the unmutated page. The page write still succeeds.This is the right choice for everything except safety-criticalenforcers.-- **`reject`** — Engine aborts the write, propagating the error up to+- **`reject`**: the engine aborts the write, propagating the error up tothe caller. Use this **only** when the webhook is a hard preconditionfor persistence (e.g. a future `validate-no-secrets` enforcer).A webhook that subscribes to multiple ops uses the same policy across-all of them — including the handoff lifecycle ops above, where "abort" means+all of them, including the handoff lifecycle ops above, where "abort" means"decline this handoff", not "fail the event".## 5. Workspace / project names@@ -284,8 +284,8 @@ embedders, tests that wire a chain without a reader).External webhooks should treat the names as opaque strings (workspace /project values use the same validation as `--workspace` / `--project`-CLI flags). They are stable for the lifetime of the workspace / project-— the engine doesn't rename them silently. `rename-project` is a manual+CLI flags). They are stable for the lifetime of the workspace / project;+the engine doesn't rename them silently. `rename-project` is a manualop that an operator runs and that will eventually trigger a freshwebhook fan-out if you wire one.@@ -313,7 +313,7 @@ Constants are exported from the `ai-memory-wiki` crate root:| Constant | Value | What it caps ||---|---|---|-| `MAX_ADMISSION_WEBHOOKS` | `16` | Chain length. `AdmissionChain::new` errors out beyond this — a misconfigured template (helm loop, duplicated block) can't push N hooks into the write-path. |+| `MAX_ADMISSION_WEBHOOKS` | `16` | Chain length. `AdmissionChain::new` errors out beyond this, so a misconfigured template (helm loop, duplicated block) can't push N hooks into the write-path. || `MAX_RESPONSE_BYTES` | `1 MiB` | Webhook response body. Beyond this the response is dropped (treated as no-op + `warn`). || Per-webhook `timeout_ms` | operator-set (default `2000`) | Single request. The chain is sequential, so total worst case ≈ `Σ timeout_ms`; automatic session-start handoff acceptance additionally caps the whole deciding chain at 750 ms. |@@ -343,17 +343,17 @@ blocking = false # fire-and-forget afterA webhook is either **blocking** or **non-blocking**:-- **`blocking = true`** (default) — runs *synchronously* inside the write path.+- **`blocking = true`** (default): runs *synchronously* inside the write path.It can mutate the page (`write_page`/`consolidate`), and a `reject` failureaborts the write. The write waits for it (up to `timeout_ms`). Use forenrichers/validators (e.g. `contributors`, `validate-no-secrets`).-- **`blocking = false`** — dispatched *fire-and-forget* **after** the durable+- **`blocking = false`**: dispatched *fire-and-forget* **after** the durableoperation has completed. For writes that means the final page is on disk andindexed in SQLite; for deletes that means the file and index row are gone;for project purges that means the DB purge has completed and filesystemremoval has been attempted; for project moves it means the directory and DBrows now point at the destination workspace. The engine does not wait for it- and ignores its response, so it **cannot mutate or reject** — it only+ and ignores its response, so it **cannot mutate or reject**; it onlyobserves/mirrors the final state. Use for pure backups/mirrors (e.g.`git-mirror`) so a slow or down sink never adds latency to writes. Stillhonours `events` and the skip list.@@ -364,13 +364,13 @@ Since the blocking chain is sequential, total worst-case write latency isFire-and-forget dispatch is bounded: **256** such requests may be in flight perprocess, and beyond that the request is dropped and logged rather than queued(the durable operation has already completed, so the caller is never stalled).-On the handoff lifecycle ops — `handoff_begin`, `handoff_accept`,-`handoff_cancel` — only a `reject`-policy webhook is awaited, so a+On the handoff lifecycle ops (`handoff_begin`, `handoff_accept`,+`handoff_cancel`), only a `reject`-policy webhook is awaited, so a`blocking = true` hook with `failure_policy = "ignore"` is dispatchedfire-and-forget there and shares that budget: under sustained load it too can bedropped. Such a drop is logged at ERROR (a non-blocking one at WARN). A hook thatmust not be dropped on those ops needs `failure_policy = "reject"`, which makes-it a decider — awaited before the operation, and able to refuse it.+it a decider: awaited before the operation, and able to refuse it.Env override:@@ -422,7 +422,7 @@ persisting. `body` is left untouched (not in the response).The webhook materialises the page into a local clone of an externalrepo, batches commits, and pushes asynchronously. The engine doesn't-wait for the push — only the local enqueue runs inside the write path+wait for the push; only the local enqueue runs inside the write pathunder the webhook's `timeout_ms`.## 10. Tests@@ -460,13 +460,13 @@ covers the integrated path (`Wiki::write_page` → store reader resolution## 12. Non-goals (planned iterations, not blockers)-- **Parallel fan-out.** The chain is sequential by design today —+- **Parallel fan-out.** The chain is sequential by design today, becausemutation composition is well-defined that way. A future`parallel = true` for side-effect-only webhooks (no body mutationexpected) is possible but not in scope.- **Webhook discovery / dynamic registration.** Hooks are operator-namedin config. A future `/admin/admission-webhooks` POST surface is- conceivable but explicitly out of scope here — single-tenant config+ conceivable but explicitly out of scope here. Single-tenant configis simpler and matches how the engine treats every other extensionpoint (`[[etl_sources]]`, etc.).- **Per-webhook metrics surface.** The chain logs via `tracing` today.diff --git a/docs/agent-messaging.md b/docs/agent-messaging.mdindex 425700cb..110efde3 100644--- a/docs/agent-messaging.md+++ b/docs/agent-messaging.md@@ -18,7 +18,7 @@ ever sees mail addressed **to** it (its inbox) or sent **from** it (its outbox).- A message is addressed to a **project**, not a person. Any session working inthe recipient project can pop it. (Knowledge is shared; the pop is the- claim-once baton — the same rule handoffs follow.)+ claim-once baton, the same rule handoffs follow.)- **Claim-once queue.** A message is `pending` until a session in the recipientproject pops it (→ `claimed`, exactly once) or the sender cancels it(→ `cancelled`). A second pop of the same message returns nothing.@@ -47,7 +47,7 @@ Four MCP tools (documented in the installed `ai-memory-messaging` skill):Kimi calls `memory_message_send` with `to_workspace: "default"`,`to_project: "project-b"`, and a self-contained `body`. Compose the body as a-complete prompt — the recipient cannot see project A.+complete prompt, because the recipient cannot see project A.**In Claude (project B), receiving:**@@ -157,8 +157,8 @@ each message records who sent it for audit.ai-memory already gives a resuming agent a hot start: every agent's SessionStarthook (or, for clients that discard SessionStart output like Kimi, its firstuser-prompt hook) fetches `GET /handoff`, which returns any pending single-use-**handoff** plus — when the project's `.ai-memory.toml` opts in with-`[briefing] inject_on_session_start = true` — a compiled **project brief** of+**handoff** plus, when the project's `.ai-memory.toml` opts in with+`[briefing] inject_on_session_start = true`, a compiled **project brief** ofpinned / `_rules/` / `_slots/` pages and recent-page pointers. That block isprepended to the new session's context automatically.@@ -173,7 +173,7 @@ weigh, not instructions to obey.```The notice carries only a count and the inbox's own server-side workspace and-project names — never any message text — so it cannot be used to inject content+project names, never any message text, so it cannot be used to inject contentinto a resuming agent. The names are there so a static client can pass them tothe pop; if they cannot be looked up, the notice falls back to "this project'sinbox". The count is also available on demand via `memory_briefing`diff --git a/docs/airgapped-install.md b/docs/airgapped-install.mdindex 33e60026..31db7d05 100644--- a/docs/airgapped-install.md+++ b/docs/airgapped-install.md@@ -2,9 +2,9 @@Corporate IT-security review commonly asks for a documented offlineinstallation path before approving a dev tool. ai-memory's build and-runtime are already close to air-gap-friendly by design; this page collects-what already exists elsewhere in the docs into one answer, rather than-introducing a new mode.+runtime are already close to air-gap-friendly by design. This page collects+what the docs already say elsewhere into one answer; it does not add a new+mode.## Build: no network required@@ -19,7 +19,7 @@ If you'd rather not build at all, tagged GitHub Releases publish prebuiltbinaries for Linux (`linux/amd64`, `linux/arm64`), macOS(`ai-memory-macos-aarch64.tar.gz`, `ai-memory-macos-x86_64.tar.gz`), andWindows (`ai-memory-windows-x86_64.zip`), each with a SHA-256 checksum-(`SECURITY.md`, "Published executable integrity") — download once on a+(`SECURITY.md`, "Published executable integrity"). Download once on anetwork-connected machine, verify the checksum, and transfer the artifactinto the air-gapped environment.@@ -35,7 +35,7 @@ explicitly configure:search, or provider-based embeddings. Skip this and use the `local`embedding provider (below) to stay fully offline.- **`capture_assistant`** and **`AI_MEMORY_RERANKER=llm`**, both off by- default — see `DATA_HANDLING.md`.+ default; see `DATA_HANDLING.md`.## Local embeddings without a network dependency@@ -44,7 +44,8 @@ server, set the embedding provider to `local`([`docs/local-embeddings.md`](local-embeddings.md)). On first use it fetchesthree small model files (~87 MB total, Apache-2.0 licensed) into`<data_dir>/models/all-MiniLM-L6-v2/`, each checked against a sha256 pinned-in source so a tampered or drifted file fails loudly rather than silently.+in source so a tampered or drifted file fails with an error instead of+loading.For a fully offline install, download those three files(`model.safetensors`, `tokenizer.json`, `config.json`) from@@ -52,13 +53,13 @@ For a fully offline install, download those three filesnetwork-connected machine and place them in that directory before firststart; the loader verifies the same checksums and never touches the network(`docs/local-embeddings.md`, "Offline installs"). After that, embeddings run-entirely on-host via the bundled `candle` (pure Rust) runtime — no ONNX+entirely on-host via the bundled `candle` (pure Rust) runtime, with no ONNXruntime or other native library to source separately.## What still needs a decision from you- **git remote sync**, if you use it to push the wiki repository somewhere,- is your own channel to secure (`SECURITY.md`, "Remote sync security" —+ is your own channel to secure (`SECURITY.md`, "Remote sync security";out of scope for ai-memory itself). [`docs/backup.md`](backup.md) has aworked example of the rsync + `git push` pattern with the appropriatesecret and derived-state exclusions.@@ -68,8 +69,8 @@ runtime or other native library to source separately.## Related documents-- [`DATA_HANDLING.md`](../DATA_HANDLING.md) — what leaves the host and when.-- [`docs/local-embeddings.md`](local-embeddings.md) — embedding provider+- [`DATA_HANDLING.md`](../DATA_HANDLING.md): what leaves the host and when.+- [`docs/local-embeddings.md`](local-embeddings.md): embedding providerchoices, including the offline path in detail.-- [`docs/deploy.md`](deploy.md) — Docker/homelab deployment pattern.-- [`SECURITY.md`](../SECURITY.md) — release integrity and threat model.+- [`docs/deploy.md`](deploy.md): Docker/homelab deployment pattern.+- [`SECURITY.md`](../SECURITY.md): release integrity and threat model.diff --git a/docs/auto-improve-eval-gates.md b/docs/auto-improve-eval-gates.mdindex 84847be9..cf73c612 100644--- a/docs/auto-improve-eval-gates.md+++ b/docs/auto-improve-eval-gates.md@@ -108,10 +108,10 @@ to pending evidence; reading a report cannot restore independent observations.This repository includes two dependency-free templates:-- [`docs/examples/auto-improve-eval/score_proposal.py`](examples/auto-improve-eval/score_proposal.py)- — Python scorer that checks basic structure and placeholders.-- [`docs/examples/auto-improve-eval/score_proposal.sh`](examples/auto-improve-eval/score_proposal.sh)- — POSIX shell wrapper around an embedded Python scorer for hosts that prefer a+- [`docs/examples/auto-improve-eval/score_proposal.py`](examples/auto-improve-eval/score_proposal.py):+ Python scorer that checks basic structure and placeholders.+- [`docs/examples/auto-improve-eval/score_proposal.sh`](examples/auto-improve-eval/score_proposal.sh):+ POSIX shell wrapper around an embedded Python scorer for hosts that prefer ascript entrypoint.Try them with the sample payload:diff --git a/docs/auto-improvement-loop.md b/docs/auto-improvement-loop.mdindex 80874383..b655c100 100644--- a/docs/auto-improvement-loop.md+++ b/docs/auto-improvement-loop.md@@ -3,8 +3,8 @@## The 60-second version (read this first)When an LLM provider is configured, the server periodically reviews-newly completed sessions and proposes small wiki edits — a new gotcha,-a rule promotion, a patch to a stale concept page. Every proposal is+newly completed sessions and proposes small wiki edits, such as+a new gotcha, a rule promotion, or a patch to a stale concept page. Every proposal isvalidated (schema, confidence floor, size caps, eval gate) and stagedinto `_pending/auto-improve/` with a human-readable sidecar, then**auto-approved by default** through the normal wiki write path.@@ -12,17 +12,17 @@ into `_pending/auto-improve/` with a human-readable sidecar, thenWhat that means for you:- **Solo, zero-LLM install**: this never runs. Nothing to decide.-- **Solo with an LLM**: the default is fine — proposals are small,+- **Solo with an LLM**: the default is fine. Proposals are small,bounded, audited (every one lands in the pending-writes trail withevidence quotes and a confidence score), and reversible via wikihistory. Run `ai-memory pending-writes list` for a week if you want to- build trust — that (and SQLite) is the source of truth for a proposal's+ build trust; that list (and SQLite) is the source of truth for a proposal'sstatus. The `_pending/auto-improve/` sidecar files are a human-readablesnapshot frozen at staging time; they do not track a proposal toapproved/applied/rejected.- **Shared / team server**: set `[auto_improve] require_approval =true`. On a server several people trust, an LLM should not- auto-apply edits nobody reviewed — proposals then wait in+ auto-apply edits nobody reviewed. Proposals then wait in`_pending/` until a human approves each one.- **Cost**: one bounded LLM call per completed session that passes thepreflight filters (minimum observations/duration); prompt and output@@ -30,8 +30,8 @@ What that means for you:A typical staged proposal sidecar looks like: the target path, theoperation (create or patch), a confidence like `0.86`, the rationale,-bounded evidence quotes from the session, and the exact body or edits-— enough to approve or reject without opening anything else.+bounded evidence quotes from the session, and the exact body or edits.+That is enough to approve or reject without opening anything else.The rest of this page is the original design research plusimplementation notes, kept for depth.@@ -51,8 +51,7 @@ implementation notes, kept for depth.An ai-memory equivalent of Hermes Agent's self-improvement loop is worthshipping as a default-available, review-gated staging path. The current wikialready captures useful durable knowledge: decisions, gotchas, concepts, rules,-notes, and session summaries. The missing piece is not more capture. It is a-careful reviewer that can identify durable lessons and apply small wiki patches+notes, and session summaries. What is missing is a careful reviewer that can identify durable lessons and apply small wiki patchesthrough the existing review/audit path without mutating the active agent contextor silently promoting weak session residue into rules.@@ -121,7 +120,7 @@ The default is off, preserving existing behavior. When enabled:Validation runs before staging, so invalid writes are rejected immediatelyinstead of being queued for approval and failing later.-This maps strongly to ai-memory. Wiki edits are closer to Hermes skills than to+This maps closely to ai-memory. Wiki edits are closer to Hermes skills than tosmall memory entries: they can be large, durable, and project-shaping. Stagingshould be the default for autonomous ai-memory learning writes.@@ -381,12 +380,12 @@ min_session_age_secs = 600`patchable_page_prefixes` decides which folders' **page bodies** are sent to thereviewer. Everything else in the project reaches it through the recent-page list-as a single line — path, title, kind, updated_at — with no content.+as a single line (path, title, kind, updated_at) with no content.That matters because the reviewer cannot avoid duplicating what it cannot read.A project that keeps its invariants in `decisions/` or `gotchas/`, with no`_rules/` pages at all, sends **no page bodies**, and the model will keep-proposing rules that are already written down — often with high confidence,+proposing rules that are already written down, often with high confidence,because the claim really is well evidenced by the session.The default is the historical pair, so existing installations are unchanged. Add@@ -555,7 +554,7 @@ can notice already exists, and therefore what it may redundantly re-propose:recently updated ones. To keep those slots for durable knowledge, theauto-improve reviewer excludes `sessions/` pages from *its* recent-page context(session pages are never valid proposal targets and would otherwise dominate- the list). This exclusion is scoped to the reviewer only — the SessionStart+ the list). This exclusion is scoped to the reviewer only; the SessionStartbriefing and `memory_briefing` still include session pages, where they belong.The practical consequence: a durable page that lives outside `_rules/` /@@ -650,9 +649,9 @@ Tests:## Current Conclusion-Hermes validates the idea, but also shows why the boundaries matter. The useful-part is not that the agent can write memory by itself. The useful part is a-bounded, observable, reviewable loop that turns repeated work into durable+Hermes validates the idea and also shows why the boundaries matter. An agent+that can write memory by itself is not what makes it useful. The useful part is+a bounded, observable, reviewable loop that turns repeated work into durableknowledge while keeping active task execution isolated.For ai-memory, the current correct boundary is scheduled review plus pendingdiff --git a/docs/auto-scope.md b/docs/auto-scope.mdindex d2b29027..f0383610 100644--- a/docs/auto-scope.md+++ b/docs/auto-scope.md@@ -11,11 +11,11 @@ delayed post-tool, stop, or session-end tail from an older process must notredirect a newer session's unscoped reads.Since v1.39 that pointer is **keyed by the caller's own coordinate** by-default (`per_actor`), so two harnesses in one project — or two operators on-one server — cannot overwrite each other's notion of "current project".+default (`per_actor`), so two harnesses in one project, or two operators on+one server, cannot overwrite each other's notion of "current project".-Before v1.39 the default was a single process-wide slot (`single`). That is-right for exactly one harness at a time and collapses as soon as there are+Before v1.39 the default was a single process-wide slot (`single`). That+works for exactly one harness at a time and breaks as soon as there aretwo: a hook firing from `~/repo-A` overwrites the slot that a concurrent`memory_query` (with no explicit project) in `~/repo-B` was about to read.Because unscoped **writes** resolve through the same pointer, that could also@@ -134,12 +134,12 @@ valid remote uses its folder basename.Owner and agent are what identify a session; scope is not. The same operator'ssession legitimately produces events in another project when its cwd moves, so-a differing `(workspace, project)` is recorded rather than rejected — see+a differing `(workspace, project)` is recorded rather than rejected. See[`[routing] mid_session`](marker-file.md#mid-session-navigation-routing-mid_session)for how those events are attributed. The one exception is a terminal event: a`SessionEnd` naming a different scope than its session is not that session's-end, so it is dropped rather than ending someone else's session — unless it-comes from the session's own cwd. Then the scope drifted under the same+end, so it is dropped rather than ending someone else's session, unless it+comes from the session's own cwd. In that case the scope drifted under the samedirectory (a `.ai-memory.toml` appeared mid-session), and the end closes thesession in the scope it was recorded in.@@ -215,7 +215,7 @@ For built-in installs that use static MCP config, prefer:## Pairing with multi-user mode`per_actor` is most useful when the engine is in multi-user mode (see-[`docs/users.md`](users.md)) — each native API credential resolves through+[`docs/users.md`](users.md)): each native API credential resolves through`api_credentials` to its owning `users` row, so the auth middleware tagsevery request with the right `user`. With `[auto_scope] mode = "per_actor"`, twoauthenticated users running concurrent agent sessions through the same@@ -230,9 +230,9 @@ configs, use explicit `workspace` + `project` arguments for concurrent windows.## Surviving a restart-The pointer is process memory: restarting the daemon — which is exactly what-the packages tell you to do after an upgrade — empties it, including for-sessions that are still open. Until the next foreground hook event lands, every+The pointer is process memory. Restarting the daemon, which the packages tell+you to do after an upgrade, empties it, including for sessions that are still+open. Until the next foreground hook event lands, everykeyed read misses, and an unscoped read used to resolve through the bakeddefault scope and report an empty project through the success path. Nothing inthe answer or the log said "scope unresolved", so an agent asking "what do we@@ -240,12 +240,12 @@ have here?" was told "nothing" while thousands of observations sat in the DB.`serve` therefore seeds a **read-side fallback slot** at startup from the mostrecently active project already recorded in SQLite, so a keyed miss right after-a restart degrades to real data instead of an empty default. Four bounds keep-that narrow:+a restart degrades to real data instead of an empty default. Four bounds limit+it:- **Reads only.** The seed is a reconstruction, not an observed publish, so itlives in its own slot. An unscoped **write** still resolves as if nothing- were published — it fails closed on a genuine mismatch and otherwise uses the+ were published: it fails closed on a genuine mismatch and otherwise uses theconfigured default, exactly as before. Nothing in a restart should retargetwhere a page lands.- **Keyed entries are never reconstructed**, so a keyed hit still wins and@@ -282,16 +282,16 @@ observable changes:| your setup | before | after ||---|---|---|-| one harness, hooks installed | shared slot | keyed slot for that session — same project |-| static MCP client (bearer, no session id) | shared slot | that operator's identity-only slot — same project |+| one harness, hooks installed | shared slot | keyed slot for that session, same project |+| static MCP client (bearer, no session id) | shared slot | that operator's identity-only slot, same project || client that forwards no identity at all | shared slot | shared slot, unchanged |-| **MCP-only install, no lifecycle hooks** | shared slot | shared slot — nothing is ever keyed, so the fallback applies |+| **MCP-only install, no lifecycle hooks** | shared slot | shared slot; nothing is ever keyed, so the fallback applies || two harnesses / two operators | one slot, last write wins | one slot each |-The single behavioural change is deliberate: a client that forwards a session+The one behavioural change is deliberate: a client that forwards a sessionid which does **not** match any published hook activity no longer inherits the-shared slot. Answering it from there is what routed a request into whichever-project published last — on a shared server, potentially another operator's.+shared slot. Answering it from there routed a request into whichever+project published last, which on a shared server could be another operator's.Such a caller now resolves to the server's configured default instead.To restore the old behaviour exactly:diff --git a/docs/backup.md b/docs/backup.mdindex 3022c5ae..c98d207c 100644--- a/docs/backup.md+++ b/docs/backup.md@@ -11,7 +11,7 @@ Ai-memory's wiki directory is a real git repository. Every consolidation passwrites a checkpoint through libgit2 (see cross-cutting invariant #10 in[`AGENTS.md`](../AGENTS.md) and the wiki design notes in[`docs/ARCHITECTURE.md`](ARCHITECTURE.md)). That means half of a remote-backup-setup is already done for you — the wiki has its own commit history and can be+setup is already done for you: the wiki has its own commit history and can bepushed to any git remote you own. The rest of this doc is about wiring thatup, what else to include, what to exclude, and how to schedule it.@@ -49,7 +49,7 @@ running `reindex` after a restore), pair the git mirror with a periodic## Security: what ends up in your wiki-Read this before configuring a remote — decide what is acceptable to have+Read this before configuring a remote. Decide what is acceptable to haveoff your machine, then pick the shape of backup that matches.The wiki captures **everything the coding agent sees during a session**@@ -62,8 +62,8 @@ a private client name, a customer record, or a file path they considersensitive into a captured session, it is on disk in the wiki tree, andwhatever you push will carry it.-For any remote target — even a private repository on a service you-control — assume an operator or administrator on the receiving side+For any remote target, even a private repository on a service you+control, assume an operator or administrator on the receiving sidecould read the contents. Employer-managed cloud repositories(GitHub Enterprise, GitLab self-hosted, Bitbucket Data Center) may beroutinely audited by administrators, and a repository private to you on@@ -94,7 +94,7 @@ ships this list already; expand it for anything install-specificsite-specific env files).**Alternatives when the wiki content is too sensitive to store as text-on a remote** — pick whichever fits the threat model:+on a remote**; pick whichever fits the threat model:- **Encrypted archive to object storage.** `restic` or `borg` snapshotsof the data dir to a private object store (S3, Backblaze B2, Wasabi,@@ -114,8 +114,8 @@ on a remote** — pick whichever fits the threat model:convenience for zero third-party exposure.If none of the wiki content is more sensitive than what already lives-in your project's source repository, a private mirror repo is fine —-this section is for the case where it is.+in your project's source repository, a private mirror repo is fine.+This section is for the case where it is.## Backing up the wiki to a remote git repository@@ -141,7 +141,7 @@ Two caveats:## Backing up the whole data dir (mirror + push)-For a full-install backup — wiki, raw ledger, sanitized config — the+For a full-install backup (wiki, raw ledger, sanitized config), thesupported pattern is a scheduled rsync into a mirror git repository, followedby a git push. This avoids running git operations against the live wikirepository (which the server writes to) while still giving you a single@@ -150,12 +150,12 @@ remote with the full recoverable state.A worked example lives at[`docs/examples/backup/`](examples/backup/README.md) and consists of:-- `ai-memory-snapshot.sh` — an idempotent rsync + `git commit && git push` ++- `ai-memory-snapshot.sh`: an idempotent rsync + `git commit && git push` +tarball script driven by six environment variables.-- `ai-memory-backup.service` — a `systemd --user` oneshot unit that runs it.-- `ai-memory-backup.timer` — a daily user timer with a randomised delay and+- `ai-memory-backup.service`: a `systemd --user` oneshot unit that runs it.+- `ai-memory-backup.timer`: a daily user timer with a randomised delay and`Persistent=true` so a missed run after a reboot still fires.-- `.gitignore` — an exclusion list to drop into the root of the mirror+- `.gitignore`: an exclusion list to drop into the root of the mirrorrepository so derived state and secrets never land in commits.The high-level flow, one invocation per day (adjust the timer for a different@@ -192,18 +192,18 @@ Recovering the full ai-memory install from it is two steps:2. Rebuild the SQLite index from the recovered markdown:[`lifecycle-ops.md#reindex`](lifecycle-ops.md#reindex) walks through this.Sessions, observations, handoffs, users/tokens, audit rows, and- embeddings live only in the DB and are not rebuilt by `reindex` — for+ embeddings live only in the DB and are not rebuilt by `reindex`. Forthose, restore from the paired tarball via `ai-memory restore --from<tarball> --data-dir <path> --force`.## Security posture-Remote sync is your own channel, not ai-memory's — this is called out+Remote sync is your own channel, not ai-memory's. This is called outexplicitly in [`SECURITY.md`](../SECURITY.md) ("Remote sync security" underout-of-scope for v1). What that means in practice:- **Private repository, always.** ai-memory captures prompts, tool calls, and- synthesized page bodies verbatim — the same content you would treat as+ synthesized page bodies verbatim, the same content you would treat asproject source.- **Least-privilege push credential.** Prefer an SSH deploy key or afine-grained personal-access token scoped to the mirror repository only.@@ -211,8 +211,8 @@ out-of-scope for v1). What that means in practice:- **Explicit secret exclusion.** The example script rejects any file matching`SECRET_EXCLUDES` (`*.env`, `auth.json`, `.secrets`, `*.pem`, `*.key`, `*.crt` by default), and thesuggested mirror-repo `.gitignore` matches the same set. Add anything else- install-specific — private CA bundles, host-side certificates, cloud- credential files — to both lists.+ install-specific (private CA bundles, host-side certificates, cloud+ credential files) to both lists.- **Encryption at rest is out of scope for ai-memory.** If your threat modelrequires it, either put the mirror on an encrypted remote (`git-crypt`,GitLab's group-level encryption, a self-hosted Gitea over TLS with disk@@ -221,13 +221,13 @@ out-of-scope for v1). What that means in practice:## Related documents-- [`docs/lifecycle-ops.md`](lifecycle-ops.md) — `ai-memory backup`, `restore`,+- [`docs/lifecycle-ops.md`](lifecycle-ops.md): `ai-memory backup`, `restore`,`restore-page`, `reset`, `reindex` reference.-- [`docs/deploy.md#backups`](deploy.md#backups) — the on-box tarball routine+- [`docs/deploy.md#backups`](deploy.md#backups): the on-box tarball routineand the `scp`-to-laptop idiom for Docker deployments.-- [`docs/airgapped-install.md`](airgapped-install.md) — offline installs,+- [`docs/airgapped-install.md`](airgapped-install.md): offline installs,including the callout that remote git sync is user-owned plumbing.-- [`SECURITY.md`](../SECURITY.md) — the "Remote sync security" out-of-scope+- [`SECURITY.md`](../SECURITY.md): the "Remote sync security" out-of-scopenote this doc expands into a walkthrough.-- [`docs/local-embeddings.md`](local-embeddings.md) — how `models/` is+- [`docs/local-embeddings.md`](local-embeddings.md): how `models/` isfetched and pinned (why it does not need to be in the mirror).diff --git a/docs/benchmarks/README.md b/docs/benchmarks/README.mdindex a51a63a4..719854cc 100644--- a/docs/benchmarks/README.md+++ b/docs/benchmarks/README.md@@ -2,7 +2,7 @@Published retrieval-quality numbers for ai-memory, with full provenance(commit, dataset sha256, hardware, mode). Every number here was produced-by the in-repo harness — see `evals/README.md` for how to reproduce:+by the in-repo harness. `evals/README.md` explains how to reproduce them:```bashcargo build --release -p ai-memory-cli@@ -19,19 +19,19 @@ cargo run --release -p ai-memory-eval -- retrieval --fetch| 2026-09-01 | LongMemEval-S (v1) | zero-llm, stopword-filtered FTS (prior) | 0.668 | [longmemeval-s-2026-09-01-fts.md](longmemeval-s-2026-09-01-fts.md) || 2026-09-01 | LongMemEval-S (v1) | zero-llm (pre-2.0 FTS) | 0.617 | [longmemeval-s-2026-09-01.md](longmemeval-s-2026-09-01.md) |-The **2026-09-21 (2.4 RC)** re-run confirms no default-ranking regression: local+The 2026-09-21 (2.4 RC) re-run shows no default-ranking regression: local`hit@5` 0.823 → 0.815 and FTS `hit@5` 0.668 → 0.666 are identical within-run-to-run noise (2.4's aging/retrieval features are opt-in / off by default, so-default retrieval is unchanged). Full triple + provenance in+run-to-run noise. 2.4's aging/retrieval features are opt-in and off by default,+so default retrieval is unchanged. The full triple and provenance are in[retrieval-ab-r2.md](retrieval-ab-r2.md).-The 2.0 retrieval work moved overall hit@5 from **0.617 → 0.823**+The 2.0 retrieval work moved overall hit@5 from 0.617 → 0.823(+20.6 points; hit@1 0.449 → 0.536, recall@5 0.472 → 0.680) in twomeasured steps: dropping stopwords from bare-query FTS OR-joins(+5.1 hit@5, +8.5 hit@1), then the in-process local embedder with-correct masked-mean pooling — the pooling fix alone was worth ~6.6-points over a padded-attention implementation, caught by the-calibration tests. Every intermediate number was measured on this+correct masked-mean pooling. The pooling fix alone was worth ~6.6+points over a padded-attention implementation, which the+calibration tests caught. Every intermediate number was measured on thisharness before the next change landed. For context, publishedembedding-based numbers on this dataset: agentmemory 0.967 R@5(hybrid + reranking), doobidoo/mcp-memory-service 0.804 R@5.@@ -39,12 +39,12 @@ embedding-based numbers on this dataset: agentmemory 0.967 R@5## A/B comparisons (R2)The harness can also A/B two configs over the same question set and report-an **accuracy + latency + context-tokens** triple with a baseline→candidate-delta — see [retrieval-ab-r2.md](retrieval-ab-r2.md). The full-dataset A/B-(FTS baseline → local candidate, 470 scored) is published there as of the-**2026-09-21 (2.4 RC)** run: local embeddings add **+0.149 hit@5 / +0.254-recall@10** over zero-LLM FTS for ~90 ms p50 latency, with a clean-baseline-vs-baseline determinism check (all accuracy/token deltas `0.000`).+an accuracy + latency + context-tokens triple with a baseline→candidate+delta (see [retrieval-ab-r2.md](retrieval-ab-r2.md)). That file publishes the+full-dataset A/B (FTS baseline → local candidate, 470 scored) from the+2026-09-21 (2.4 RC) run: local embeddings add +0.149 hit@5 / +0.254+recall@10 over zero-LLM FTS for ~90 ms p50 latency, and the+baseline-vs-baseline determinism check is clean (all accuracy/token deltas `0.000`).## Reading the numbers@@ -58,9 +58,9 @@ baseline-vs-baseline determinism check (all accuracy/token deltas `0.000`).embedding-based retrieval over raw chat logs. Our `hit@5` is thecomparable statistic, but our pipeline additionally pays forproduction-shaped capture: excerpts are bounded at the 2 KB privacy- boundary, so evidence deep inside one long turn is genuinely out of- reach of the index. That cost is real and deliberate — the benchmark- measures the shipped system, not an idealised retriever.+ boundary, so evidence deep inside one long turn is out of reach of the+ index. The cost is deliberate, because the benchmark measures the shipped+ system rather than an idealised retriever.- **Regression gate.** Roadmap items 2-6 re-run this benchmark; a changethat lowers a slice materially is a regression to fix, not a note topublish.diff --git a/docs/benchmarks/retrieval-ab-r2.md b/docs/benchmarks/retrieval-ab-r2.mdindex ba3b10ee..8d2b3464 100644--- a/docs/benchmarks/retrieval-ab-r2.md+++ b/docs/benchmarks/retrieval-ab-r2.md@@ -4,11 +4,11 @@ The `retrieval` harness can compare two server/query configurations overthe **same** LongMemEval-S question set in one run, reporting a triple perconfig and a baseline→candidate delta:-- **accuracy** — `hit@k` / `recall@k` (as the single-config baselines do);-- **latency** — `memory_query` MCP round-trip p50 / p95, milliseconds;-- **context tokens** — the context an agent would ingest from a result,+- **accuracy**: `hit@k` / `recall@k` (as the single-config baselines do);+- **latency**: `memory_query` MCP round-trip p50 / p95, milliseconds;+- **context tokens**: the context an agent would ingest from a result,estimated as **chars / 4** over every returned hit's `title` + `snippet`- (a documented, provider-agnostic heuristic — not a real tokenizer).+ (a documented, provider-agnostic heuristic, not a real tokenizer).Provenance (commit, dataset sha256, hardware, per-config knob summary) iscarried exactly as the single-config reports carry it. See@@ -62,8 +62,8 @@ questions excluded).| ctx tok median | 316.5 | 367.5 | +51.0 |Local embeddings buy a large recall gain (hit@10 +0.198, recall@10 +0.254)-for ~90 ms added p50 query latency and ~65 more context tokens — the expected-tradeoff, now measured on the full set rather than a smoke.+for ~90 ms added p50 query latency and ~65 more context tokens. That is the+expected tradeoff, now measured on the full set rather than a smoke.Per-slice `hit@5` (candidate, local): knowledge-update 0.875, multi-session0.868, temporal-reasoning 0.780, single-session-assistant 0.821,@@ -71,12 +71,12 @@ single-session-preference 0.767, single-session-user 0.734.**Determinism check (baseline vs baseline, `--candidate`):** every accuracyand context-token delta is exactly `0.000` (latency wobbles ±5 ms at wall-clock-noise) — the harness is sound on the 2.4 tree.+noise), so the harness is sound on the 2.4 tree.**No default-ranking regression on 2.4.** The 2.4 aging/retrieval features areopt-in / off by default, so default retrieval is unchanged from 2.3.x: overallFTS `hit@5` 0.668 → 0.666 and local `hit@5` 0.823 → 0.815 versus the-2026-09-01 snapshot (commit `0ac0dcf`) — identical within run-to-run noise.+2026-09-01 snapshot (commit `0ac0dcf`), identical within run-to-run noise.**Cross-run variance (read the numbers accordingly).** The harness isdeterministic *within* a run (the `--candidate` determinism check is exactly@@ -86,7 +86,7 @@ wobble up to ~0.02–0.03 on the small-n slices in **both directions** (e.g.knowledge-update 0.875 then 0.903; single-session-user 0.734 then 0.750). Treatoverall `hit@5` as ≈ 0.82 ± 0.005 and don't over-read a single small-n slicefrom one run. Both 2.4 runs are statistically identical to the 2.3.x 0.823-baseline — a genuine per-slice regression is a drop that persists across a+baseline. A genuine per-slice regression is a drop that persists across aconfirmation re-run, not a one-run dip.Reproduce:@@ -100,7 +100,7 @@ cargo run --release -p ai-memory-eval -- retrieval --candidate### Illustrative sample-20 run (triple + QA-accuracy, NOT a baseline)Recorded to show the triple + QA columns on a real run. **`--sample 20`, 20-LongMemEval-S questions — illustrative, NOT the full-500 baseline.** The+LongMemEval-S questions: illustrative, NOT the full-500 baseline.** Thepublished baseline stays 0.823 hit@5 (local) / 0.668 zero-LLM in[README.md](README.md); do not cite the numbers below as a baseline.diff --git a/docs/companion-crates.md b/docs/companion-crates.mdindex a48d1251..d12ec235 100644--- a/docs/companion-crates.md+++ b/docs/companion-crates.md@@ -54,8 +54,7 @@ Companion projects should not:resolution, or the single-writer store boundary;- require ai-memory to host arbitrary plugin code in-process.-Companion features should be treated as separate products, not rejected ideas.-They can move faster than core, have their own UX, and carry source-specific or+Companion features are separate products. They can move faster than core, have their own UX, and carry source-specific orworkflow-specific behavior without widening ai-memory's default install.If a companion exposes browser writes, it must implement its own server-side@@ -246,7 +245,8 @@ root `cargo test --workspace`.Mirror a team's shared ai-memory pages into a project repository asreviewable markdown, so the wiki a team actually maintains can travel with-the code it documents — read-only, family-scoped, and dry-run by default.+the code it documents. The export is read-only, family-scoped, and dry-run by+default.### How it talks to ai-memory@@ -273,7 +273,7 @@ the code it documents — read-only, family-scoped, and dry-run by default.reported with a diff summary and the whole batch is refused without`--force`.- Never deletes anything (deletes are slice 4); never runs git, commits,- or pushes — it prints the commands the operator may run.+ or pushes. It prints the commands the operator may run.- Destination-path safety: traversal, dotfiles, reserved Windows names,non-portable characters, case-fold collisions, oversized bodies,symlinked destinations/components/state directories, and unknown page@@ -297,7 +297,7 @@ responses (200/ETag/304/401/404 and cursor pagination).### Roadmap (#986)-1. This slice — read-only export into a project repository.+1. This slice: read-only export into a project repository.2. Conditional mutation seam (compare-and-write) in core, if independentlyjustified.3. Bidirectional apply through public write tools.@@ -308,7 +308,7 @@ responses (200/ETag/304/401/404 and cursor pagination).Self-contained macOS accessory app at[`companions/ai-memory-macos`](../companions/ai-memory-macos). It is a-**wrapper**, not a data-seam dashboard: it ships the `ai-memory` binary and+**wrapper** rather than a data-seam dashboard: it ships the `ai-memory` binary and`hooks/` tree inside an `.app`, governs the existing LaunchAgent, and opens`/web`, `ai-memory status`, `config.toml`, the data directory, and logs.@@ -516,17 +516,16 @@ Not every adjacent tool is that shape.**Working-tree coordination is out of core, and is an *independent hookconsumer*, not a data-seam companion** (decided in #620). Several agent sessions-sharing one checkout collide over the single git index — one session's-`git add .` sweeps up another's staged work, a `--fix` run rewrites an unclaimed-tree — and the natural instinct is to build the guard on ai-memory's captured-`PreToolUse`/`PostToolUse` signal. That does not work, for two deliberate-reasons:+sharing one checkout collide over the single git index: one session's+`git add .` sweeps up another's staged work, or a `--fix` run rewrites an+unclaimed tree. Building the guard on ai-memory's captured+`PreToolUse`/`PostToolUse` signal does not work, for two deliberate reasons:- **ai-memory cannot block a tool action.** The `/hook` path is capture-only andfire-and-forget (it returns `202`/`429`, never allow/deny/ask, and processesafter responding). Hooks that await a REST round-trip can deadlock the engine- (agentmemory #221) — so there is no synchronous veto channel back to the- harness, by design.+ (agentmemory #221), so by design there is no synchronous veto channel back to+ the harness.- **ai-memory does not retain the file paths.** For closed-tool agents thestored observation is reduced to a `tool_family` label plus outcome; rawarguments, paths, and tool names are extracted only transiently for@@ -534,13 +533,13 @@ reasons:arguments, paths, or arbitrary tool names"). A consumer can see *that* a fileop happened in a session, never *which file*.-Reversing either — persisting paths, or adding a blocking hook — trades away a-privacy/bounding invariant or the anti-deadlock invariant. Both stay.+Reversing either (persisting paths, or adding a blocking hook) would trade away a+privacy/bounding invariant or the anti-deadlock invariant, so both stay.So a working-tree coordinator installs its **own** `PreToolUse` hook alongsideai-memory's, reads the raw `tool_input`, and arbitrates synchronously in its own-process with its own ephemeral ownership state (a lock file or small store —-never the wiki or SQLite). It is a *sibling on the same hook event*, not a+process with its own ephemeral ownership state (a lock file or small store,+never the wiki or SQLite). It is a *sibling on the same hook event* rather than aseam-consumer. It may still live under `companions/` for discoverability, but itdepends on the harness's hook mechanism, not on ai-memory's surfaces. Scope itto the shared-index / file-ownership class; stale-tree builds and host@@ -566,4 +565,4 @@ Poor core candidates:- project-specific scoring, pruning, or normalization policies;- companion-only admin commands.-This keeps ai-memory stable while still allowing richer tools to grow around it.+That keeps ai-memory stable while richer tools grow around it.diff --git a/docs/comparison.md b/docs/comparison.mdindex 5aa7d790..fe1935df 100644--- a/docs/comparison.md+++ b/docs/comparison.md@@ -1,9 +1,9 @@# How ai-memory compares-For anyone evaluating ai-memory against another agent-memory tool — or-migrating from one. This page aims to be **fair and specific**: what each-approach does well, where ai-memory differs, where others are ahead, and how-the field has independently validated the bets ai-memory made. The deep+This page is for anyone evaluating ai-memory against another agent-memory tool,+or migrating from one. It aims to be **fair and specific**: what each+approach does well, where ai-memory differs, where others are ahead, and where+other projects reached the same design choices independently. The detailedanalysis behind it is in [`research-2026-landscape.md`](research-2026-landscape.md)and the per-project research docs; the numbers are from[`benchmarks/`](benchmarks/README.md), reproducible from the in-repo harness.@@ -13,35 +13,35 @@ and the per-project research docs; the numbers are fromMost memory tools optimize one of: extracting atomic **facts** per turn(Mem0, LangMem), a temporal **knowledge graph** (Zep/Graphiti), anagent-editable **memory OS** (Letta, MemOS), or a hosted **context database**-(OpenViking). ai-memory optimizes something different: **a git-backed markdown+(OpenViking). ai-memory instead keeps **a git-backed markdownwiki as the source of truth, with a derived index for retrieval**, captured-automatically from lifecycle hooks, shared across agents and machines.+automatically from lifecycle hooks and shared across agents and machines.-What actually distinguishes it:+What sets it apart:- **Cross-agent and cross-machine by construction.** One server; 20+ harnesses(Claude Code, Codex, Cursor, Gemini, OpenCode, Kimi, …) feed and read the- same memory. Quit one agent, open another in the same repo, get a real- handoff. Handoffs are a typed protocol (owned, claimed exactly once), not a- note file.+ same memory. Quit one agent, open another in the same repo, and you get a+ handoff. Handoffs are a typed protocol (owned, claimed exactly once) instead+ of a note file.- **Zero-LLM default.** Capture, FTS5 + entity + graph retrieval, localembeddings, and rule-based summaries all work with **no API key**. An LLM is- opt-in for richer consolidation — not a requirement to function.-- **Files are the truth.** The wiki is plain markdown + YAML frontmatter — a- native [Open Knowledge Format](okf.md) (OKF v0.2) bundle. `grep` it, open it- in Obsidian, edit by hand, `rsync` it. The SQLite index is derived and+ opt-in for richer consolidation; nothing requires one.+- **Files are the truth.** The wiki is plain markdown + YAML frontmatter, a+ native [Open Knowledge Format](okf.md) (OKF v0.2) bundle. You can `grep` it, open it+ in Obsidian, edit it by hand, or `rsync` it. The SQLite index is derived andrebuildable. Nothing is trapped in a vector store or binary blob.-- **Multi-user without a paid tier.** An auth ladder (root → DB-user tokens →- OIDC), per-person attribution, audit log, and the invariant that **pages are- shared per project while handoffs stay owned** — a team story built in.+- **Multi-user without a paid tier.** It has an auth ladder (root → DB-user tokens →+ OIDC), per-person attribution, an audit log, and the invariant that **pages are+ shared per project while handoffs stay owned**, so team use is built in.- **One self-contained binary.** Bundled SQLite, vendored libgit2; no external- services to stand up. Runs on a laptop, a homelab box, or a LAN server.+ services to stand up. It runs on a laptop, a homelab box, or a LAN server.-And it publishes numbers: **LongMemEval-S hit@5 0.823** (local-embeddings-default; 0.668 zero-LLM), produced by the in-repo harness with full provenance-— not a marketing claim. For context on the same dataset, mcp-memory-service-reports 0.804 R@5 and agentmemory 0.967 R@5 (hybrid + reranking); ai-memory is-comparable to the former and honestly below the latter, and it documents *why*+It also publishes numbers: **LongMemEval-S hit@5 0.823** (local-embeddings+default; 0.668 zero-LLM), produced by the in-repo harness with full provenance.+For context on the same dataset, mcp-memory-service+reports 0.804 R@5 and agentmemory 0.967 R@5 (hybrid + reranking). ai-memory is+comparable to the former and below the latter, and it documents *why*(the pipeline pays a real 2 KB privacy-capture cost the raw-log retrievers donot). See [where we're behind](#where-were-behind-or-different-by-choice).@@ -51,7 +51,7 @@ not). See [where we're behind](#where-were-behind-or-different-by-choice).|---|---|---|---|| Fact extractors | Mem0, LangMem | Cheap per-turn personalization | Atomic facts lose relational/causal context (see [TriMem](research-2026-landscape.md#4-research-developments-worth-knowing)); LLM-per-turn; not file-first || Hosted memory API (hybrid) | **Supermemory**, **LiquidLM** | Chunk-RAG + LLM temporal fact-graph + per-user profiles in one query; managed connectors (Drive/Notion/GitHub), multimodal, metadata/tag query filters | Cloud-first (best features + extraction are paid/hosted); LLM-required quality path; an opaque store is the source of truth (not file-first, nothing to `grep`/diff). Supermemory's MIT self-host binary drops the connectors + extraction models; LiquidLM is closed-source and cloud-only (no self-host at all) |-| User-modeling / theory-of-mind | **Honcho** (Plastic Labs) | Reasoning-derived model of what each "peer" knows/believes over time — personalizes around the *human* the agent serves | Different problem: it remembers the *user*, ai-memory remembers the *project*. Opaque Postgres, LLM-required (Deriver/Dreamer), multi-service stack; adjacent (shares MCP/plugin delivery) but not a coding-memory migration target. ai-memory borrowed the *conveniences*, not the engine: an opt-in dialectic **answer** over its own hits and a **reasoning** tier now ship (both off by default, LLM-required) |+| User-modeling / theory-of-mind | **Honcho** (Plastic Labs) | Reasoning-derived model of what each "peer" knows/believes over time; personalizes around the *human* the agent serves | Different problem: it remembers the *user*, ai-memory remembers the *project*. Opaque Postgres, LLM-required (Deriver/Dreamer), multi-service stack; adjacent (shares MCP/plugin delivery) but not a coding-memory migration target. ai-memory borrowed the *conveniences*, not the engine: an opt-in dialectic **answer** over its own hits and a **reasoning** tier now ship (both off by default, LLM-required) || Temporal knowledge graph | Zep/Graphiti, Cognee | Bi-temporal "what was true vs believed when" | Needs a graph DB; heavier to self-host. ai-memory ships **bi-temporal-lite** on SQLite ([`temporal.md`](temporal.md)) + typed edges ([`typed-edges.md`](typed-edges.md)) for the useful part || Memory OS / self-editing | Letta, MemOS, MIRIX | Agent curates its own tiered memory | Token-expensive self-editing; Letta itself now concedes file-first ("Is a Filesystem All You Need?") || Hosted context database | **OpenViking** (ByteDance) | Progressive L0/L1/L2 loading; directory-scoped retrieval; broad integrations | LLM-**required** (VLM + embeddings); opaque swappable storage; AGPLv3 core + SaaS/enterprise weight |@@ -66,11 +66,11 @@ not). See [where we're behind](#where-were-behind-or-different-by-choice).## Maturity and maintenance-This is a crowded, fast-moving field, and it is only fair to say so: **every tool+This is a crowded, fast-moving field, and **every toolcompared here is actively maintained** (as of 2026-09-18, all had commits within-the last ~10 days — none stale, none archived; the five new-entrant rows below+the last ~10 days, and none was stale or archived; the five new-entrant rows belowwere verified 2026-09-22). Raw GitHub popularity, though,-tracks funding and app-developer reach more than coding-agent fitness — the+tracks funding and app-developer reach more than coding-agent fitness. Thestar leaders are the app-personalization and hosted-context players (a differentbuyer), while the tools closest to ai-memory's file-first, self-hosted,coding-continuity niche are smaller by design.@@ -100,31 +100,31 @@ Full figures, sources, and per-tool caveats: [`research-2026-landscape.md`](rese## How the field validates the approach-The strongest endorsement of ai-memory's design is that others arrived at its-core bets independently, from different substrates:+Other projects, built on different substrates, arrived at ai-memory's core+design choices independently:- **Google standardized file-first.** The [Open Knowledge Format](okf.md) (June- 2026) — markdown + YAML frontmatter, one concept per file, no runtime — is+ 2026), markdown + YAML frontmatter with one concept per file and no runtime, isthe interop layer for agent memory. ai-memory's wiki is a native OKF bundle.-- **Letta conceded the filesystem.** The "memory OS" camp's own leader+- **Letta conceded the filesystem.** The leader of the "memory OS" camppublished that agents post-trained for file search rival specialized memory- systems — the file-as-truth + derived-index split ai-memory uses.-- **Hindsight's paper validates pages-over-facts.** A funded competitor on the+ systems. That is the file-as-truth + derived-index split ai-memory uses.+- **Hindsight's paper supports pages over facts.** A funded competitor on the*opposite* (Postgres, LLM-required) substrate makes its top tier "mental- models" — living markdown pages a background process rewrites and the agent+ models": living markdown pages a background process rewrites and the agentboots from. That is ai-memory's `wiki/` + [auto-improve loop](auto-improvement-loop.md)under another name, backed by arXiv:2512.12818.-- **OpenViking validates document memory + a consolidation loop.** ByteDance's+- **OpenViking uses document memory + a consolidation loop.** ByteDance'sentrant stores document/directory-scoped memory (not atomic facts) with a- background extract/merge pass and a "compile" step into wikis — the same- shape as ai-memory's consolidation, from an LLM-required corner.+ background extract/merge pass and a "compile" step into wikis. That is the same+ shape as ai-memory's consolidation, from an LLM-required starting point.- **The literature backs it.** TriMem (arXiv:2605.19952) argues document/page/narrative hierarchies beat atomic-fact stores; the Storage→Reflection→Experience survey (arXiv:2605.06716) names cross-trajectory abstraction as- the frontier — which ai-memory's [experience pass](experience.md) targets.+ the frontier, which ai-memory's [experience pass](experience.md) targets.-ai-memory also **shipped the borrowable ideas** from that research rather than-just cataloguing them: typed relation edges, ingestion-time temporal validity+ai-memory also **shipped the borrowable ideas** from that research instead of+only cataloguing them: typed relation edges, ingestion-time temporal validitywith `as_of` queries, local (no-key) embeddings as the default, and thecross-session abstraction pass are all in the product today. The 2.4 line addedfive retrieval conveniences, each **opt-in with defaults byte-identical**: a@@ -135,28 +135,28 @@ basic-memory/LiquidLM), an opt-in dialectic **answer** over hits and astanding-context briefing, LiquidLM), and a **show-superseded** retrieval knobover the supersession chains.-The 2.4 line also closed most of the **memory-aging** gap — the decay,-compression, and consolidation machinery the field converged on — on+The 2.4 line also closed most of the **memory-aging** gap (the decay,+compression, and consolidation machinery the field converged on) onai-memory's own zero-LLM, file-first terms (design of record:[`design-memory-aging.md`](design-memory-aging.md)):- **Per-tier decay curves** (mcp-memory-service's 365/180/90/30 shape): thesingle global half-life is now a tunable per-tier `[decay.half_life_days]`- table. Identity default — an upgrade changes no score.+ table. The default is the identity, so an upgrade changes no score.- **Extractive tier-down of cold episodic pages** (agentmemory andmcp-memory-service ship extractive, zero-LLM compression as a default):instead of evicting a cold page, ai-memory can compact it to its abstract,a summary, and a regex-mined keep-token set (paths, URLs, code spans, error- codes) and drop the prose — reversible through git + the supersession chain.+ codes) and drop the prose. This is reversible through git + the supersession chain.- **Cold-cluster dedup** (mcp-memory-service's DBSCAN): near-duplicate coldepisodic pages cluster (adaptive-eps DBSCAN over already-stored embeddings)- and collapse to one survivor — superseded, never deleted.+ and collapse to one survivor. The others are superseded, never deleted.- **Zero-LLM contradiction flagging** (mcp-memory-service's 0.4–0.75cosine band): `memory_lint` now surfaces likely-conflicting pages, advisoryonly, from existing embeddings.- **Access-weighted retention** (mcp-memory-service's access boost): a page ahuman opens, searches, or reaches through the link graph resists decay like- a search hit — now on *every* read path.+ a search hit, now on *every* read path.- **Belief-strength confidence** (Hindsight, mcp-memory-service): a read-time,zero-LLM `confidence` per page (distinct-session breadth, recency, live`contradicts` count), surfaced in `memory_query explain` and `memory_status`.@@ -164,11 +164,11 @@ ai-memory's own zero-LLM, file-first terms (design of record:Supermemory's "dreaming"): idle-scheduled, cancel-on-activity,surprisal-first cross-session rewrite/merge of cold clusters.-Two of these change behavior only where a provider is configured and the-operator opts in — belief-strength folded into ranking, and the dream pass —+Two of these, belief-strength folded into ranking and the dream pass, change+behavior only where a provider is configured and the operator opts in,and both are **off by default and gated on a recall eval (R2) before they maydefault on**. No such eval has been run yet, so ai-memory claims *parity of-mechanism, not a measured quality win*: the substrate ships, honestly, off.+mechanism, not a measured quality win*: the code ships, switched off.Everything else here is zero-LLM, reversible, and off by default until anoperator turns it on.@@ -178,18 +178,18 @@ operator turns it on.compiles into readable **pages** you can open and edit, not opaque fact rows.Retrieval fuses FTS + entity + graph + vectors instead of vector-only.- **From Zep/Graphiti:** you get bi-temporal-lite (`as_of`, version-filtered- search) and typed edges without standing up a graph database — on one binary.+ search) and typed edges in one binary, without standing up a graph database.- **From Claude Code's built-in memory:** the same "remember my project"- convenience, but synced across machines and agents, searchable, team-capable,- and capturing tool lifecycle — not a per-laptop `MEMORY.md`.-- **From mcp-memory-service:** a very close sibling; the switch is fact-rows →+ convenience, but synced across machines and agents, searchable, usable by a+ team, and capturing tool lifecycle, where the built-in memory is a per-laptop `MEMORY.md`.+- **From mcp-memory-service:** a very close sibling. The switch is fact-rows →wiki pages (human-editable markdown truth) and cross-agent handoffs as afirst-class protocol. Cross-project [agent messaging](agent-messaging.md) is- new ground neither had as a typed queue. On aging you keep what you relied on- — the 2.4 line matches its per-tier decay curves, extractive compression,+ new ground neither had as a typed queue. On aging you keep what you relied on:+ the 2.4 line matches its per-tier decay curves, extractive compression,DBSCAN cold-cluster dedup, access boosts, and 0.4–0.75-band contradiction- detection — but done **zero-LLM by default, reversibly** (every collapse- supersedes rather than deletes; `restore-page` recovers the original), and+ detection, but does them **zero-LLM by default, reversibly** (every collapse+ supersedes instead of deleting; `restore-page` recovers the original), and**off by default** so an upgrade evicts nothing.- **From Supermemory / LiquidLM (a hosted memory API):** you trade a cloudvault and a managed multimodal RAG service for a self-contained binary whose@@ -198,25 +198,25 @@ operator turns it on.explicit uploads. You give up (for now) their multimodal ingestion(video/audio/PDF/Office), a polished consumer web app + grounded chat, andmanaged hosting; you gain data ownership, no required API spend, offline- operation, per-project team sharing, and — now opt-in on the 2.4 line — a+ operation, per-project team sharing, and (opt-in on the 2.4 line) apin-before-search contract and a bounded related-pages graph walk over the link- neighbours ai-memory already computes. Different job: they build a general- "second brain," ai-memory remembers *this repo*.+ neighbours ai-memory already computes. The jobs differ: they build a general+ "second brain," while ai-memory remembers *this repo*.- **From Hindsight / OpenViking:** you trade a hosted, LLM-required service fora self-contained binary that runs zero-LLM by default and keeps memory in- files you own. The consolidation shape you came for is here on 2.4 — a+ files you own. The consolidation shape you came for is here on 2.4: abelief-strength `confidence` over evidence and an idle-scheduled,- cancel-on-activity, surprisal-first LLM "dream" rewrite of cold clusters —- but as **opt-in layers that never delete a source** (the pre-merge versions- stay reachable) and are **off by default and gated on a recall eval before- default-on**, over a zero-LLM core, rather than a mandatory loop. OpenViking's+ cancel-on-activity, surprisal-first LLM "dream" rewrite of cold clusters.+ Both are **opt-in layers that never delete a source** (the pre-merge versions+ stay reachable), **off by default and gated on a recall eval before+ default-on**, and sit over a zero-LLM core instead of forming a mandatory loop. OpenViking'sL0/L1/L2 progressive tiers map onto ai-memory's extractive tier-down(abstract + summary + keep-tokens). You give up (for now) their VLM-drivenextraction depth and their published headline accuracy numbers; you gain novendor lock-in, no required API spend, and per-project team sharing ratherthan strict per-bank isolation.- **From Engram (self-hosted coding-agent store):** the closest operational- sibling among the newcomers — a single self-hosted binary, SQLite+FTS5, MCP,+ sibling among the newcomers: a single self-hosted binary, SQLite+FTS5, MCP,project scope, and session-summary handoffs. The switch is Engram'sagent-saved structured rows (the agent calls `mem_*` MCP tools; SQLite is thetruth, git-syncing compressed chunks) → ai-memory's automatic lifecycle-hook@@ -233,16 +233,16 @@ operator turns it on.SQLite+LanceDB derived indexes map onto ai-memory's derived SQLite/FTS5(+localembeddings). You give up (for now) memU's turnkey skill-distillation packagingand hosted cloud, and EverOS's LanceDB vector tier.-- **From Caura (governed multi-agent fleet memory):** different buyer. Caura- optimizes org-scale fleet governance — agent/team/org visibility scopes, four- trust tiers, an audit log, PII flagging — on Postgres+pgvector with LLM+- **From Caura (governed multi-agent fleet memory):** a different buyer. Caura+ optimizes org-scale fleet governance (agent/team/org visibility scopes, four+ trust tiers, an audit log, PII flagging) on Postgres+pgvector with LLMextraction. ai-memory shares the multi-agent/multi-user goal but at*project* scope (`pages shared, batons owned`, invariant #16) with a- self-hosted auth ladder and audit log, not fleet-wide trust tiers. If you need- cross-fleet trust governance across hundreds of agents, that is Caura's lane,- not ours; if you want file-first, zero-LLM, single-binary project memory, it is- ours. (Caura's trust-tier governance is an honest capability we do not match —- see [`competitive-parity.md`](competitive-parity.md).)+ self-hosted auth ladder and audit log, without fleet-wide trust tiers. If you need+ cross-fleet trust governance across hundreds of agents, use Caura; if you want+ file-first, zero-LLM, single-binary project memory, use ai-memory. (Caura's+ trust-tier governance is a real capability we do not match; see+ [`competitive-parity.md`](competitive-parity.md).)- **From TencentDB Agent Memory (proxy fan-in server):** you trade a Nodethree-service proxy that intercepts each harness's API base URL (distillingChat Memory / Skill / Wiki / CodeGraph assets) for a file-first binary that@@ -254,39 +254,37 @@ operator turns it on.## Where we're behind, or different by choice-Fair means saying this plainly:-- **Raw retrieval score, and no local reranker.** 0.823 hit@5 on LongMemEval-Sis comparable to mcp-memory-service and below agentmemory's 0.967 (hybrid +- reranking). Part is deliberate — a 2 KB privacy cap on captured excerpts puts- evidence deep inside one long turn out of the index's reach; the benchmark- measures the *shipped, sanitized* system, not an idealized retriever. The only+ reranking). Part of the gap is deliberate: a 2 KB privacy cap on captured excerpts puts+ evidence deep inside one long turn out of the index's reach, and the benchmark+ measures the *shipped, sanitized* system instead of an idealized retriever. The onlyreranker is LLM-as-judge, so the zero-LLM default path has none; the opt-in`answer=true` dialectic synthesis (2.4) is likewise LLM-required, off by- default, and its end-to-end QA-accuracy is early and small-sample (see- [`benchmarks/retrieval-ab-r2.md`](benchmarks/retrieval-ab-r2.md)), not a- headline claim.-- **Belief-strength and the dream pass ship, but off — no proven win yet.**+ default, and its end-to-end QA-accuracy result is early and small-sample (see+ [`benchmarks/retrieval-ab-r2.md`](benchmarks/retrieval-ab-r2.md)), so we do+ not make it a headline claim.+- **Belief-strength and the dream pass ship, but off, with no proven win yet.**The 2.4 memory-aging set includes the two pieces that could move retrieval- *quality* — folding belief-strength `confidence` into ranking authority, and- the LLM "dream" rewrite of cold clusters — but both are **off by default and+ *quality*, folding belief-strength `confidence` into ranking authority and+ the LLM "dream" rewrite of cold clusters, but both are **off by default andgated on a recall eval (R2) that has not been run**. We claim parity of*mechanism* with Hindsight/mcp-memory-service here, not a measured recall or- QA improvement; until R2 shows a positive delta the honest statement is+ QA improvement. Until R2 shows a positive delta the accurate statement is"shipped, opt-in, unproven," and the default path is unchanged.- **Headline benchmark comparability.** Hindsight quotes 91.4% *accuracy* and- OpenViking quotes LoCoMo lifts — different datasets/metrics than our hit@5,+ OpenViking quotes LoCoMo lifts. Those are different datasets/metrics than our hit@5,and both are self-reported/preprint. We publish a reproducible harness and a- single stated metric rather than a bigger number.+ single stated metric instead of a bigger number.- **No VLM fact extraction.** Because the default path is zero-LLM, ai-memorydoes not do the LLM-per-turn atomic extraction the fact-extractor andLLM-required systems build on. Consolidation is opt-in and page-shaped.- **Not a graph database.** ai-memory chooses bi-temporal-lite on SQLite over a- full temporal knowledge graph — the useful 80%, not the graph-query surface.-- **Single server, not SaaS.** No hosted multi-region tier, no enterprise- console. That is the point (own your data, one binary), but it is a- difference if you want managed infrastructure.+ full temporal knowledge graph. It covers the useful 80% without the graph-query surface.+- **Single server, not SaaS.** There is no hosted multi-region tier and no enterprise+ console. That is intentional (own your data, one binary), but it matters+ if you want managed infrastructure.-If a specific comparison here reads as unfair or out of date, open an issue —-these numbers and claims are meant to be checkable against the linked research+If a specific comparison here reads as unfair or out of date, open an issue.+These numbers and claims are meant to be checkable against the linked researchand the reproducible harness.diff --git a/docs/competitive-parity.md b/docs/competitive-parity.mdindex f1a1d33b..2f3d17c7 100644--- a/docs/competitive-parity.md+++ b/docs/competitive-parity.md@@ -3,26 +3,26 @@A self-critical internal audit, September 2026. Sibling to the public[`comparison.md`](comparison.md) (the fair pitch) and[`research-2026-landscape.md`](research-2026-landscape.md) (what each competitor-does + what to borrow). This doc asks the harder, honest question the pitch+does + what to borrow). This doc asks the question the pitchcannot:-> **In the goals where we overlap a competitor, are we actually *better* — or did+> **In the goals where we overlap a competitor, are we actually *better*, or did> we copy their ideas without improving on them? If I already use competitor X,> is ai-memory worth migrating *to*? What do I gain that X doesn't have, and what> do I give up?**The premise being tested: *we do the same basic stuff and have extra to justify-the switch.* Where that premise holds, migration is real; where we only matched-(or fell behind), it isn't. Every ai-memory claim below was verified against the-code, not the marketing; competitor claims against their primary sources. Goals-that simply differ from ours are called out as "different buyer — not a migration-target," not forced into a comparison.+the switch.* Where that premise holds, migration makes sense; where we only matched+(or fell behind), it doesn't. Every ai-memory claim below was verified against the+code rather than the marketing, and competitor claims against their primary+sources. Goals that simply differ from ours are labeled "different buyer, not a+migration target" instead of being forced into a comparison.## The migration barA competitor's user should switch only if ai-memory (a) does the basic thing theyrely on **at parity or better**, and (b) adds something they can't get where they-are. So each verdict rests on two honest ledgers: **our verified moat** (the+are. So each verdict rests on two ledgers: **our verified moat** (the"extra") and **our real gaps** (where "better" is not yet true).## ai-memory's verified moat (the "extra") — real in code@@ -32,54 +32,52 @@ None of the competitors below has more than one or two of these; none has all.- **Zero-LLM default path.** Capture, FTS5 + entity + link RRF retrieval, localembeddings, and rule-based summaries all work with no API key (invariant #13).- **Files are the source of truth.** A git-backed markdown wiki, committed every- consolidation pass — `grep`/diff/Obsidian/rsync it. The DB is a rebuildable+ consolidation pass, so you can `grep`/diff/Obsidian/rsync it. The DB is a rebuildableindex. (Letta's own "Is a Filesystem All You Need?" concession validates this.)-- **One self-contained binary** — bundled SQLite, vendored libgit2, no sidecar,+- **One self-contained binary**: bundled SQLite, vendored libgit2, no sidecar,no external DB, no graph server.- **Cross-harness lifecycle capture** across 20+ harnesses through a typedsanitizer boundary (invariants #5/#6).-- **Typed claim-once handoffs + cross-project agent messaging** — protocols, not+- **Typed claim-once handoffs + cross-project agent messaging**: protocols, not"both agents read the same files."- **Multi-user shared-within-project** ("pages shared, batons owned", invariant- #16) — self-hosted, no paid tier.+ #16), self-hosted, with no paid tier.- **A single honest, reproducible benchmark** (0.823 hit@5 local; 0.668 zero-LLM).## Migration verdicts, by competitor| From | Migrate to ai-memory? | You gain | You give up ||---|---|---|---|-| **mcp-memory-service** (fact-row twin) | **Yes** if you liked hook capture + typed edges + honest numbers | Files-as-truth (not opaque fact rows), handoffs, cross-project messaging, `as_of` temporal, a marginally better + reproducible number, and — new on 2.4 — its aging set at parity done zero-LLM/reversible/off-by-default (per-tier decay curves, extractive compression, DBSCAN cold-cluster dedup, access boosts, 0.4–0.75-band contradiction flagging) | Cloud/multi-backend replication (Cloudflare/Milvus), graph viz. (Belief-strength + clustering consolidation are no longer a give-up — ai-memory now ships both, clustering as a zero-LLM default-off pass, belief-strength off/R2-gated) |+| **mcp-memory-service** (fact-row twin) | **Yes** if you liked hook capture + typed edges + honest numbers | Files-as-truth (not opaque fact rows), handoffs, cross-project messaging, `as_of` temporal, a marginally better + reproducible number, and (new on 2.4) its aging set at parity done zero-LLM/reversible/off-by-default (per-tier decay curves, extractive compression, DBSCAN cold-cluster dedup, access boosts, 0.4–0.75-band contradiction flagging) | Cloud/multi-backend replication (Cloudflare/Milvus), graph viz. (Belief-strength + clustering consolidation are no longer a give-up: ai-memory now ships both, clustering as a zero-LLM default-off pass, belief-strength off/R2-gated) || **basic-memory** (file-first sibling) | **Yes** for multi-harness coding continuity; **no** for a personal Obsidian KB with live team co-edit | Ambient capture (no `write_note` ceremony), full lifecycle, handoffs/messaging, git-versioned truth, published numbers | Local zero-cost reranking, real-time collaborative editing, Postgres backend, `build_context` graph-walk, hosted mobile/web UX || **agentmemory** (ideological sibling) | **Yes** for operability + data ownership | Self-contained binary (no `iii-engine` sidecar), files-as-truth, SQL indexes committed in-txn, typed handoffs, Windows parity, fuller auth | ~13 pts raw R@5 (they rerank), a P2P mesh-sync primitive, ~31 tools of (mostly speculative) surface |-| **Claude Code built-in memory** | **Yes** for teams / multi-machine / multi-harness; **not obviously** for a solo dev on one machine in Claude only | Cross-machine, cross-harness, team sharing, tool-lifecycle capture, real search | Zero setup — it's already on with no server to run (our one honest structural disadvantage for the solo case) |-| **Hindsight** (pages-over-facts) | **Yes** for self-hosted/offline/team; **no** if you need their published accuracy + are fine with an LLM-required cloud | Zero-LLM, files you own, one binary, in-project team sharing (vs strict per-bank isolation), and — new on 2.4 — a belief-strength `confidence` + an opt-in "dream" rewrite that borrow their model but never delete a source and keep the zero-LLM default | Their published headline accuracy, VLM/LLM extraction depth, and belief-strength that *actually moves ranking by default* (ours ships but is off/R2-gated until an eval proves it) |+| **Claude Code built-in memory** | **Yes** for teams / multi-machine / multi-harness; **not obviously** for a solo dev on one machine in Claude only | Cross-machine, cross-harness, team sharing, tool-lifecycle capture, real search | Zero setup: it's already on with no server to run (our one honest structural disadvantage for the solo case) |+| **Hindsight** (pages-over-facts) | **Yes** for self-hosted/offline/team; **no** if you need their published accuracy + are fine with an LLM-required cloud | Zero-LLM, files you own, one binary, in-project team sharing (vs strict per-bank isolation), and (new on 2.4) a belief-strength `confidence` + an opt-in "dream" rewrite that borrow their model but never delete a source and keep the zero-LLM default | Their published headline accuracy, VLM/LLM extraction depth, and belief-strength that *actually moves ranking by default* (ours ships but is off/R2-gated until an eval proves it) || **Zep/Graphiti** (temporal KG) | **Yes** for self-hosting coders avoiding Neo4j+LLM (Community Edition is discontinued); **no** for enterprise graph-query/world-time | One binary on SQLite, zero-LLM, files, coding-harness native, a supported self-host | True bi-temporal (world vs observed time), Cypher/BFS graph queries, custom entity/edge types, `minRating` |-| **Mem0** | **Mostly no — different buyer** (app end-user personalization). Yes only if you (mis)used it as coding-session memory | Zero-LLM, per-repo, cross-harness, editable pages, no API spend | Mem0's SDK/integration ecosystem + managed cloud personalization |+| **Mem0** | **Mostly no: different buyer** (app end-user personalization). Yes only if you (mis)used it as coding-session memory | Zero-LLM, per-repo, cross-harness, editable pages, no API spend | Mem0's SDK/integration ecosystem + managed cloud personalization || **Letta / MemOS** | **No** if you're building your agent *on* Letta; **yes** if you only wanted your existing coding agent to remember | Additive memory under your existing harness, zero-LLM, no runtime adoption | The ADE + agent-framework machinery (which you don't need unless building on Letta) |-| **Honcho** (Plastic Labs) | **No — different problem.** It models the *human* (theory-of-mind peer representations); we remember the *project* | If you (mis)used it for coding continuity: file-first git truth, zero-LLM, single-binary self-host, per-project scoping, no mandatory LLM egress | Its user-psychology reasoning engine (Deriver/Dreamer/Dialectic), published user-recall benchmarks, managed cloud — none of which a coding-memory user needs |-| **LiquidLM** (solo-built hosted memory API, Supermemory camp) | **Weak — different job.** It's a cloud "second brain" with multimodal RAG; we're automatic, file-first coding memory | Data ownership (markdown+git, no opaque cloud), zero-LLM default, single-binary self-host, automatic hook capture, per-project team sharing, no API/subscription spend | Its multimodal ingestion (video/audio/PDF/Office), polished web app + grounded chat, managed hosting, GitHub-sync connector, and out-of-the-box rerank |-| **Engram** (self-hosted coding-agent store, issue #810) | **Yes** — the closest newcomer to our lane | Files-as-truth git-markdown wiki (vs SQLite-as-truth + git-synced compressed chunks), **automatic lifecycle-hook capture** (vs agent-driven `mem_*` MCP saves), typed claim-once handoffs + cross-project messaging, multi-user page sharing, published numbers | Engram's zero-config Go binary is equally lean; you give up its managed Cloud replication add-on. A near-tie on posture — the switch is capture model + wiki-vs-rows, not moat depth |+| **Honcho** (Plastic Labs) | **No: different problem.** It models the *human* (theory-of-mind peer representations); we remember the *project* | If you (mis)used it for coding continuity: file-first git truth, zero-LLM, single-binary self-host, per-project scoping, no mandatory LLM egress | Its user-psychology reasoning engine (Deriver/Dreamer/Dialectic), published user-recall benchmarks, managed cloud, none of which a coding-memory user needs |+| **LiquidLM** (solo-built hosted memory API, Supermemory camp) | **Weak: different job.** It's a cloud "second brain" with multimodal RAG; we're automatic, file-first coding memory | Data ownership (markdown+git, no opaque cloud), zero-LLM default, single-binary self-host, automatic hook capture, per-project team sharing, no API/subscription spend | Its multimodal ingestion (video/audio/PDF/Office), polished web app + grounded chat, managed hosting, GitHub-sync connector, and out-of-the-box rerank |+| **Engram** (self-hosted coding-agent store, issue #810) | **Yes**, the closest newcomer to our lane | Files-as-truth git-markdown wiki (vs SQLite-as-truth + git-synced compressed chunks), **automatic lifecycle-hook capture** (vs agent-driven `mem_*` MCP saves), typed claim-once handoffs + cross-project messaging, multi-user page sharing, published numbers | Engram's zero-config Go binary is equally lean; you give up its managed Cloud replication add-on. A near-tie on posture; the switch is about capture model + wiki-vs-rows, not moat depth || **EverOS** (file-first sibling, issue #810) | **Yes** for zero-LLM/single-binary/team; **no** if you want its LanceDB vector tier or user-track modeling | Zero-LLM default (EverOS's minimal tier still needs an LLM for the core flow), one self-contained binary (vs a Python stack), cross-harness lifecycle capture, typed handoffs/messaging, published numbers | EverOS's LanceDB vector index, its first-class user `episodes/profile` track, and its packaged offline "memory evolution" UX |-| **memU** (LLM-wiki + skill distillation, issue #810) | **Partly** — same file-first instinct, different default | Zero-LLM capture/retrieval by default (memU's distill flow is LLM-required), one binary (vs Python + sidecars patching host instruction files), MCP + hooks, git-versioned truth | memU's turnkey **skill-distillation-into-Markdown** packaging and its hosted cloud (memu.so). Our nearest equivalent is the opt-in experience/auto-improve pass, not a one-command skill distiller |-| **Caura** (governed fleet memory, issue #810) | **No — different buyer** (org-scale multi-agent governance) | If you (mis)used it for one project: file-first git truth, zero-LLM, single-binary self-host, per-project scoping, no LLM egress | Its **fleet-governance layer** — org/team/agent visibility scopes and **four cross-fleet trust tiers** — which ai-memory does **not** match (see honest gaps); plus its managed platform and self-reported LoCoMo/LongMemEval numbers |-| **TencentDB Agent Memory** (proxy fan-in server, issue #810) | **Mostly no — different capture model** | Hook/MCP capture into a file-first wiki you own (vs a base-URL proxy intercepting traffic), zero-LLM default, one binary vs a Node three-service stack, typed handoffs | Its zero-code proxy integration and its **CodeGraph** codebase index (adjacent code-intelligence we don't do). Note: needs no Tencent DB (SQLite default) — the name misleads |-| **Mem0/Zep for apps; OpenViking, Supermemory, LiquidLM, Honcho, Caura** | different buyer (app/user personalization, hosted context DB / RAG-as-a-service, user-modeling, org-scale fleet governance) — **not migration targets** | — | — |--Net: the premise holds where it should. For a **self-hosted, multi-harness,-team, zero-LLM, data-ownership** coding-memory use case, ai-memory does the basics-and adds a moat none of them fully have — migration is justified. It does *not*-hold for app/user personalization (Mem0/Supermemory/LiquidLM), user-modeling /+| **memU** (LLM-wiki + skill distillation, issue #810) | **Partly**: same file-first instinct, different default | Zero-LLM capture/retrieval by default (memU's distill flow is LLM-required), one binary (vs Python + sidecars patching host instruction files), MCP + hooks, git-versioned truth | memU's turnkey **skill-distillation-into-Markdown** packaging and its hosted cloud (memu.so). Our nearest equivalent is the opt-in experience/auto-improve pass, not a one-command skill distiller |+| **Caura** (governed fleet memory, issue #810) | **No: different buyer** (org-scale multi-agent governance) | If you (mis)used it for one project: file-first git truth, zero-LLM, single-binary self-host, per-project scoping, no LLM egress | Its **fleet-governance layer** (org/team/agent visibility scopes and **four cross-fleet trust tiers**), which ai-memory does **not** match (see honest gaps); plus its managed platform and self-reported LoCoMo/LongMemEval numbers |+| **TencentDB Agent Memory** (proxy fan-in server, issue #810) | **Mostly no: different capture model** | Hook/MCP capture into a file-first wiki you own (vs a base-URL proxy intercepting traffic), zero-LLM default, one binary vs a Node three-service stack, typed handoffs | Its zero-code proxy integration and its **CodeGraph** codebase index (adjacent code-intelligence we don't do). Note: needs no Tencent DB (SQLite default); the name misleads |+| **Mem0/Zep for apps; OpenViking, Supermemory, LiquidLM, Honcho, Caura** | different buyer (app/user personalization, hosted context DB / RAG-as-a-service, user-modeling, org-scale fleet governance), **not migration targets** | — | — |++Net: for a **self-hosted, multi-harness, team, zero-LLM, data-ownership**+coding-memory use case, ai-memory does the basics and adds a moat none of them+fully have, so migration is justified. The premise does *not* hold for app/user personalization (Mem0/Supermemory/LiquidLM), user-modeling /theory-of-mind (Honcho), enterprise graph queries (Zep Cloud), agent-building-runtimes (Letta), or a solo dev happy with Claude's built-in — those are+runtimes (Letta), or a solo dev happy with Claude's built-in. Those aredifferent buyers, and we should say so rather than overclaim.## Did we copy without improving? — the borrowed-ideas audit-The sharp finding: ai-memory did **not** cargo-cult this field. Of the ideas it-took, most are at parity-or-better; the exceptions are **honestly-scoped-but--unfinished substrate**, each deliberately gated behind "prove it with an eval-first." The risk is not shallow copying — it is that borrowed ideas sit **dormant**-until the eval harness (R2) that would justify activating them gets built.+The main finding: ai-memory did **not** cargo-cult this field. Of the ideas it+took, most are at parity-or-better; the exceptions are **scoped-but-unfinished+substrate**, each deliberately gated behind "prove it with an eval first." The+remaining risk is that borrowed ideas sit **dormant** until the eval harness (R2) that would justify activating them gets built.| Borrowed idea | From | Verdict | Detail ||---|---|---|---|@@ -87,26 +85,26 @@ until the eval harness (R2) that would justify activating them gets built.| Hook capture | mcp-memory-service | **BETTER** | 20+ harnesses + typed sanitizer boundary + backpressure vs Claude-Code-centric || Versioned supersession | agentmemory | **BETTER** | A concurrent divergent write supersedes but the loser stays reachable (invariant #16); theirs flips `isLatest` || Retention-as-formula (decay) | agentmemory | **BETTER** | Real SQL decay math vs in-memory O(N²) Jaccard capped at 1000 rows; 2.4 adds opt-in per-tier half-life curves (identity default) |-| Per-tier retention curves (365/180/90/30) | mcp-memory-service | **SHIPPED (parity), better default** | `[decay.half_life_days]` per tier (2.4, #807); their shape, but the omitted-key default is byte-identical to the old single-λ — no upgrade mass-evicts |+| Per-tier retention curves (365/180/90/30) | mcp-memory-service | **SHIPPED (parity), better default** | `[decay.half_life_days]` per tier (2.4, #807); their shape, but the omitted-key default is byte-identical to the old single-λ, so no upgrade mass-evicts || Extractive, zero-LLM compression | agentmemory / mcp-memory-service | **BETTER** | 2.4 tier-down (#808) keeps abstract+summary+regex keep-tokens and drops prose, but is **reversible** (git + supersession chain, `restore-page`) and off by default, not a lossy in-place rewrite || Cold-cluster dedup (DBSCAN, adaptive-eps) | mcp-memory-service | **SHIPPED (parity), better safety** | 2.4 (#812) over the bounded cold set (no O(N²)); collapses by **supersede-not-delete** (invariant #16), conservative eps ceiling, zero-LLM, off by default |-| Access-weighted retention (access boost) | mcp-memory-service | **SHIPPED (parity+), closed a real gap** | 2.4 (#798) wired reinforcement into `read_page`, the related-walk, and `explore` — every read path, not just search; throttled/async/FTS-exempt |+| Access-weighted retention (access boost) | mcp-memory-service | **SHIPPED (parity+), closed a real gap** | 2.4 (#798) wired reinforcement into `read_page`, the related-walk, and `explore`: every read path, not just search; throttled/async/FTS-exempt || Contradiction detection (0.4–0.75 band) | mcp-memory-service | **SHIPPED (parity), advisory-only** | 2.4 (#814) surfaces likely conflicts in `memory_lint` from existing embeddings; zero-LLM, never edits/deletes/persists an edge || Surprisal-first + idle/cancel dream scheduling | Honcho (Dreamer) / Supermemory | **SHIPPED (parity), opt-in** | 2.4 (#816) idle-scheduled, cancels on activity, orders most-novel-first; off by default, observable `DreamReport` per run || Git-as-snapshot | agentmemory | **BETTER** | The wiki files *are* the truth (diffable), not a `state.json` dump || Pages-over-facts / living pages | Hindsight | **PARITY** (native) | Same architecture, file-first vs their Postgres-first; `settled_first` briefing shipped |-| Cross-session experience/abstraction pass | Letta/Hindsight/surveys | **REAL, ~parity** | ≥2-session evidence guard is the genuine article — but LLM-required and **off by default** |-| Typed relation edges | graph camp | **PARTLY SHIPPED** | Link-neighbours are now a first-class retrieval surface — `memory_read_page include_related` walks the `page_links` graph outward (bounded BFS, #775) — but retrieval **RANK weighting by edge type is still not done** (edge kind stays explain-only in `memory_query`) |-| Belief-strength consolidation | Hindsight / mcp-memory-service | **SHIPPED, off by default (parity of mechanism, unproven)** | 2.4 (#815) computes a read-time, zero-LLM `confidence` over `page_evidence` (distinct-session breadth, recency, live `contradicts`, capped `[0,0.95]`), exposed inertly in `explain`/`status`; foldable into ranking authority behind a **default-0.0, R2-gated** weight. Our improvement over Hindsight's documented **entrenchment** failure: breadth-not-raw-count weighting, recency shading, a confidence cap, and **supersession always wins** regardless of evidence. Not yet default-on — no R2 delta run |+| Cross-session experience/abstraction pass | Letta/Hindsight/surveys | **REAL, ~parity** | ≥2-session evidence guard is real, but the pass is LLM-required and **off by default** |+| Typed relation edges | graph camp | **PARTLY SHIPPED** | Link-neighbours are now a first-class retrieval surface: `memory_read_page include_related` walks the `page_links` graph outward (bounded BFS, #775). Retrieval **RANK weighting by edge type is still not done** (edge kind stays explain-only in `memory_query`) |+| Belief-strength consolidation | Hindsight / mcp-memory-service | **SHIPPED, off by default (parity of mechanism, unproven)** | 2.4 (#815) computes a read-time, zero-LLM `confidence` over `page_evidence` (distinct-session breadth, recency, live `contradicts`, capped `[0,0.95]`), exposed inertly in `explain`/`status`; foldable into ranking authority behind a **default-0.0, R2-gated** weight. Our improvement over Hindsight's documented **entrenchment** failure: breadth-not-raw-count weighting, recency shading, a confidence cap, and **supersession always wins** regardless of evidence. Not yet default-on; no R2 delta run || LLM merge/rewrite "dream" pass | Hindsight (Dreamer) / Supermemory ("dreaming") | **SHIPPED, opt-in/off (parity of mechanism, unproven)** | 2.4 (#816) rewrites cold clusters into one page via the gated `apply_batch` path, `dry_run` first, JSON-schema output; **never deletes a source** (superseded with a merge-note stub, `restore-page` recovers), off by default, provider-less stores keep the zero-LLM A3 path. Off until an R2 quality delta is shown |-| bi-temporal-lite | Zep/Graphiti | **BEHIND by design** | Ingestion-time only; world-time validity deferred (honestly, because dating facts needs an LLM and breaks the zero-LLM path) |+| bi-temporal-lite | Zep/Graphiti | **BEHIND by design** | Ingestion-time only; world-time validity deferred (because dating facts needs an LLM and breaks the zero-LLM path) |## Honest gaps (consolidated) and recommended adjustments-Documented recommendations only — **nothing here is scheduled or to be+These are documented recommendations only. **Nothing here is scheduled or to beimplemented without a separate decision.** Ordered by leverage.-1. **R2 reproducible eval harness — now built (#771/#772).** It was the+1. **R2 reproducible eval harness, now built (#771/#772).** It was themeta-blocker: belief-strength ranking, typed-edge rank weighting, and apublished accuracy/latency/context-tokens *triple* were all gated on "prove itwith a number." The harness now measures that triple **and** end-to-end@@ -115,43 +113,44 @@ implemented without a separate decision.** Ordered by leverage.Illustrative sample-20 numbers are in[`benchmarks/retrieval-ab-r2.md`](benchmarks/retrieval-ab-r2.md); thepublished full-500 triple is still pending.-2. **A zero-LLM / local reranker (candle cross-encoder).** The single most-cited- weakness: our only reranker is LLM-as-judge, so the zero-LLM default path —- our headline — has *no* reranking, while basic-memory ships a local one and+2. **A zero-LLM / local reranker (candle cross-encoder).** The most-cited+ weakness: our only reranker is LLM-as-judge, so the zero-LLM default path,+ which is our headline, has *no* reranking, while basic-memory ships a local one andagentmemory/Hindsight's score lead is largely reranking (0.823 vs 0.952 same- dataset). Closes a gap on our own keyless turf. Gate on R2.-3. **Activate the dormant substrate — belief-strength now wired, off by+ dataset). This would close a gap on our own keyless turf. Gate on R2.+3. **Activate the dormant substrate: belief-strength now wired, off bydefault (2.4, #815).** `page_evidence` confidence is now computed at readtime (zero-LLM) and can be folded into `PageAuthority` behind a clamped,- **default-0.0** `[retrieval] belief_authority_weight` — the design in+ **default-0.0** `[retrieval] belief_authority_weight`, following the design in[`design-hindsight-borrowings.md`](design-hindsight-borrowings.md) §3, with- the anti-entrenchment guards baked in. It is exposed inertly in+ the anti-entrenchment guards built in. It is exposed inertly in`memory_query explain` and `memory_status` today; **it does not move rankinguntil an operator sets the weight, and turning it on is gated on a positive- R2 delta that has not been run.** Still genuinely behind: **typed-edge rank+ R2 delta that has not been run.** Still behind: **typed-edge rankweighting** (edge kind stays explain-only) and a `contradicts` *authority*- cap — A5 (#814) surfaces contradictions in `memory_lint` but does not yet+ cap; A5 (#814) surfaces contradictions in `memory_lint` but does not yetfeed rank.4. **Sharpen the cross-machine story.** `comparison.md`'s "cross-machine *by- construction*" is overstated — it's one shared server + manual git/rsync, with+ construction*" is overstated: it's one shared server + manual git/rsync, with**no automatic replication** (agentmemory ships a P2P primitive; mcp-memory-service has Cloudflare/Milvus). Either reframe as "one server, many machines"+ an explicit git/rsync note, or design a bounded `ai-memory sync` over the git- wiki (push/pull the source-of-truth dir, rebuild the index) — a cleaner,- file-first P2P story than an opaque KV LWW.-5. **Close the setup-friction gap vs the built-in.** Our one honest structural+ wiki (push/pull the source-of-truth dir, rebuild the index), which would be+ a cleaner, file-first P2P story than an opaque KV LWW.+5. **Close the setup-friction gap vs the built-in.** This is our one structuralweakness for the solo user. Much is already done (`run` auto-wire, `doctor`,`backfill`, `install-self-routing`); surface it as *the* onboarding path in theREADME hero, add a one-line `ai-memory run claude` quickstart, and ship a"coming from Claude built-in?" importer (the `~/.claude/.../memory/` format is- nearly identical markdown + `type` frontmatter — a cheap, strong on-ramp).-6. **Smaller, competitor-specific closes — five now shipped on 2.4 (opt-in,+ nearly identical markdown + `type` frontmatter, which makes it a cheap,+ strong on-ramp).+6. **Smaller, competitor-specific closes: five now shipped on 2.4 (opt-in,defaults byte-identical):** the graph-walk retrieval tool (basic-memory's`build_context`/`memory://`, LiquidLM's `follow_references`/`get_related`)shipped as `memory_read_page include_related`/`related_depth` (#775), a boundedBFS exposing the link-neighbour walk over `page_links` we already compute; the**dialectic/oracle query** (Honcho) shipped as `memory_query answer=true`- (#782) — a synthesized+cited answer over the hits, LLM-required and off by+ (#782), a synthesized+cited answer over the hits, LLM-required and off bydefault (graceful `answer_unavailable` with no provider); the **reasoning-tierknob** (Honcho) shipped as `memory_query`/`memory_explorereasoning: {minimal..max}` (#783), mapping to a per-tier token budget; the@@ -160,10 +159,10 @@ implemented without a separate decision.** Ordered by leverage.retrieval knob** shipped as `memory_query include_superseded=true` (#773) overour supersession chains. All five are strictly opt-in LLM/retrieval layers*over* the zero-LLM FTS/RRF core, never a requirement (invariant #13).- The **memory-aging** set (A1–A5, B1–B4, C1) landed on 2.4 as well —- per-tier decay curves, extractive tier-down, DBSCAN cold-cluster dedup,+ The **memory-aging** set (A1–A5, B1–B4, C1) landed on 2.4 as well+ (per-tier decay curves, extractive tier-down, DBSCAN cold-cluster dedup,the contradiction band, access reinforcement on all read paths,- belief-strength confidence, and the LLM dream pass — audited row-by-row in+ belief-strength confidence, and the LLM dream pass), audited row-by-row inthe borrowed-ideas table above; the design of record is[`design-memory-aging.md`](design-memory-aging.md).MCP tool behavior hints now ship across the 23-tool surface (title plus@@ -183,15 +182,15 @@ implemented without a separate decision.** Ordered by leverage.(now 54 / 130); `comparison.md` attributes agentmemory's `0.967` toLongMemEval-S when it's their in-house `coding-agent-life-v1` (the like-for-likeLongMemEval-S is 0.952 vs our 0.823).-8. **Fleet-scale trust governance — a real gap vs Caura (issue #810).** Our+8. **Fleet-scale trust governance: a real gap vs Caura (issue #810).** Ourmulti-user story is per-project (`pages shared, batons owned`, invariant #16)- with a root→DB-user→OIDC auth ladder and an audit log — deliberately+ with a root→DB-user→OIDC auth ladder and an audit log, and it is deliberatelyproject-scoped. Caura adds an axis we do not have: org/team/agent visibilityscopes plus **four cross-fleet trust tiers** governing read/write/delete across- hundreds of agents, with per-write PII flagging. This is genuinely off-mission- for file-first coding memory (it belongs to the org-fleet buyer), so the honest- move is to **say so, not to chase it** — but it should not be waved away as- "we already do multi-user." We do project multi-user; we do not do fleet+ hundreds of agents, with per-write PII flagging. This is off-mission+ for file-first coding memory (it belongs to the org-fleet buyer), so the right+ move is to **say so, not to chase it**. It still should not be waved away as+ "we already do multi-user": we do project multi-user, and we do not do fleetgovernance.## Bottom line@@ -199,11 +198,11 @@ implemented without a separate decision.** Ordered by leverage.- **The moat is real and verified:** zero-LLM default, files-as-truth, one binary,cross-harness capture, claim-once handoffs + messaging, and multi-usershared-within-project. On operability, data ownership, and cross-agent/team- continuity, ai-memory is genuinely ahead of every overlapping competitor.+ continuity, ai-memory is ahead of every overlapping competitor.- **The borrowed conveniences now ship (opt-in), and so does the aging set.**- The 2.4 line landed the five competitor-specific closes above — related-walk,+ The 2.4 line landed the five competitor-specific closes above (related-walk,dialectic answer, reasoning tier, pin-before-search, and the show-superseded- knob — plus the memory-aging program (per-tier decay curves, extractive+ knob) plus the memory-aging program (per-tier decay curves, extractivetier-down, DBSCAN cold-cluster dedup, contradiction flagging,access-weighted retention, belief-strength confidence, and the LLM "dream"pass), each opt-in with defaults byte-identical. Our consistent improvements@@ -214,16 +213,17 @@ implemented without a separate decision.** Ordered by leverage.or calls an LLM. The R2 harness that gates the quality work now exists andmeasures the accuracy+latency+context-tokens triple plus end-to-endQA-accuracy (illustrative sample-20 only so far).-- **The honest weakness is still retrieval quality**, and it remains+- **The real weakness is still retrieval quality**, and it remains*self-inflicted by discipline, not by copying*: no local zero-LLM rerankerexists, belief-strength (`page_evidence`) is now wired but **default-off**,typed-edge **RANK** weighting is still not built, and the published*full-dataset* triple is still pending (only illustrative sample-20 numbers sofar). No R2 delta has been run, so nothing quality-affecting defaults on. Thegate (R2) is now- open — **activate what's already there against a full-500 run.**+ open, so the next step is to **activate what's already there against a+ full-500 run.**- **Migration answer:** for the self-hosted, multi-harness, team, zero-LLM,- own-your-data coding-memory user, yes — we do the basics and add what they+ own-your-data coding-memory user, yes: we do the basics and add what theycan't get elsewhere. For app personalization, enterprise graph queries, agent- runtimes, or a solo dev content with the built-in, no — and we should keep+ runtimes, or a solo dev content with the built-in, no, and we should keepsaying so.diff --git a/docs/cookbook.md b/docs/cookbook.mdindex 4efa173b..e6c894f3 100644--- a/docs/cookbook.md+++ b/docs/cookbook.md@@ -50,11 +50,11 @@ Your agent calls `memory_write_page` and it lands as a durable wiki page (routedunder `_rules/` when it's a rule). Next session, `memory_query` surfaces it, andif the project's `.ai-memory.toml` opts into the on-start brief, rules areprepended to the agent's context automatically. To make it apply to **all** your-projects, ask for it as a standing preference — it goes to your cross-project+projects, ask for it as a standing preference. It goes to your cross-projectprofile (see the next recipe), or to the shared `_global` scope with`scope: "global"`. On a multi-userserver, writing a global rule needs root or a `write` grant on `_global`. From-another project's page, link to that standing page with `[[_global:path]]` — it+another project's page, link to that standing page with `[[_global:path]]`, whichalways names the reserved `_global` project in the default workspace. Siblingprojects use `[[project:path]]`; another workspace uses`[[workspace/project:path]]`. Bare `[[name]]` stays inside the current project.@@ -64,8 +64,8 @@ projects use `[[project:path]]`; another workspace uses> "In all my projects: use pnpm, keep integration tests in tests/suite."Your agent writes each one into the cross-project profile-(`memory_write_page` with `scope: "profile"`). From then on every project — and-every harness — gets a short "your usual choices" section at session start, and+(`memory_write_page` with `scope: "profile"`). From then on every project, in+every harness, gets a short "your usual choices" section at session start, andthe agent applies those choices whenever the repository's rules file and yousay nothing. A brand-new repository gets the whole baseline, plus a pointer to`ai-memory profile apply` for writing it into that repository's rules file.@@ -89,8 +89,8 @@ Details: [`cross-project-profile.md`](cross-project-profile.md).Two ways, depending on where the document lives:-1. **It's already a wiki page** (you saved it, or imported it — below): tell the- agent "read the `norms/gdpr-retention` page before implementing" — it calls+1. **It's already a wiki page** (you saved it, or imported it as described below): tell the+ agent "read the `norms/gdpr-retention` page before implementing" and it calls`memory_read_page` with that path and works from the full body.2. **It's an external file** (a norm/spec on disk): save it as a page first("remember this spec as `norms/gdpr-retention`", paste or point at it), then@@ -107,7 +107,7 @@ bring an existing body of documents in as project memory:document, under a stable prefix like `norms/…`. Then any project can read aspecific one before implementing (recipe above).- **A whole OKF/Obsidian vault or an export from another tool**: use the- companion importer (see [`companion-crates.md`](companion-crates.md)) — it+ companion importer (see [`companion-crates.md`](companion-crates.md)). Itingests OMC and external-conversation exports into the store. `ai-memoryexport-okf` is the inverse (export your wiki as an OKF bundle), useful to seethe exact on-disk shape your documents should take.@@ -125,7 +125,7 @@ To keep a team's shared memory reviewable next to the code it documents, usethe [`ai-memory-wikisync`](../companions/ai-memory-wikisync) companion(boundary in [`companion-crates.md`](companion-crates.md)). It exportsexplicitly allowlisted page families from the server's read-only `/api/v1`-surface into a directory in your repo — dry-run by default:+surface into a directory in your repo. It is dry-run by default:```bashai-memory-wikisync plan --server http://127.0.0.1:49374 \@@ -143,15 +143,15 @@ conflict handling are tracked in #986.## Recipe: control what gets kept, aged, or consolidated-By default nothing you have to think about: memory decays on a single gentle+By default there is nothing to think about: memory decays on a single gentlecurve, and an upgrade to 2.4 changes no scores and evicts nothing. When you *do*-want to tune aging, it is all opt-in and reversible — the original of anything+want to tune aging, it is all opt-in and reversible. The original of anythingcompacted or merged stays in git and the supersession chain, recoverable with`ai-memory restore-page`.- **Keep something forever:** pin it. A pinned page is exempt from theforget-sweep regardless of tier or age. Semantic and procedural pages never- decay either — only working/episodic memory ages.+ decay either; only working/episodic memory ages.- **Make a note expire on a deadline:** ask your agent to remember it "until<date>" (an `expires_at`); the forget-sweep deletes it when the time passes,no matter how often it was read. A TTL outranks pinning.@@ -163,7 +163,7 @@ compacted or merged stays in git and the supersession chain, recoverable withprose; `[decay] dedup_cold_clusters` collapses near-duplicate cold pages intoone survivor. Both are zero-LLM, off by default, and supersede rather thandelete.-- **Keep used memory longer:** nothing to configure — a page you open, search,+- **Keep used memory longer:** nothing to configure. A page you open, search,or reach through a related-pages walk is reinforced automatically and resistsdecay.- **Surface likely contradictions:** run `memory_lint` (through your agent or the@@ -172,7 +172,7 @@ compacted or merged stays in git and the supersession chain, recoverable withas disagreement, so a single-domain or single-language store yields mostlycandidate pairs: read each finding as a pair to check, not as a defect. Ifthat noise is too high, raise `contradiction_band_min` (`config.toml` or- `AI_MEMORY_CONTRADICTION_BAND_MIN`, default `0.4`) — on such a store the+ `AI_MEMORY_CONTRADICTION_BAND_MIN`, default `0.4`). On such a store theband measures domain proximity more than conflict, so a higher floor trimssame-domain-but-unrelated pairs.- **Let an LLM consolidate on idle ("dream"):** with a provider *and* an embedder@@ -187,7 +187,7 @@ compacted or merged stays in git and the supersession chain, recoverable within the same repo): automatic. A handoff is captured at session end and thenext session's on-start hook prepends it. Ask "where did we leave off?".- **Ask an agent in another project to do something** without loading that- project's context here: cross-project messaging — "send project-b a request to+ project's context here: use cross-project messaging. Say "send project-b a request toadd the export endpoint" (`memory_message_send`), and over there "check myinbox" (`memory_message_pop`). See [`agent-messaging.md`](agent-messaging.md).@@ -244,15 +244,15 @@ ai-memory run --yolo claude`Enter`/`y`/`yes` proceeds (the default); `n`/`no` aborts before anythinglaunches.- **The ai-jail offer.** If [ai-jail](https://github.com/akitaonrails/ai-jail)- is usable — on Linux/macOS, installed on `PATH` (or `~/.local/bin/ai-jail`),- with its sandbox backend present (`bwrap` on Linux, `sandbox-exec` on- macOS) — and you are not already inside it, a second question offers to+ is usable (on Linux/macOS, installed on `PATH` or `~/.local/bin/ai-jail`,+ with its sandbox backend present: `bwrap` on Linux, `sandbox-exec` on+ macOS) and you are not already inside it, a second question offers tore-run the session inside it. When it is not usable (or on Windows) there isno second question; the run just proceeds. Accepting re-execs the originalcommand under `ai-jail --network --agent-state --env <NAME>... --`,forwarding only the credential/configenvironment variables that are already set (server/hook URL,- `CLAUDE_CONFIG_DIR`, provider API keys, etc.) — `--network` keeps the+ `CLAUDE_CONFIG_DIR`, provider API keys, etc.). `--network` keeps theloopback ai-memory server reachable while still sandboxing the filesystem.Declining keeps the run unsandboxed (your choice, already warned).- **Choosing what the jail gets.** After you accept the offer, a checklist@@ -267,8 +267,8 @@ ai-memory run --yolo claudeas `--no-X`, so they stay off even if your global `~/.ai-jail` enables them.- **Skipping the questions.** `ai-memory run --jail claude` re-runs insideai-jail straight away, turning on those pre-marked defaults and leaving- everything else to your own ai-jail config — with or without `--yolo`, and- in scripts too; it fails rather than running unjailed if ai-jail is not+ everything else to your own ai-jail config. This works with or without+ `--yolo`, and in scripts too; it fails rather than running unjailed if ai-jail is notusable. `--jail=github,ssh,no-mise` is exact: the listed toggles (`no-X`forces one off), with every other checklist row forced off; `all` turnsevery row on and `none` turns every row off. `--no-jail` never jails and skips the@@ -284,7 +284,7 @@ ai-memory run --yolo claude`--jail=github,…`. ai-memory always passes `--no-save-config`, so a jailedrun never writes its own flags into your repository's `.ai-jail`.- **Already inside ai-jail.** Both prompts are skipped and the run proceeds- directly — `ai-jail ai-memory run … --yolo` sees no extra friction.+ directly, so `ai-jail ai-memory run … --yolo` sees no extra friction.Detection is Linux (`ai-sandbox` hostname) / macOS (`PS1` starting with`(jail) `); it fails open (shows the warning) when undetectable, neveropen to skipping it silently.@@ -298,7 +298,7 @@ ai-memory run --yolo claude**It cannot remove your own `ask` rules**: Claude Code honors explicit`permissions.ask` rules (and its built-in command-safety checks) in everymode, so a rule like `Bash(docker run *)` in `~/.claude/settings.json` still- pauses the run. For a pause-free sandbox, drop those `ask` entries — `deny`+ pauses the run. For a pause-free sandbox, drop those `ask` entries; `deny`rules block without pausing, so they can stay. Best paired with ai-jail.- **Passing extra env, e.g. a GitHub token.** `ai-memory run claude --yolo--env GH_TOKEN="$(gh auth token)"` forwards it into the jailed agent (needs@@ -402,7 +402,7 @@ ai-memory serve # run the server- **Server/homelab down**: `ai-memory run` does not need the server to start aharness. When the server is unreachable it prints one loud warning and- launches anyway — hooks keep capturing to the local spool (drained+ launches anyway. Hooks keep capturing to the local spool (drainedautomatically when the server returns), an existing MCP registrationdegrades to no-recall for the session, and the child's exit code isreturned. What you lose for that run is the workstream lease/context,@@ -434,7 +434,7 @@ ai-memory serve # run the servercounts are shown as unavailable rather than zero.- **Only *some* agents are being remembered**: run `ai-memory doctor`. It listsevery harness that has local sessions in this project and whether the server- captured them — so a harness you rotated in without installing its hook (a+ captured them. A harness you rotated in without installing its hook (asilent gap: it keeps its own local history while capturing nothing) shows upas a warning with the exact `install-hooks` command to fix it. For ClaudeCode it also reports the detected default auto-memory directory and whether@@ -450,7 +450,7 @@ ai-memory serve # run the serverbackground; you can trigger or preview it yourself with `ai-memory backfill`(`--dry-run` to see what it would import), or turn it off with`AI_MEMORY_BACKFILL_ON_START=false`.-- **A search misses something you saved**: confirm the scope — memory is+- **A search misses something you saved**: confirm the scope. Memory isper-project; a page saved in project A is not returned in project B unless itwas written to the global scope or you query with an explicit scope.- **You want an LLM feature (consolidation, digests)**: set a providerdiff --git a/docs/cross-project-profile.md b/docs/cross-project-profile.mdindex 49556371..d8bcbb35 100644--- a/docs/cross-project-profile.md+++ b/docs/cross-project-profile.md@@ -3,8 +3,8 @@ai-memory keeps knowledge per project, so switching harness costs nothing:Claude Code, Codex and OpenCode in one checkout read the same pages. The**profile** removes the other cost, switching *project*. It is a small set of-pages recording how you usually work — the package manager you reach for, how-you lay out tests, the architecture you prefer, the review workflow you follow —+pages recording how you usually work (the package manager you reach for, how+you lay out tests, the architecture you prefer, the review workflow you follow),and every project receives it at session start, through every harness.When you start a new repository and describe what you want, the agent already@@ -298,8 +298,8 @@ llm = true- `auto` (default): `global` on a single-operator server, `user` on amulti-user one.- **`min_projects`**: how many distinct projects a choice must appear in before- it joins the profile on its own (a choice you state as general — "in all my- projects" — needs only one).+ it joins the profile on its own (a choice you state as general, such as "in all my+ projects", needs only one).- **`inject_on_session_start`**: `false` keeps the digest out of session start;the profile still reaches `memory_query`.- **`digest_max_bytes`** / **`baseline_max_bytes`**: the digest budgets, indiff --git a/docs/deploy.md b/docs/deploy.mdindex 464b03e9..d5a1253b 100644--- a/docs/deploy.md+++ b/docs/deploy.md@@ -1,7 +1,7 @@# Deploying ai-memory to a homelab-This walks through the pattern documented in `bin/deploy`. The end-state is: a long-lived ai-memory container on your homelab host,+This guide follows the pattern documented in `bin/deploy`. You end up+with a long-lived ai-memory container on your homelab host,reachable on your LAN at `http://<host>:49374/mcp`, configured withyour LLM/embedding API keys, with backups handled by whatever youalready use for `/var/opt/docker/...`.@@ -30,7 +30,7 @@ stripped, and are gitignored.| `docker/.env.production.example` | `docker/.env.production` | LLM + embedding API keys |`.gitignore` excludes the live files. If you ever see one staged,-something has drifted - unstage before committing.+something has drifted; unstage it before committing.## First-time setup (one-time)@@ -107,27 +107,27 @@ middleware validates with a constant-time comparison.**Encrypted transport.** Plain HTTP on the LAN means anyone with apacket capture can read the bearer token (and native `aim_` keys oncemulti-user mode is on) in transit. Add a TLS-terminating reverse-proxy in front of ai-memory — Caddy with Let's Encrypt, Caddy with-its internal CA, Cloudflare Tunnel, nginx, or external cert files —+proxy in front of ai-memory (Caddy with Let's Encrypt, Caddy with+its internal CA, Cloudflare Tunnel, nginx, or external cert files)when you bind beyond loopback or turn on multi-user.**See [`docs/https-via-proxy.md`](https-via-proxy.md)** for the fulldeployment guide, including:-- When to add TLS and when to skip it (the loopback + stdio cases honestly don't need it).+- When to add TLS and when to skip it (the loopback + stdio cases don't need it).- Copy-paste docker compose templates in [`docker/compose.tls.caddy.yml`](../docker/compose.tls.caddy.yml) and [`docker/compose.tls.cloudflared.yml`](../docker/compose.tls.cloudflared.yml).- Per-OS trust-store install for the internal-CA path (the load-bearing manual step).- [Hosting under a subpath](https-via-proxy.md#hosting-under-a-subpath) via `--base-path` / `AI_MEMORY_BASE_PATH` when ai-memory shares a hostname with other apps.-- The explicit "what can go wrong" sections so you don't ship security theatre by accident.+- The "what can go wrong" sections, so you don't ship security theatre by accident.For the single-user-on-loopback Quick Start, the bearer token alone-remains acceptable — the token is what stops the LAN neighbour, and-loopback is what stops the packet capture. TLS earns its keep once-the deployment shape stops being "single user, single machine."+remains acceptable: the token stops the LAN neighbour, and loopback+stops the packet capture. Add TLS once the deployment is no longer+"single user, single machine."## Routine deploys-After the first-time setup, every subsequent deploy is just:+After the first-time setup, every later deploy is:```bashbin/deploy@@ -140,8 +140,8 @@ new copy + re-run `bin/deploy`.The restart step stops the running container with SIGTERM. The serverhandles SIGINT and SIGTERM on both transports and bounds each wait in-its shutdown path at five seconds, so a restart — or a plain `docker-stop` or `docker compose down` — drains and exits in a few seconds+its shutdown path at five seconds, so a restart (or a plain `docker+stop` or `docker compose down`) drains and exits in a few secondsinstead of waiting out the supervisor's grace period and ending inSIGKILL. Before those handlers existed the two deployment shapes faileddifferently. In the container the server is PID 1, and for PID 1 the@@ -149,7 +149,7 @@ kernel discards a signal whose handler is not installed, so `dockerstop` burned its full grace period and `docker kill` was the only wayout. Under the native systemd unit the server is not PID 1, so`systemctl stop` fell through to the kernel's default disposition and-killed it instantly instead — fast, but with no drain and the durable+killed it instantly instead: fast, but with no drain and the durableSessionEnd consolidation worker cut off mid-flight. There the stop isnow slower and clean. The five-second bound is fixed and notconfigurable. `docker kill` remains the way to stop the server without@@ -171,8 +171,8 @@ with the new values. No rebuild needed.## LLM provider choicesThe `.env.production.example` defaults to **Kimi 2.6 via OpenRouter**-(openai-compat transport, $0.73/$3.49 per million tokens). Reasonable-alternatives:+(openai-compat transport, $0.73/$3.49 per million tokens). Other+options:| Provider | Model | Approx. cost / consolidation | Notes ||---|---|---|---|@@ -185,7 +185,7 @@ alternatives:| openai-compat (Ollama) | `qwen3:32b` | $0 | Self-hosted. Set `AI_MEMORY_LLM_BASE_URL=http://host.docker.internal:11434/v1`. Quality depends on the model. |> **What we don't recommend:** reasoning-mode models (Kimi-K2.6 in reasoning mode,-> Claude with extended thinking, GPT-o3, Gemini "thinking" variants) — they burn+> Claude with extended thinking, GPT-o3, Gemini "thinking" variants). They burn> token budget on internal reasoning before emitting output and hang or emit empty> responses with the strict-JSON consolidation prompt. If you must use one, turn> reasoning off.@@ -243,16 +243,16 @@ and models), see [`docs/backup.md`](backup.md) and the worked example under## Sharing one server between people or harnesses-A deployed server is the supported way to share a project — between teammates,-or between several harnesses you run yourself. Two things are worth knowing+A deployed server is the supported way to share a project, whether between+teammates or between several harnesses you run yourself. Check two thingsbefore you hand out the URL.**One server per data directory.** Point two `ai-memory serve` processes at thesame `data/` (a synced folder, an NFS mount, two containers on one volume) andthey will each run their own writer and their own git handle on the wiki. SQLitesurvives it; the wiki and the in-process state do not. Run one server and let-everyone connect to it — which is also what makes the shared-knowledge model-work.+everyone connect to it, which is also what the shared-knowledge model relies+on.**Check the isolation mode.** Unscoped MCP calls resolve "current project"through a pointer that, since v1.39, is keyed per caller. The startup line says@@ -263,15 +263,14 @@ active-project isolation mode mode=PerActor …````PerActor` is the default and the one you want on a shared server. `Single` is-a single process-wide slot — fine for one harness, but concurrent sessions then-share it, and unscoped **writes** resolve through it too. See+a single process-wide slot. That is fine for one harness, but concurrent sessions+then share it, and unscoped **writes** resolve through it too. See[auto-scope.md](auto-scope.md) and [users.md](users.md#running-for-a-team).### How much load one server absorbs-Every write goes through a single writer actor — the right design for SQLite,-and the obvious question it raises is when that becomes the ceiling. Measured-rather than estimated, with+Every write goes through a single writer actor, which suits SQLite but sets a+ceiling. These figures were measured, not estimated, with`cargo test -p ai-memory-store --test writer_throughput -- --ignored --nocapture`:| concurrent writers | throughput | mean latency |@@ -281,11 +280,9 @@ rather than estimated, with| 32 | 698/s | 1.43 ms || 128 | 700/s | 1.43 ms |-Read it in two parts.-**The ceiling is ~700 writes/second**, reached around 32 concurrent writers and-flat from there — 128 writers produce the same throughput at the same latency.-Past saturation the server applies backpressure instead of degrading: the queue+flat from there: 128 writers produce the same throughput at the same latency.+Past saturation the server applies backpressure instead of degrading. The queueis bounded at 1024 with an awaiting send, so a burst larger than the queue slowsits producers down and still lands every write. Nothing is dropped, and nothinggrows without limit.@@ -296,14 +293,14 @@ which is why throughput rises 17× while per-write latency *falls*.For capacity planning: an actively working agent emits on the order of onelifecycle write per tool call. Even at a pessimistic one tool call per second-per agent, ~700/s is several hundred concurrently active agents — far beyond a-team, and beyond most shared installs. The writer is not the thing that will+per agent, ~700/s is several hundred concurrently active agents, far beyond a+team and beyond most shared installs. Something other than the writer willbreak first.Two caveats before you lean on the numbers. They were taken on a fast localdisk; because the cost is `fsync`, a network filesystem or a slow volume willbe materially lower, which is another reason to keep the data dir on local-storage. And they measure the store, not the HTTP front door — an install that+storage. They also measure the store, not the HTTP front door; an install thatsaturates this is far more likely to be limited by the agent side than bySQLite.@@ -327,25 +324,25 @@ does:ssh "$SERVER" "docker exec ai-memory /usr/local/bin/ai-memory compact --confirm"```-Compaction deletes nothing — it rebuilds the FTS indexes and `VACUUM`s.+Compaction deletes nothing. It rebuilds the FTS indexes and `VACUUM`s.### Do not schedule an unconditional nightly VACUUM-The obvious move is a nightly cron entry. Resist it:+Avoid a nightly cron entry for it:- `VACUUM` takes an **exclusive lock** and rewrites the entire database. Every- write blocks for the duration, which on a large store is minutes — and this- server's job is answering hook traffic, so blocking writes drops captures.+ write blocks for the duration, which on a large store is minutes. This+ server answers hook traffic, so blocking writes drops captures.- It needs free disk space of roughly the database's own size, so the nightlyjob also sets a permanent floor on free space.- Because SQLite reuses free pages, a store in steady use usually has almostnothing to reclaim. The nightly run pays the full cost for no benefit on mostnights.-The case that genuinely leaves a large freelist is a **one-off deletion** — a+What leaves a large freelist is a **one-off deletion**: a`purge-project`, a big retention sweep, a `forget-sweep` over months of-episodic pages. Those are events, not a schedule, and the destructive commands-already offer `--compact` inline for exactly that moment.+episodic pages. Those happen once rather than on a schedule, and the+destructive commands already offer `--compact` inline for that moment.If you do want it automated, make it **conditional** on the figure above andput it in off hours:@@ -372,8 +369,8 @@ every night.It is not erasure. The wiki git history keeps page content in its objects andcommit messages, and any backup taken earlier still holds everything. Compaction-returns bytes from the live SQLite file — worth doing on its own terms, and not-a guarantee that content is unrecoverable. See+returns bytes from the live SQLite file. That is worth doing on its own terms,+but it does not guarantee that content is unrecoverable. See[lifecycle-ops.md](lifecycle-ops.md) for the full boundary.## Rolling back@@ -424,7 +421,7 @@ ssh "$SERVER" "tail -100 $DEPLOY_DIR/data/logs/ai-memory.log.$(date +%F)"the rebuild. Scheduled embedding backfill can also fill missingrows when enabled.- **Capture looks delayed, or observations are missing**: `ai-memory- status` reports local hook-spool health — how many events are queued+ status` reports local hook-spool health: how many events are queuedclient-side, the age of the oldest one, and the total failed-deliveryattempts:@@ -440,11 +437,10 @@ ssh "$SERVER" "tail -100 $DEPLOY_DIR/data/logs/ai-memory.log.$(date +%F)"once it is reachable. `pending: 0` means capture is keeping up.The spool is **client-side**, so this section reflects the machine you- run the command on, not the server — it is the local data dir even when+ run the command on, not the server. It is the local data dir even when`AI_MEMORY_SERVER_URL` points at a homelab. It is also printed when theserver cannot be reached at all (to stderr, so `--json` consumers still- get a single object on stdout), which is precisely when a backlog is- worth seeing. `--json` carries the same numbers under a `spool` object+ get a single object on stdout), which is when a backlog matters most. `--json` carries the same numbers under a `spool` object(`pending`, `oldest_age_ms`, `retries_total`).- **Provider failures**: `ai-memory status` reports passive LLM and@@ -455,7 +451,7 @@ ssh "$SERVER" "tail -100 $DEPLOY_DIR/data/logs/ai-memory.log.$(date +%F)"TLS-inspecting firewall or antivirus, see[https-via-proxy.md](https-via-proxy.md#outbound-llm-calls-fail-behind-a-tls-inspecting-firewall).- **Container restart loop**: check- `docker logs ai-memory` - the `ai-memory starting` line at the top+ `docker logs ai-memory`. The `ai-memory starting` line at the topreports the resolved config; a missing required env var (e.g.`LLM_API_KEY` with `openai-compat` selected but no model) will failhere with a clear error.diff --git a/docs/design-boot-backfill.md b/docs/design-boot-backfill.mdindex 3c5f61f2..c6e2bbd1 100644--- a/docs/design-boot-backfill.md+++ b/docs/design-boot-backfill.md@@ -9,7 +9,7 @@ behavior and touches the trust boundary (retroactive untrusted text enters the s1. **Ingest path is B, not A.** The plan recommended path A (reuse the managed-workstreambegin → link → finish endpoints, for the incremental cursor). A live smoke proved Apopulates the *workstream continuity ledger*, not the `sessions`/`observations`/`pages`- pipeline — `observation` count stayed zero after import, so the history was not+ pipeline: `observation` count stayed zero after import, so the history was notrecall-able via `memory_query`. The implementation therefore **replays each transcriptthrough `/hook/batch`** (the same ingress live capture uses, as the companion importerdoes): `export_transcript` normalizes the native transcript, then each event is posted@@ -40,37 +40,37 @@ Surfacing the count in the next session's on-start context is a possible follow-## ProblemCapture is forward-only. The lifecycle hooks record events *from the moment they are-installed*. If you have already been working in a project for weeks — a long Claude or-Codex session on disk — and only now install ai-memory, none of that prior context is-in memory. You get a "cold start": the tool that exists to give cross-session continuity-begins with amnesia about the very session you are resuming.+installed*. If you have already been working in a project for weeks (a long Claude or+Codex session on disk) and only now install ai-memory, none of that prior context is+in memory. You get a "cold start": a tool meant to give cross-session continuity knows+nothing about the session you are resuming.The `ai-memory doctor` command (shipped alongside this proposal) makes the related gap-visible — "this harness ran here but captured nothing." This proposal fills a specific+visible: "this harness ran here but captured nothing." This proposal fills a specificinstance of it: **when a project's store is brand new (empty) and the harness is resuminga session that already has local transcript history, import that history once, so thefirst consolidated pages reflect what you actually did rather than nothing.**## What already exists (do not rebuild)-The hard part — read a native transcript, sanitize it, get it into the store — is built-twice already. This proposal is a *trigger and guards* around existing ingest, not a new-importer.+The hard part (read a native transcript, sanitize it, get it into the store) is already+built twice. This proposal adds a *trigger and guards* around existing ingest and does not+add a new importer.- **`ai-memory-workstream` transcript adapters** read every supported harness's nativesession store read-only, keyed by cwd, with per-harness path/id encoding in one place(`export_transcript`, `list_native_sessions`, `discover_native_session`). `doctor`already reuses `list_native_sessions`; boot-backfill reuses `export_transcript`.- **`export_transcript`** returns an `ExportedTranscript { native_session_id, events:- Vec<NewWorkstreamEvent>, source_cursor, losses }` — a bounded, sanitizable visible-event+ Vec<NewWorkstreamEvent>, source_cursor, losses }`: a bounded, sanitizable visible-eventledger plus an **opaque incremental cursor**. `ai-memory run` calls it after a managedchild exits and POSTs the events in size-bounded batches (`FinishManagedRunRequest`,`event_batches`) to the managed-workstream finish endpoint; the server persists`source_cursor` so the next read is incremental. This is a working backfill engine thatonly ever runs *after* a managed launch today.- **The companion importer** (`companions/ai-memory-importer`) has `ExternalConversation`- — "replay a generic external conversation through ai-memory's hook API" — with exactly- the bounding discipline this needs: `MAX_CONVERSATION_MESSAGES = 128`,+ ("replay a generic external conversation through ai-memory's hook API") with the+ bounds this needs: `MAX_CONVERSATION_MESSAGES = 128`,`MAX_USER_MESSAGE_BYTES = 16 KiB`, `MAX_CONVERSATION_TOTAL_BYTES = 1 MiB`, a dedicated`external-import` agent kind, all through the sanitizer.- **The sanitizer** (`ai-memory-hooks`, `Sanitized<NewObservation>`) is the only path from@@ -84,7 +84,7 @@ importer.- **Default on**, with a clean opt-out.- **Full project bootstrap**: when the store is empty on first boot in a project,import *all* local sessions for this cwd across every supported harness, not just the- current resumed session — hard-capped, with a one-line notice printed.+ current resumed session. The import is hard-capped and prints a one-line notice.## Design@@ -93,10 +93,10 @@ importer.The SessionStart hook already fires and already contacts the server (it fetches thehot-context/handoff block). Extend that one round-trip to also learn, cheaply:-- **Is this project's store empty?** A scoped count — the same family as doctor's+- **Is this project's store empty?** A scoped count, in the same family as doctor's`GET /admin/sessions/by-agent` for `(workspace, project)`; sum of sessions == 0 meansempty. Emptiness is the gate: an established project is never retro-imported (that would- duplicate/rewrite real history and confuse consolidation). Boot-backfill is a strictly+ duplicate/rewrite real history and confuse consolidation). Boot-backfill is strictly a**one-time bootstrap**.- **Backfill enabled?** `[capture] backfill_on_start` (default true), overridable by`AI_MEMORY_BACKFILL_ON_START` and a `.ai-memory.toml` marker key.@@ -119,7 +119,7 @@ and cwd:events, attaching to the harness-native session id so the imported session id matcheswhat forward capture would have used (Claude/Codex local id == server session id).4. Persist each session's `source_cursor` so a later real resume continues incrementally- from where the backfill stopped — no double-capture of the overlap.+ from where the backfill stopped, without double-capturing the overlap.5. Print one notice to the operator's next surface: `📼 ai-memory imported N prior localsessions (~M events) for this project. Opt out with AI_MEMORY_BACKFILL_ON_START=0.`@@ -132,11 +132,11 @@ store, explicit) for operators who want it outside the boot path.The events from `export_transcript` are `NewWorkstreamEvent`s. Two ways to land them:- **(A) Reuse the managed-workstream finish endpoint** (`FinishManagedRunRequest` +- `source_cursor`, batched by `event_batches`). Richest fit: the cursor and incremental+ `source_cursor`, batched by `event_batches`). Best fit: the cursor and incrementalsemantics already exist and the server already consolidates workstream ledgers. Cost: itis currently coupled to a managed *run* lifecycle (a `WorkstreamCheckpoint`, an- `exit_code`); backfill has no live child, so it needs a "finish without a run" entry —- a synthetic/adopted workstream for the pre-hook history.+ `exit_code`); backfill has no live child, so it needs a "finish without a run" entry,+ meaning a synthetic/adopted workstream for the pre-hook history.- **(B) Replay as sanitized hook observations** (the importer's approach). Simpler andlifecycle-free; integrates with the ordinary capture/consolidation path. Cost: needs a`NewWorkstreamEvent → NewObservation` mapping and its own idempotency (no built-in@@ -144,19 +144,19 @@ The events from `export_transcript` are `NewWorkstreamEvent`s. Two ways to land**Recommendation: (A)**, extended with a lifecycle-free "import" variant of the finishendpoint. It preserves the incremental `source_cursor` contract end to end (critical for-step 4 — the overlap between backfilled history and the resumed live session must not be+step 4: the overlap between backfilled history and the resumed live session must not becaptured twice), and reuses the server's existing workstream consolidation rather than-inventing an observation mapping. The cursor is the load-bearing reason to prefer A.+inventing an observation mapping. The cursor is the main reason to prefer A.### 4. Idempotency and overlapThree guards, all reusing existing mechanisms:-- **Emptiness gate** — only an empty store bootstraps; a populated store is never touched+- **Emptiness gate:** only an empty store bootstraps; a populated store is never touchedby the automatic path.-- **Bootstrap lease** — claim-once per project (handoff/message pattern) prevents+- **Bootstrap lease:** claim-once per project (handoff/message pattern) preventsconcurrent double-import across simultaneous boots.-- **Per-session `source_cursor`** — the imported session's cursor is persisted, so when+- **Per-session `source_cursor`:** the imported session's cursor is persisted, so whenthe operator's live resume then produces new events, forward capture continues *after*the cursor. No event is both backfilled and live-captured.@@ -175,7 +175,7 @@ Bound everything, defaults chosen to protect boot and the single-writer actor:### 6. Security-Retroactive text is exactly as untrusted as live hook text — it is old model/tool output.+Retroactive text is exactly as untrusted as live hook text, since it is old model/tool output.- **No sanitizer bypass.** Every imported record passes the same`Sanitized<NewObservation>` / workstream sanitize boundary and the same caps. The e2e@@ -190,12 +190,12 @@ Retroactive text is exactly as untrusted as live hook text — it is old model/toperator, imports only into an *empty* project scope, and is opt-outable per project viathe marker. Consider gating the automatic path to the default (loopback/single-operator)posture and requiring explicit `ai-memory backfill` on `deployment_distinguishes_operators()`- servers — an open question below.+ servers (an open question below).### 7. Opt-out and configuration- `[capture] backfill_on_start = true` (default) in config.-- `AI_MEMORY_BACKFILL_ON_START=0` env override (one config-read path — read in+- `AI_MEMORY_BACKFILL_ON_START=0` env override (one config-read path: read in`Config::load`, never ad hoc).- `.ai-memory.toml` marker key so a specific project can opt out regardless of globalconfig (mirrors how `ignore_paths` is project-scoped).@@ -204,14 +204,15 @@ Retroactive text is exactly as untrusted as live hook text — it is old model/t### 8. Harness coverageExactly the set with read-only native transcript adapters (doctor's `SCANNED_HARNESSES`).-A harness whose store is unreadable/absent contributes nothing — backfill never invents-history it cannot read, same conservative stance as doctor.+A harness whose store is unreadable/absent contributes nothing. Like doctor, backfill+never invents history it cannot read.## Relationship to `ai-memory doctor`-Complementary: **doctor detects** the coverage gap (a harness ran here but captured-nothing); **backfill fills** the specific first-boot instance of it. The docs should-cross-link them — doctor is the ongoing check, backfill is the one-time bootstrap.+The two commands complement each other. Doctor detects the coverage gap (a harness ran+here but captured nothing); backfill fills the specific first-boot instance of it. The+docs should cross-link them: doctor is the ongoing check, backfill is the one-time+bootstrap.## Testing plan@@ -225,23 +226,23 @@ cross-link them — doctor is the ongoing check, backfill is the one-time bootst- **Security**: a canary secret in a planted transcript is scrubbed; an `ignore_paths`match in a planted file-tool event is dropped.- **Multi-session**: two concurrent boots → exactly one import (lease claim-once), the- other no-ops — the invariant-#16 concurrency shape, proven at integration level.+ other no-ops. This is the invariant-#16 concurrency shape, proven at integration level.## Open questions — resolved as builtThese were the pre-implementation questions; the shipped feature (see the **As-builtnote** at the top) resolved each:-1. **Ingest path A vs B** — resolved to **B** (replay through `/hook`). A live smoke proved+1. **Ingest path A vs B:** resolved to **B** (replay through `/hook`). A live smoke provedpath A populated the workstream continuity ledger, not the searchable memory pipeline(observation count stayed zero), so it was abandoned.-2. **Shared-server default** — shipped **on by default** with `AI_MEMORY_BACKFILL_ON_START=false`+2. **Shared-server default:** shipped **on by default** with `AI_MEMORY_BACKFILL_ON_START=false`/ `--no`-style opt-out; the emptiness gate makes it safe on any posture (it only everbootstraps an empty project).-3. **Notice delivery** — the automatic path runs detached and silent (like Claude Code's+3. **Notice delivery:** the automatic path runs detached and silent (like Claude Code'sown auto-memory); the summary shows on a manual `ai-memory backfill`. Surfacing it inthe next session's on-start context remains a possible follow-up.-4. **Consolidation quality** — shipped **behind the hard cap** (newest 25 sessions / 50k+4. **Consolidation quality:** shipped **behind the hard cap** (newest 25 sessions / 50kevents) and iterating; a dedicated eval remains a follow-up.## Semverdiff --git a/docs/design-cross-project-profile.md b/docs/design-cross-project-profile.mdindex 2af1c056..7e22456e 100644--- a/docs/design-cross-project-profile.md+++ b/docs/design-cross-project-profile.md@@ -18,7 +18,7 @@ reaches the agent only when a `memory_query` happens to match it, and isdeliberately kept out of the SessionStart brief. `docs/design-rules-promotion.md`defers cross-project sharing, and RFC #1000 asks for exactly that.-The **profile** is the missing piece: a small, curated, cross-project record of+The **profile** fills that gap. It is a small, curated, cross-project record ofhow this user usually works, built from evidence, delivered to every projectand every harness, and used as the default whenever nothing more specific saysotherwise.diff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex 68df96fc..2207b959 100644--- a/docs/design-decisions.md+++ b/docs/design-decisions.md@@ -11,7 +11,7 @@A self-contained Rust binary that:1. Runs as an **MCP server** (stdio + HTTP/SSE) for coding-agent CLIs (Claude Code, OpenAI Codex, Cursor, Gemini CLI, Antigravity CLI, OpenClaw, OpenCode, OMP, and MCP-capable clients).-2. Captures sanitized, bounded lifecycle observations **automatically** - no `write_note` ceremony - via hook scripts or generated extensions that agent CLIs invoke. User prompts and post-compaction summaries retain at most 16 KiB; notifications and tool excerpts retain at most 2 KB; every sanitized durable body has a 16 KiB backstop. Optional `ai-memory run` workstreams additionally read visible native transcript tails through host-side, read-only adapters.+2. Captures sanitized, bounded lifecycle observations **automatically** (no `write_note` ceremony) via hook scripts or generated extensions that agent CLIs invoke. User prompts and post-compaction summaries retain at most 16 KiB; notifications and tool excerpts retain at most 2 KB; every sanitized durable body has a 16 KiB backstop. Optional `ai-memory run` workstreams additionally read visible native transcript tails through host-side, read-only adapters.3. Maintains a **Karpathy-style wiki**: incrementally-compiled markdown pages with cross-links, supersession, an `index.md` and a `log.md`.4. Serves retrieval via the MCP `tools/list` to coding agents: a handful of *narrow* tools, not 50.5. Ships a **Docker image** (`docker run -v ai-memory-data:/data -p 49374:49374 ai-memory`) so it can move between desktop and homelab.@@ -23,11 +23,11 @@ A self-contained Rust binary that:- Cargo-format clean.- Docker-deployable, easy backup, easy move desktop↔homelab.- MCP server for coding agents.-- **Automatic** memory capture/fetch - minimal manual tool invocations.+- **Automatic** memory capture/fetch, with minimal manual tool invocations.- Differentiates **short-term** vs **long-term** memory temporally (like agentmemory).- Self-healing memory management.- Helps with handoffs between agent CLIs (resume from Codex where Claude Code left off).-- Iteratively planned - each feature working before the next starts. No dead code.+- Iteratively planned: each feature works before the next starts. No dead code.## 3. Storage model - the biggest architectural decision@@ -39,12 +39,12 @@ Three options surveyed:| **B. Markdown-in-git** primary | Files in repo | Derived index | Diff-able, grep-able, portable, Karpathy-faithful | Watcher correctness (basic-memory #580/#758/#798), inode races (#765), startup cost || **C. DB-primary with on-demand export** | SQLite | Everything | Best of both | Two formats to keep coherent; user must remember to export |-**Decision: Option B - markdown in a git repo is source of truth, SQLite is derived index.**+**Decision: Option B. Markdown in a git repo is the source of truth, and SQLite is a derived index.****Why:**-- Backup/move story is trivial - `git clone` or `rsync` a directory. The user explicitly asked for this.+- Backup/move is trivial: `git clone` or `rsync` a directory. The user explicitly asked for this.- Karpathy's pattern *is* the wiki on disk. Faking it with an export step loses the inspect-in-Obsidian property.-- DB is rebuildable from files - corruption is recoverable.+- DB is rebuildable from files, so corruption is recoverable.- Cross-tool compatibility for free: any agent that reads `~/.ai-memory/wiki/*.md` works without an MCP integration.**How we avoid basic-memory's watcher pain:**@@ -78,12 +78,12 @@ Why not LanceDB/Qdrant/Kuzu/CozoDB/SurrealDB?- SurrealDB: heavy, multi-mode storage; we'd inherit a lot of surface we don't need.- Packed vectors in SQLite keep v1 dependency-light; `sqlite-vec` remains the scale-up path once brute-force cosine stops being enough.-**The graph is just SQL tables.** A `wiki_pages` table, a `wiki_links (from_id, to_id, link_type)` table, optional `wiki_concepts (page_id, concept)`. Graph queries are recursive CTEs in SQLite. Petgraph in-memory for batch traversals. Avoids the entire "embedded graph DB" footgun cognee fell into.+**The graph is just SQL tables.** A `wiki_pages` table, a `wiki_links (from_id, to_id, link_type)` table, optional `wiki_concepts (page_id, concept)`. Graph queries are recursive CTEs in SQLite. Petgraph in-memory for batch traversals. This avoids the "embedded graph DB" footgun cognee fell into.**Crates** (research-backed picks):- `rusqlite` for embedded SQLite access. `bundled-sqlcipher` if we want encryption later.- `refinery` for SQL migrations.-- `tantivy` *not* used initially - sqlite FTS5 is sufficient at the corpus sizes we expect (hundreds to low-thousands of pages per project). Revisit only if FTS5 ranking proves inadequate.+- `tantivy` *not* used initially; sqlite FTS5 is sufficient at the corpus sizes we expect (hundreds to low-thousands of pages per project). Revisit only if FTS5 ranking proves inadequate.- `petgraph` for in-memory graph algorithms during consolidation.## 5. Embedding & LLM@@ -98,14 +98,14 @@ Why not LanceDB/Qdrant/Kuzu/CozoDB/SurrealDB?- **Off by default**, behaves like agentmemory after #138's fix. Without a provider, the system still works: synthetic compression (rule-based), no LLM-generated summaries, no `memory_consolidate` page-rewrite.- With a provider, LLM consolidation runs on PreCompact, on demand via `memory_consolidate`, and at session end only when `AI_MEMORY_CONSOLIDATE_ON_SESSION_END=true` (off by default). A substantive session end always writes a rule-based summary page + handoff regardless, except that a session page the agent wrote itself through `memory_write_page` with the session's id (`consolidated_by: agent`) is kept in place of the summary and skipped by the SessionEnd worker; a session containing only `SessionStart` / `SessionEnd` boundaries closes without either artifact or provider work and releases any startup handoff bound to that receiver. SessionEnd provider work is persisted by observation generation and consumed outside the hook request by one bounded retrying worker, so client drain cancellation cannot lose it. The automatic handoff and completed-end watermark commit in one SQLite transaction; an already-ended keyed replay converges the remaining wiki commit, provider enqueue, and ingest-key completion. The completed end also stores the observation count it covered; a resumed session re-enters the end path only after that count advances, avoiding non-convergent wall-clock comparisons. Optional 6h maintenance timer.- Providers implement `LlmProvider { complete(...); complete_structured(...) }`. The current provider and authentication matrix lives in [`ARCHITECTURE.md`](ARCHITECTURE.md); this design boundary also covers OpenAI-compatible endpoints such as Ollama, vLLM, and LM Studio.-- **Native HTTP per provider** - no LiteLLM-equivalent. The cognee tracker (#2412/#2430/#2537/#2608/#2749/#2782/#2840/#2842) showed silent-kwarg-drop in a generic gateway is the #1 source of provider bugs. Each provider's typed JSON, errors on unknown fields. Hand-coded but correct.+- **Native HTTP per provider**, no LiteLLM-equivalent. The cognee tracker (#2412/#2430/#2537/#2608/#2749/#2782/#2840/#2842) showed silent-kwarg-drop in a generic gateway is the #1 source of provider bugs. Each provider gets typed JSON that errors on unknown fields. It is hand-coded, but correct.- **Structured output via JSON schema, not XML, not Instructor-style wrapping.** Use each provider's native JSON-mode where available; for Anthropic, request a tool-use response with a typed schema. Validate with `serde_json` + `schemars`-derived schemas.## 6. Capture model - auto, never `write_note`Three capture surfaces, in priority order:-1. **Lifecycle hooks/extensions.** The current clients are listed in the README support matrix. These are fast, reliable, structured. We ship hook scripts or generated TypeScript integrations the user installs once. Lessons from agentmemory:+1. **Lifecycle hooks/extensions.** The current clients are listed in the README support matrix. These are fast, reliable, and structured. We ship hook scripts or generated TypeScript integrations the user installs once. Lessons from agentmemory:- Hooks must be **fire-and-forget** (#221). No `await fetch()` blocking session start.- Sub-second hard timeouts on the writer side (`tokio::time::timeout`).- All hooks → single HTTP/Unix-socket POST → server queues → returns 202@@ -114,7 +114,7 @@ Three capture surfaces, in priority order:2. **Managed-workstream transcript import** (opt-in through `ai-memory run`). Each supported adapter reads its linked native session after a managed launch and appends portable visible events to the shared ledger. ai-memory does not ship a universal background watcher over private harness stores.-3. **Manual MCP tool** (`memory_write_page`) - only for explicit durable project knowledge from the user ("remember this"). Routine session capture remains automatic.+3. **Manual MCP tool** (`memory_write_page`), only for explicit durable project knowledge from the user ("remember this"). Routine session capture remains automatic.### Capture-policy boundary (#194)@@ -138,7 +138,7 @@ Adopt agentmemory's tier model **but** keep the surface narrow:|---|---|---|---|| **Working** | Current session: last N observations, last user prompt, current files | Until session end | Drop on session end (kept in DB for forensics, but excluded from default recall) || **Episodic** | Per-session summaries with concept tags, files-touched, decisions made | 30 days hot, 180 days cold, then evict if cold-score < threshold | `salience · exp(-λ · age_days) + σ · log(1 + access_count) · exp(-μ · days_since_access)`. Code of record: [`crates/ai-memory-store/src/decay.rs`](../crates/ai-memory-store/src/decay.rs). |-| **Semantic** | Distilled facts/preferences/architecture notes - the wiki pages themselves | Indefinite, supersedeable | Versioned in place: old `is_latest=false`, new `supersedes=old_id` |+| **Semantic** | Distilled facts/preferences/architecture notes: the wiki pages themselves | Indefinite, supersedeable | Versioned in place: old `is_latest=false`, new `supersedes=old_id` || **Procedural** | Repeated patterns extracted from episodic clusters (`pattern` type with frequency ≥ 2) | Indefinite | Frequency-decay if not re-observed in N days |**Implementation note:** the four tiers map to one `pages` table with a `tier` enum column + an `observations` table for bounded working/episodic projections, not four separate tables. Keeps schema migrations sane.@@ -264,7 +264,7 @@ not authorize an unscoped write. Any future schema simplification may improvethe explicit/static path, but must preserve the session-aware path unless aseparate major-version decision replaces its UX and concurrency guarantees.-**Install-time `project_strategy` default (#128).** `basename(cwd)` remains the fallback for a checkout without a valid remote, but an agent shell that `cd`s into a subdirectory and stays there can otherwise fork the rest of the session into a phantom project named after the subdir. The #1033 default now names remote-backed repositories from normalized `upstream`, then `origin`, before this strategy applies. A `.ai-memory.toml` marker with `project_strategy = "repo-root"` fixes the remote-less case (#16, #23, #111) but needs a marker in (or above) every repo; a runtime env-var fallback that the *user* sets was deliberately rejected in #16. `install-hooks --project-strategy repo-root` instead **bakes** the strategy into the generated hook command (and the OpenCode / OMP / OpenClaw plugins) at install time — the same status as the already-baked `AI_MEMORY_AUTH_TOKEN` / `AI_MEMORY_HOOK_URL` / `--data-dir`, not a user runtime override. This is a client/install-time-only change: the server already parses `project_strategy=repo-root`. A marker's explicit `project` or `identity` and operator-home routing still win; an unpinned marker `project_strategy` changes only the no-valid-remote fallback.+**Install-time `project_strategy` default (#128).** `basename(cwd)` remains the fallback for a checkout without a valid remote, but an agent shell that `cd`s into a subdirectory and stays there can otherwise fork the rest of the session into a phantom project named after the subdir. The #1033 default now names remote-backed repositories from normalized `upstream`, then `origin`, before this strategy applies. A `.ai-memory.toml` marker with `project_strategy = "repo-root"` fixes the remote-less case (#16, #23, #111) but needs a marker in (or above) every repo; a runtime env-var fallback that the *user* sets was deliberately rejected in #16. `install-hooks --project-strategy repo-root` instead **bakes** the strategy into the generated hook command (and the OpenCode / OMP / OpenClaw plugins) at install time. That gives it the same status as the already-baked `AI_MEMORY_AUTH_TOKEN` / `AI_MEMORY_HOOK_URL` / `--data-dir`, not a user runtime override. This is a client/install-time-only change: the server already parses `project_strategy=repo-root`. A marker's explicit `project` or `identity` and operator-home routing still win; an unpinned marker `project_strategy` changes only the no-valid-remote fallback.## 12. Operability@@ -294,7 +294,7 @@ historical decision boundary rather than a current support matrix.- No alternative graph DB (SQL recursive CTEs only).- No multimodal (text only).- No general "skills" / slash-command bundle in v1 (agentmemory plugin format). The narrow exception is the managed ai-memory Agent Skills that package routing guidance for agents; hooks + MCP remain the product surface.-- No LongMemEval-style benchmark harness in v1 - add in v0.4.+- No LongMemEval-style benchmark harness in v1; add in v0.4.## 14. Mistakes-to-avoid checklist (from issue research)@@ -318,7 +318,7 @@ Top-line rules carved into the codebase:16. No `lru_cache` on configs (cognee #2228/#2853).17. Datasets/projects are query-time filters, not orchestration-mode-conditional (cognee #2867).18. LLM has off by default; opt-in via env (agentmemory #138/#143).-19. `cargo deny` for transitive license audits (cognee #2807 - FastEmbed removed for license).+19. `cargo deny` for transitive license audits (cognee #2807: FastEmbed removed for license).20. Pin upstream native deps; ship a lockfile (agentmemory #555/#540).## 15. Managed workstreams use a portable ledger, not native format conversiondiff --git a/docs/design-handoff-offer-not-claim.md b/docs/design-handoff-offer-not-claim.mdindex 090010ac..5fcd583c 100644--- a/docs/design-handoff-offer-not-claim.md+++ b/docs/design-handoff-offer-not-claim.md@@ -10,14 +10,14 @@ managed-run continuity packet, the compiled brief, and the inbox notice; if theneed resurfaces, the safe shape is a server-side `handoff=off` parameter thatclaims nothing and delivers everything else. `to_agent` targeting (option 3) isnot needed once nothing is claimed automatically. The-maintainer marked #959 design-first: it touches the single-claim contract (invariant #16 — a handoff+maintainer marked #959 design-first: it touches the single-claim contract (invariant #16: a handoffis claimed exactly once by two independent `state='open'` guards) in several-places at once, so this is the design pass requested before any code lands.+places at once, so this design pass was requested before any code lands.## ProblemA pending handoff is claimed by whichever session starts next in the-project — any harness, any purpose, interactive or not. The claim is+project, whatever its harness or purpose, interactive or not. The claim issingle-use and cannot be undone. In practice the baton rarely reaches thesession it was meant for:@@ -30,11 +30,11 @@ session it was meant for:Observed on 2.4.1 (`433a19f3`): a Claude Code session left an automatichandoff at 13:53:04Z; an interactive Codex session opened at 14:17:07Z for anunrelated task consumed it, and a later `memory_handoff_cancel` on it-returned `cancelled: false, state: accepted` — already gone. A follow-up+returned `cancelled: false, state: accepted`, because it was already gone. A follow-upreport narrowed part of the original complaint to a self-inflicted cause(calling `memory_handoff_begin` at the end of every session created a*manual*, project-wide handoff, which `is_handoff_candidate` always prefers-over a directory-matched automatic one — working as documented, just not as+over a directory-matched automatic one; that works as documented, just not asexpected), but the remaining ask stood: the automatic claim at session starthas no opt-out, and `to_agent` is stored but never used to target delivery.@@ -43,10 +43,10 @@ has no opt-out, and `to_agent` is stored but never used to target delivery.- **Claim site**: `fetch_and_accept_handoff_at` in `crates/ai-memory-hooks/src/router.rs`(~line 1355). Every `SessionStart` (and every `opencode run` /`ai-memory run` launch) calls this. It resolves the project, looks up- `latest_open_handoff` (owner-filtered — `OwnerFilter::User`/`Unattributed`,+ `latest_open_handoff` (owner-filtered by `OwnerFilter::User`/`Unattributed`,so a shared server does not leak one operator's baton to another's- session), renders it to markdown, then — inside the same admission-chain- pass that notifies webhooks — claims it. A refused or timed-out admission+ session), renders it to markdown, then claims it inside the same admission-chain+ pass that notifies webhooks. A refused or timed-out admissionchain cancels only the claim, leaving the handoff open; the content isstill served either way (comment at ~line 1440 explains why: "thesession-start claim is how most handoffs are consumed, so a webhook must@@ -57,7 +57,7 @@ has no opt-out, and `to_agent` is stored but never used to target delivery.`memory_handoff_begin`) is project-wide and always wins over an automaticone. An automatic (`SessionEnd`) handoff is scoped by cwd path-boundary.Owner is checked first, before the manual short-circuit, so cross-operator- mixing is already excluded — this proposal only touches same-operator,+ mixing is already excluded. This proposal only touches same-operator,same-project delivery. `startup_handoff` (`reader.rs`) also already skips abaton whose source session is still live (`LIVE_BATON_QUIET_PERIOD`, 10minutes, `router.rs`), so a session started next to a running one does not@@ -68,37 +68,37 @@ has no opt-out, and `to_agent` is stored but never used to target delivery.batons do not pile up; only manual ones stay open until accepted orcancelled.- **`to_agent`**: a column exists on the handoff row (`ai-memory-store`), is- threaded through `row_to_agent_message`-adjacent plumbing, and is written- — always as `None`. `memory_handoff_begin`'s args+ threaded through `row_to_agent_message`-adjacent plumbing, and is written,+ always as `None`. `memory_handoff_begin`'s args(`crates/ai-memory-mcp/src/server.rs` ~line 1188, `HandoffBeginArgs`) do not- accept it at all. Selection never reads it. It is dead weight today.+ accept it at all. Selection never reads it, so today it does nothing.- **Per-execution opt-out**: none exists for handoff delivery specifically.The closest precedent is `--no-autowire` / `AI_MEMORY_RUN_AUTOWIRE=false`(`crates/ai-memory-cli/src/cli.rs` ~line 312) for a different concern(harness hook/MCP autowiring on `ai-memory run`), and the generatedOpenCode plugin's `fetchHandoff` call(`crates/ai-memory-cli/src/commands/install_hooks.rs`, four call sites:- ~3464, ~4139/4249, ~4879/4915) has no guard of any kind — every+ ~3464, ~4139/4249, ~4879/4915) has no guard of any kind: every`experimental.chat.system.transform` fetches and risks consuming thehandoff.-- **A working non-consuming precedent already exists**, for a different+- A working non-consuming precedent already exists for a differentresource: the inbox notice (V64), `render_inbox_notice` in `router.rs`(~line 1572), wired in at ~line 1557. It is appended to the same- session-start context as the handoff, additive and non-destructive —- `memory_message_pop` is what actually consumes a message, the notice just+ session-start context as the handoff, additive and non-destructive:+ `memory_message_pop` is what actually consumes a message, and the notice onlysays a count is waiting. Its own doc comment is explicit about why:**"this carries ONLY a static integer count — never any message-controlledtext (no subject, no sender string) — so a hostile message cannot injecttext into the on-start context."** This is the precedent the maintainerpointed at ("inject a non-consuming notice... like the existing inboxnotice"), and it comes with a security constraint this proposal has to- reconcile, not just imitate the shape of (see Open questions, below).+ reconcile as well as imitate (see Open questions, below).## Proposed model-Three independent, additive pieces. Options 2 and 3 stand alone; option 1 is-the one that actually fixes the reported problem and is where most of the-design risk lives.+Three independent, additive pieces. Options 2 and 3 stand alone. Option 1+fixes the reported problem and carries most of the+design risk.### 1. Offer, don't claim (config-gated, default unchanged)@@ -115,14 +115,14 @@ claim_on_session_start = true # default: unchanged behaviorper-project `.ai-memory.toml` override remains a possible follow-up for teamsthat need different behavior per repository.-When `true` (default — **no behavior change for existing installs**),+When `true` (the default, so existing installs see no behavior change),`fetch_and_accept_handoff_at` claims exactly as it does today.When `false`, the same function stops short of the admission-chain claim and-instead renders a **notice**, following the inbox-notice pattern:+instead renders a notice, following the inbox-notice pattern:non-consuming, appended to the same session-start context, and claimed lateronly through `memory_handoff_accept` (which already exists and already does-almost this exact lookup — this proposal does not add a second tool).+almost this exact lookup; this proposal does not add a second tool).```📬 ai-memory: a pending handoff `<id>` from `<from_agent>`, left `<age>` ago.@@ -136,10 +136,10 @@ notice is stale (both `state='open'` guards still decide).**Managed-run ledger.** Today the managed-run context claim commits in thesame transaction as the handoff claim. In offer mode the ledger/context claim-still happens at session start — only the single-use handoff slot becomes an-offer — so a managed run does not lose its continuity packet.+still happens at session start. Only the single-use handoff slot becomes an+offer, so a managed run does not lose its continuity packet.-The brief and managed-run context (`managed_md`) are unaffected either way —+The brief and managed-run context (`managed_md`) are unaffected either way;only the single-use handoff slot's own claim becomes conditional.### 2. Per-execution opt-out (additive, no schema change)@@ -150,7 +150,7 @@ handoff:- the native `ai-memory hook` path (same place `capture_policy` alreadyreads its own env knobs);- the POSIX/PowerShell hook bundles (`hooks/<agent>/session-start.sh` and- `.ps1` — mirrors the native check so a non-native install gets the same+ `.ps1`, mirroring the native check so a non-native install gets the sameopt-out);- the four generated TypeScript `fetchHandoff` call sites in`install_hooks.rs`, which today call it unconditionally;@@ -158,8 +158,8 @@ handoff:launches that would rather pass a flag than set an env var.This covers automation and probes without touching `claim_on_session_start`,-and composes with it: an opted-out execution sees **no** claim and **no**-notice (see Open questions — this is the one place option 1 and option 2+and composes with it: an opted-out execution sees no claim and no+notice (see Open questions; this is the one place option 1 and option 2interact).### 3. Make `to_agent` load-bearing@@ -169,7 +169,7 @@ interact).- `is_handoff_candidate` gains one more condition: a handoff with`to_agent = Some(x)` is not a candidate for a session whose own agent kindis not `x`. Order relative to the existing owner check and the- manual-beats-automatic short-circuit matters — see Open questions.+ manual-beats-automatic short-circuit matters; see Open questions.- Selection (`prefer_handoff`) is otherwise unchanged: `to_agent` filters thecandidate set, it does not introduce a new ranking dimension.- An explicit `memory_handoff_accept` with an exact `handoff_id` ignores@@ -186,8 +186,8 @@ interact).notice is, by construction, something the receiving agent cannot chooseto skip the way it can choose not to call `memory_handoff_accept`). Ahandoff's summary is written by whatever agent or operator ended the- prior session — same trust level as a cross-project message. **Leaning- toward metadata-only** (id, `from_agent`, age — no summary text), matching+ prior session, the same trust level as a cross-project message. The proposal+ leans toward metadata-only (id, `from_agent`, age, no summary text), matchingthe inbox notice's own bar exactly, with the full summary available (asuntrusted content to weigh, same framing the inbox notice uses formessages) only after an explicit `memory_handoff_accept`. This is a@@ -195,7 +195,7 @@ interact).confirmed, not assumed.2. **Interaction between the opt-out and `claim_on_session_start = false`**:should `AI_MEMORY_HANDOFF=off` suppress the *notice* too, or only the- claim? Proposed: suppress both — an automated probe that does not want to+ claim? Proposed: suppress both. An automated probe that does not want toconsume a handoff almost certainly does not want to spend context on anotice about one either, and this keeps the opt-out a single on/offswitch instead of three states.@@ -204,14 +204,14 @@ interact).candidate, e.g. an untargeted automatic handoff for that cwd), or does amismatch block delivery entirely until the right agent shows up? Proposed:invisible-and-fall-through, consistent with "candidates" already being a- filtered set before `prefer_handoff` ranks them — a targeted handoff- simply removes itself from another agent's candidate list rather than+ filtered set before `prefer_handoff` ranks them. A targeted handoff+ removes itself from another agent's candidate list rather thanoccupying the slot.4. **Existing deployed OpenCode plugins**: regenerating the opt-out supportrequires `install-hooks --apply` same as any other hook-shape change(already the documented path for e.g. `--capture-assistant`). Worth anexplicit callout in the eventual changelog since this one is silent- otherwise — an un-regenerated plugin simply keeps claiming unconditionally+ otherwise: an un-regenerated plugin keeps claiming unconditionallyforever, which is not a crash, just a no-op upgrade.5. **A handoff nobody ever explicitly accepts**: with `claim_on_session_start= false`, does an un-accepted handoff expire on its own? Partly answered:@@ -223,12 +223,12 @@ interact).## Non-goals (v1)- No change to the owner-filter / cross-operator isolation already in place.-- No new MCP tool — `memory_handoff_accept` already does the claim; this+- No new MCP tool. `memory_handoff_accept` already does the claim; thisonly changes whether session start does it automatically first.- No change to `memory_handoff_begin`'s existing manual-beats-automaticprecedence rule, beyond adding `to_agent` as an orthogonal filter.- No retroactive handling for handoffs already in flight when an install- upgrades — the config default keeps today's behavior, so nothing changes+ upgrades; the config default keeps today's behavior, so nothing changesuntil an operator opts in.## Verification plan (when approved)@@ -237,7 +237,7 @@ interact).candidates, both for an otherwise-eligible automatic and an otherwise-always-winning manual handoff.- Unit: `render_handoff_notice` (new, mirroring- `inbox_notice_is_count_only_and_empty_at_zero`) — metadata-only, `None`+ `inbox_notice_is_count_only_and_empty_at_zero`): metadata-only, `None`when there is no pending handoff, never contains the stored summary text(a direct string-search assertion against a planted hostile summary, thesame shape of test that would catch a regression into carryingdiff --git a/docs/design-hindsight-borrowings.md b/docs/design-hindsight-borrowings.mdindex c92ab6a0..f9259b72 100644--- a/docs/design-hindsight-borrowings.md+++ b/docs/design-hindsight-borrowings.md@@ -8,33 +8,32 @@ default-behavior-unchanged. Shipped: **P1** typed redaction labelsbriefing (default off); **P5** the no-API-key subscription docs. The**eval-gated activations remain deferred behind the R2 harness** (which does notyet exist): P2's confidence→authority factor and P3's typed-edge rank weighting /-`contradicts` cap are NOT wired into ranking — the data and explanations land,+`contradicts` cap are NOT wired into ranking: the data and explanations land, andthe default-rank flips wait for a number. Targets the `release/2.2` line-(2.2.x — every item here is additive). Derived from+(2.2.x; every item here is additive). Derived from[`research-hindsight.md`](research-hindsight.md) §11 ("Strengths worthborrowing") and the landscape recommendations R3/R5 in[`research-2026-landscape.md`](research-2026-landscape.md). Extends, and isconsistent with, [`design-page-ingestion-windows.md`](design-page-ingestion-windows.md)(which already flagged two of these as follow-ups) and `docs/temporal.md`.-Nothing here implies re-architecture; the whole point of the Hindsight study-was that a paper-backed competitor converged on our substrate. This plan turns+Nothing here implies re-architecture; the main finding of the Hindsight study was that a paper-backed competitor converged on our substrate. This plan turnsthe four borrowable ideas into bounded, independently-shippable phases.*## 0. First, what already exists (so we do not rebuild it)The Hindsight analysis named five borrowables. Grounding them against the code-on `release/2.2`, **three are already partly or wholly built** — the honest-starting point:+on `release/2.2`, **three are already partly or wholly built**, and that is+where this plan starts:| Borrowable (research-hindsight §11) | Current state on release/2.2 | Gap this plan fills ||---|---|---|-| Bi-temporal / "recall June" | **Shipped.** `entity_page_links` windows (V56/V58) + page windows (V62, `valid_from`/`valid_to`) + `as_of` FTS (`reader.rs:1968`). | none — R4 done, out of scope here |-| Continuously-rewritten "mental models" (cross-session reflect loop) | **Mostly shipped.** `experience.rs::run_experience_review` reviews the last N session pages and rewrites procedures/rules/preferences; wired into the scheduler tick (`auto_improve_schedule.rs:190-251`), cadence-gated (`experience_pass_due`, `min_new_sessions`), state in `V57`. | **P4** — standing-answer semantics + boot surfacing + belief strength |-| Belief-strength / evidence-count consolidation | **Absent.** Pages carry `salience` (feedback, V37) and `importance` on observations (1..10), but **no evidence/proof/confidence** on a page or belief. `confidence`/`evidence_json` exist only on auto-improve *proposal* tables. | **P2** — the genuinely new mechanism |-| Typed causal-edge *retrieval* | **Data exists, retrieval ignores it.** `Relation{Causes,Fixes,Contradicts}` (`page.rs:208`) persists as `links.link_type` rows (`ops.rs:1052`); lint reads `contradiction_edges` (`reader.rs:6247`). But `graph_neighbors_for_project_explained` (`reader.rs:4165`) joins `links` with **no `link_type` filter** — one-hop neighbour expansion, no `fixes`/`causes` traversal, no `contradicts` in rank. | **P3** — the `design-page-ingestion-windows.md` §8 follow-up |-| Typed redaction labels (`[REDACTED:<kind>]`) | **Absent.** `sanitize.rs` replaces every match with the single constant `"[REDACTED]"` (`scrub()` :229) from a flat `BUILTIN_PATTERN_STRS` (:51). | **P1** — small clarity refinement |+| Bi-temporal / "recall June" | **Shipped.** `entity_page_links` windows (V56/V58) + page windows (V62, `valid_from`/`valid_to`) + `as_of` FTS (`reader.rs:1968`). | none (R4 done, out of scope here) |+| Continuously-rewritten "mental models" (cross-session reflect loop) | **Mostly shipped.** `experience.rs::run_experience_review` reviews the last N session pages and rewrites procedures/rules/preferences; wired into the scheduler tick (`auto_improve_schedule.rs:190-251`), cadence-gated (`experience_pass_due`, `min_new_sessions`), state in `V57`. | **P4**: standing-answer semantics + boot surfacing + belief strength |+| Belief-strength / evidence-count consolidation | **Absent.** Pages carry `salience` (feedback, V37) and `importance` on observations (1..10), but **no evidence/proof/confidence** on a page or belief. `confidence`/`evidence_json` exist only on auto-improve *proposal* tables. | **P2**: the new mechanism |+| Typed causal-edge *retrieval* | **Data exists, retrieval ignores it.** `Relation{Causes,Fixes,Contradicts}` (`page.rs:208`) persists as `links.link_type` rows (`ops.rs:1052`); lint reads `contradiction_edges` (`reader.rs:6247`). But `graph_neighbors_for_project_explained` (`reader.rs:4165`) joins `links` with **no `link_type` filter**: one-hop neighbour expansion, no `fixes`/`causes` traversal, no `contradicts` in rank. | **P3**: the `design-page-ingestion-windows.md` §8 follow-up |+| Typed redaction labels (`[REDACTED:<kind>]`) | **Absent.** `sanitize.rs` replaces every match with the single constant `"[REDACTED]"` (`scrub()` :229) from a flat `BUILTIN_PATTERN_STRS` (:51). | **P1**: small clarity refinement |-So the plan is: **one small clarity fix (P1), one genuinely-new mechanism+So the plan is: **one small clarity fix (P1), one new mechanism(P2), one already-planned retrieval follow-up (P3), one extension of anexisting subsystem (P4), and a positioning doc (P5).** Bi-temporal (R4) needsnothing.@@ -53,7 +52,7 @@ Restated from `AGENTS.md` because they bound each design below:a `V63__*.sql` refinery step behind the pre-migration archive, plus the pinbump at `api_credentials.rs:414` (currently `62`).- **MCP tool count is frozen at 23** (enforced by `MCP_TOOL_NAMES` and the- registered-router test in `server.rs`). None of these phases needs a *new* tool — they extend+ registered-router test in `server.rs`). None of these phases needs a *new* tool; they extendexisting surfaces (`memory_query` explain, `memory_status`, `memory_lint`,the scheduler). If P2 ever warranted a dedicated tool, that is a separatedecision with the count bump and both prompt-surface updates.@@ -64,18 +63,18 @@ Restated from `AGENTS.md` because they bound each design below:**Borrow:** Hindsight's Memory Defense redacts to a *typed* marker(`[REDACTED:github_token]`) so a later reader knows *what kind* of secret was-present without leaking it — strictly more useful than an anonymous mask.+present without leaking it, which is strictly more useful than an anonymous mask.**Design.**- Change `BUILTIN_PATTERN_STRS: &[&str]` (`sanitize.rs:51-148`) to- `&[(&str, &str)]` (pattern, label) — e.g. `("gh[pousr]_…", "github_token")`,+ `&[(&str, &str)]` (pattern, label), e.g. `("gh[pousr]_…", "github_token")`,`("AKIA|ASIA…", "aws_key")`, `("eyJ[…]", "jwt")`.- Change `SanitizerInner.patterns: Vec<Regex>` (:156) to`Vec<(Regex, &'static str)>`; `scrub()` (:219-235) formats`format!("[REDACTED:{label}]")` instead of the constant at :229. Operator`extra_patterns` (SanitizeConfig, :173) default to label `custom`.- **Backward-compat / output-change note (this is why it is a minor, not a- silent patch):** the sanitized string is *durable* — it is stored in pages+ silent patch):** the sanitized string is *durable*: it is stored in pagesand observations. Old rows keep `[REDACTED]`; new writes get`[REDACTED:<kind>]`. That is acceptable (both are non-secrets), but it is avisible format change, so it ships in a minor with a CHANGELOG note, not@@ -87,15 +86,14 @@ present without leaking it — strictly more useful than an anonymous mask.no-false-positive tests are unaffected. Add one test per label asserting theright `kind`.-**Cost:** small, no migration, single file + tests. **Risk:** low (trust-boundary #6 is preserved — still the only path from untrusted text to store,-still fail-safe: an unknown/`extra` pattern falls back to label `custom`, never+**Cost:** small, no migration, single file + tests. **Risk:** low (trust boundary #6 is preserved: it is still the only path from untrusted text to+store, and still fail-safe, since an unknown/`extra` pattern falls back to label `custom`, neverto leaking).## 3. P2 — Belief-strength / evidence-count on pages (the new mechanism)-**Borrow:** Hindsight observations are *evidence-backed beliefs* — quotes plus a-**proof count** — and "new information strengthens, weakens or extends an+**Borrow:** Hindsight observations are *evidence-backed beliefs* (quotes plus a+**proof count**), and "new information strengthens, weakens or extends anexisting belief instead of silently replacing it." We supersede (a versionchain); we do not track *how much evidence* stands behind the current version.@@ -103,7 +101,7 @@ chain); we do not track *how much evidence* stands behind the current version.the latest page; it should be a page with N supporting sightings, where asingle contradicting sighting *weakens* rather than instantly *replaces* it.That belief strength is exactly the missing input to (a) ranking authority and-(b) the `contradicts` lint — and it is the substrate the deferred Phase-B+(b) the `contradicts` lint. It is also the substrate the deferred Phase-B`confidence` in `design-page-ingestion-windows.md` §7 was gesturing at, nowwith a zero-LLM way to populate it.@@ -114,7 +112,7 @@ with a zero-LLM way to populate it.created_at)`, unique on `(page_id, source_kind, source_id)`. Written **in thesame transaction** as the page upsert (consolidator's `write_page`/`apply_batch` path, `consolidator.rs:199/564`) from the sessions/observations- that produced the page. Purely rule-based — no LLM — so the zero-LLM path+ that produced the page. Purely rule-based (no LLM), so the zero-LLM pathpopulates it. This is the "proof count" analogue; keeping the source ids(not just an integer) lets a later reader see *what* supports a belief andlets recency-weighting work (below).@@ -125,34 +123,33 @@ with a zero-LLM way to populate it.supporting sessions ⇒ higher; an unresolved `contradicts` edge (from`contradiction_edges`, `reader.rs:6247`) ⇒ lower.- **Feed it into ranking through the existing `PageAuthority`** (`reader.rs:209`)- as one more bounded factor, clamped inside the current `[0.55, 1.50]` — never- a new multiplier tower. Report it in `SearchExplain` (`reader.rs:547`) as+ as one more bounded factor, clamped inside the current `[0.55, 1.50]`, never a new multiplier tower. Report it in `SearchExplain` (`reader.rs:547`) as`confidence` + `evidence_count` alongside `authority`, so it is inspectablevia `memory_query(explain=true)` and never a black box. Surface the count in`memory_status` too.- **Strengthen / weaken / extend semantics:**- - *Strengthen* — reconsolidating the same path from a new session appends a+ - *Strengthen*: reconsolidating the same path from a new session appends a`reconsolidation`/`session` evidence row (count rises). Already the shape ofthe supersede path; P2 just records the source.- - *Weaken* — an unresolved `contradicts` edge landing lowers derived+ - *Weaken*: an unresolved `contradicts` edge landing lowers derivedconfidence (no write; it is a read-time input).- - *Extend* — unchanged supersession (the body grows/changes); P2 does not+ - *Extend*: unchanged supersession (the body grows/changes); P2 does notalter versioning.- **The entrenchment failure mode** (flagged in `research-hindsight.md` §5): apopular-but-wrong belief could outvote a correct correction. Mitigationsbaked into `f`: recency-weight evidence (newest sightings count more), and- **a supersession always wins regardless of count** — a human/agent correction+ **a supersession always wins regardless of count**: a human/agent correctionreplaces the version; evidence count only shades *ranking*, never gates*whether* a correction takes. Confidence influences rank; it never blocks awrite. That keeps invariant #16's "a divergent write supersedes, neverdestroys" intact.-**Cost:** medium — one backup-gated migration (V63 + pin bump), one write-path+**Cost:** medium: one backup-gated migration (V63 + pin bump), one write-pathhook (transactional evidence insert), one read-time derivation + explain field,retention interaction (evidence rows cascade on page purge like links).**Risk:** medium; gate behind an eval (does confidence-in-authority improveretrieval on the R2 harness, or just add noise?) before it touches default-ranking — same discipline `design-page-ingestion-windows.md` §7 applied to+ranking, the same discipline `design-page-ingestion-windows.md` §7 applied tofreshness. Ship the *table + count + explain field* first (inert to ranking),turn on the authority factor only with a number behind it.@@ -172,9 +169,8 @@ entity/temporal/**causal** links, not just neighbour expansion. Our typed edgesto a bug/decision query than an incidental wikilink).- **Bounded `fixes`/`causes` chain traversal.** Optionally follow `fixes` oneextra hop (bug → fix → the fix's own page), strictly depth-capped (≤2) and- behind the same `[retrieval]` opt-in gate style as `abstract_vectors` — so the- default fan-out stays bounded (invariant: no unbounded graph walks).-- **`contradicts` into rank** — the explicit follow-up named in+ behind the same `[retrieval]` opt-in gate style as `abstract_vectors`, so the default fan-out stays bounded (invariant: no unbounded graph walks).+- **`contradicts` into rank**: the explicit follow-up named in`design-page-ingestion-windows.md` §8 ("typed contradicts edges enteringrank: natural follow-up once page windows exist"). A page on the unresolvedside of a `contradicts` edge takes an authority cap (like the existing@@ -183,9 +179,9 @@ entity/temporal/**causal** links, not just neighbour expansion. Our typed edgesdirectly with P2's confidence (a contradiction weakens both rank andconfidence).-**Cost:** small-medium — no migration (edges exist), changes localized to the-graph-stream builder + `PageAuthority` + `GraphVia`/explain. **Risk:** low-medium-— keep the chain traversal opt-in and depth-capped; prove the typed-edge rank+**Cost:** small-medium: no migration (edges exist), changes localized to the+graph-stream builder + `PageAuthority` + `GraphVia`/explain. **Risk:** low-medium;+keep the chain traversal opt-in and depth-capped; prove the typed-edge rankweighting on the R2 harness before making it default (same baseline-before-changerule).@@ -194,26 +190,26 @@ rule).**Borrow:** Hindsight's top tier is a markdown page of *settled* knowledge anagent "boots" from instead of rediscovering context each session.-**Honest scope.** We already have the reflect loop: `experience.rs::+**Scope.** We already have the reflect loop: `experience.rs::run_experience_review` reviews the last N session pages across a project andrewrites procedures/rules/preferences (`EXPERIENCE_SYSTEM_PROMPT`), cadence-gatedin the scheduler tick. The two deltas vs Hindsight's mental models are:1. **Standing-answer semantics.** Give the experience pass an explicit outputlane: a small set of durable, per-project "what we've settled on" pages (a- `PageKind`/tier already exists — `rule`/`decision` carry the highest+ `PageKind`/tier already exists: `rule`/`decision` carry the highest`PageAuthority`; reuse them, do not invent a tier). The pass *maintains* theserather than creating new episodic pages, and P2's evidence count is whatmakes "settled" measurable (a rule with many supporting sessions is settled;a one-off is not).2. **Boot surfacing.** `memory_briefing` (an existing tool, no new surface) is- the "boot from a page of settled knowledge" seam — bias it to lead with the+ the "boot from a page of settled knowledge" seam: bias it to lead with thehigh-confidence standing-answer pages (P2 feeds this) so a new session openswith settled knowledge first, exactly Hindsight's "page of settled knowledgeinstead of rediscovering it every session."**Cost:** medium, but mostly prompt + selection + briefing wiring on top of an-existing subsystem — no new scheduler, no new subsystem. Depends on P2 for the+existing subsystem, with no new scheduler and no new subsystem. Depends on P2 for the"settled" signal. **Risk:** medium; the experience pass is LLM-opt-in and staysso (zero-LLM installs keep session pages + briefing without the abstractionlane). Guard against the pass churning the standing pages every tick (the@@ -223,7 +219,7 @@ existing cadence gate + "only rewrite when evidence changed" covers this).**Borrow:** Hindsight advertises no-API-key onboarding via ChatGPT Plus / ClaudePro / Copilot subscriptions. We already support Copilot and Anthropic-OAuth-tokens — this is a **docs/positioning** change, not code: promote "use your+tokens, so this is a **docs/positioning** change, not code: promote "use yourexisting Claude Pro / Copilot subscription, no API key" to a first-class line in`docs/install.md` and the provider setup, and confirm the OAuth/Copilot paths area one-liner in `install-mcp`/config. **Cost:** trivial (docs). **Risk:** none.@@ -233,55 +229,54 @@ Include it so the study's onboarding insight is not lost.Smallest-first, each a standalone 2.2.x PR:-1. **P1** (typed redaction labels) — no deps, no migration. Immediate.-2. **P3** (typed-edge retrieval + `contradicts` rank) — no migration; the+1. **P1** (typed redaction labels): no deps, no migration. Immediate.+2. **P3** (typed-edge retrieval + `contradicts` rank): no migration; thealready-planned §8 follow-up. Prove the rank weighting on R2 before default.-3. **P2** (evidence table + count + explain, inert to rank) — V63 migration;+3. **P2** (evidence table + count + explain, inert to rank): V63 migration;ship the count + `explain`/`status` surfacing first, authority factor behindan eval.-4. **P4** (standing-answer lane + briefing bias) — depends on P2's "settled"+4. **P4** (standing-answer lane + briefing bias): depends on P2's "settled"signal; extends `experience.rs`.-5. **P5** (subscription onboarding docs) — any time; trivial.+5. **P5** (subscription onboarding docs): any time; trivial.R2 (the reproducible LongMemEval harness, `research-2026-landscape.md` R2) is the-prerequisite for turning P2's authority factor and P3's rank weighting *on by-default* — both are gated "table/stream first, ranking change only with a number."+prerequisite for turning P2's authority factor and P3's rank weighting *on by default*; both are gated "table/stream first, ranking change only with a number."That keeps us out of the mempalace trap the research flagged.## 8. Explicitly NOT borrowing (from research-hindsight.md §12)-- **LLM-required capture** — we own the zero-LLM segment; P2's counts and P1 are+- **LLM-required capture**: we own the zero-LLM segment; P2's counts and P1 arerule-based, P4 stays opt-in. Do not follow Hindsight into provider-mandatorywrites.-- **Postgres / enterprise substrate** — single self-contained binary stays the+- **Postgres / enterprise substrate**: single self-contained binary stays thehomelab differentiator.-- **Strict bank isolation** — that is issue #708 (per-project authorization),+- **Strict bank isolation**: that is issue #708 (per-project authorization),tracked separately; the design there layers a boundary *above* ourshared-within-project model (invariant #16), it does not replace sharing withHindsight-style isolation. #709 (project identity) is its prerequisite.-- **Disposition traits** (skepticism/literalism/empathy) — unproven+- **Disposition traits** (skepticism/literalism/empathy): unprovenmetaphor-as-architecture until an ablation says otherwise; not planned.## 9. Open questions (for maintainer input before any coding)-1. **P1 output change** — is a durable move from `[REDACTED]` to+1. **P1 output change**: is a durable move from `[REDACTED]` to`[REDACTED:<kind>]` wanted at all, given it changes stored text and touchesthe #6 trust boundary? (Alternative: keep `[REDACTED]` and add the kind only- in a structured sidecar — but that loses the in-body readability that is the- whole point.)-2. **P2 confidence placement** — derived-at-read (this plan's recommendation, no+ in a structured sidecar, but that loses the in-body readability that is the+ main point.)+2. **P2 confidence placement**: derived-at-read (this plan's recommendation, nohot-path write, single source of truth in `page_evidence`) vs amaterialized `pages.confidence` column (cheaper reads, but a mutable scalar tokeep honest and a second write on every access)? The V62 doc chosematerialized for symmetry; here the read-derived option avoids a hot-pathwrite, which is the opposite tradeoff and worth a call.-3. **P2 grain** — evidence on *pages* (this plan) vs on the typed *edges*/+3. **P2 grain**: evidence on *pages* (this plan) vs on the typed *edges*/entity-links (closer to Hindsight's per-belief proof count, but a biggerchange)? Pages are the unit our ranking already authority-weights, which iswhy this plan starts there.-4. **P3 default vs opt-in** — should typed-edge rank weighting be on by default+4. **P3 default vs opt-in**: should typed-edge rank weighting be on by defaultonce eval-proven, or a `[retrieval]` opt-in like `abstract_vectors`?-5. **P4** — is a distinct standing-answer surfacing in `memory_briefing`+5. **P4**: is a distinct standing-answer surfacing in `memory_briefing`desirable, or does biasing by P2 confidence within the existing briefingsuffice without a visible new lane?diff --git a/docs/design-memory-aging.md b/docs/design-memory-aging.mdindex 56f49822..15c57686 100644--- a/docs/design-memory-aging.md+++ b/docs/design-memory-aging.md@@ -35,7 +35,7 @@ with defaults `DecayParams` (`decay.rs:35-46`): `λ=0.02` (≈35-day half-life),(`retention_score_with_breadth`, `decay.rs:94-120`) is`1 + breadth_weight·ln(1+ max(distinct_actors,1)−1)`, identity at`breadth_weight=0.0` (the default) so enabling the per-actor table changes no-score until an operator turns the weight up — there is no eviction cliff to+score until an operator turns the weight up; there is no eviction cliff tomigrate around. Salience is clamped to `[0.25, 2.0]` in steps of `0.25`(`SALIENCE_MIN/MAX/STEP`, `decay.rs:126-130`); `salience_after_feedback`(`decay.rs:141-154`) steps on `Helpful`/`NotHelpful` and drops straight to the@@ -65,10 +65,10 @@ single-writer actor (`spawn_access_bump`, `server.rs:5237`, `tokio::spawn` →sanctioned read-path-write pattern and it already honors invariants #2/#3/#13/#16.It is wired into **`memory_query`** (`server.rs:2463`, plus the raw-observation-fallback at `2545`) and **`memory_recent`** (`server.rs:2715`) — and nowhere+fallback at `2545`) and **`memory_recent`** (`server.rs:2715`), and nowhereelse. It is **not** wired into `memory_read_page` (`server.rs:3612`), therelated-walk it performs (`related_walk`, `server.rs:3688`, over `page_links`),-or `memory_explore` (`server.rs:4701`). **That is the gap** the user is asking+or `memory_explore` (`server.rs:4701`). That is the gap the user is askingabout: a page a human opens directly, or one the graph walk surfaces, earns noreinforcement today. (Bucket C1.)@@ -84,7 +84,7 @@ a page evicted this run keeps its raw capture. Tiers are `working` / `episodic`/ `semantic` / `procedural` (V01); **semantic and procedural never decay**("semantic compounds"), and **pinned pages are exempt** regardless of tier.Eviction is destructive-through-the-wiki-layer, so it goes through supersession-and git — the loser stays reachable until hard-delete.+and git, and the loser stays reachable until hard-delete.### Dormant substrate (exists on disk, ranking-inert today)@@ -92,7 +92,7 @@ and git — the loser stays reachable until hard-delete.frontmatter): a page body is separable from a short abstract; the`abstract_vectors` retrieval stream is **off by default**.- **`page_evidence`** (V63, `source_kind` including `reconsolidation`) and- **`salience`** (V37): both persisted, both **ranking-inert** — they move the+ **`salience`** (V37): both persisted, both **ranking-inert**: they move thesweep, not the results. See `competitive-parity.md` and`design-hindsight-borrowings.md`: belief-strength was designed and deferredbehind R2, not shipped into rank.@@ -101,11 +101,11 @@ and git — the loser stays reachable until hard-delete.- `experience.rs` (`apply_eval_gate` at `:195` → `apply_batch`): the existingcross-session LLM pass that turns observations into pages under the eval gate.-- `curator.rs` (`:147`): already emits a **`cold_episodic`** finding list —- literally a prediction of what the sweep would evict, i.e. a ready-made work+- `curator.rs` (`:147`): already emits a **`cold_episodic`** finding list:+ a prediction of what the sweep would evict, which makes it a ready-made workqueue for a compression/merge pass.- `Wiki::write_page` / `Wiki::apply_batch`: the only sanctioned wiki mutation- path (supersession, admission, attribution, git, index) — invariant.+ path (supersession, admission, attribution, git, index); this is an invariant.- `auto_improve.rs`: the approval-gated learning loop.### Invariants that constrain everything below@@ -114,7 +114,7 @@ Any read-path write stays on the sanctioned async/throttled/FTS-exempt path(invariant #2 single-writer no-N+1, #3 no index-after-return). The system mustkeep working with **no LLM provider** (#13). Multi-session/multi-usercorrectness (#16) means access reinforcement, merges, and supersession must not-become per-operator read filters — `page_access` is per-actor for *breadth*, not+become per-operator read filters: `page_access` is per-actor for *breadth*, notfor *visibility*.---@@ -141,12 +141,12 @@ are vendor claims, not our measurements. Sources:Takeaways that shape the design: (1) type-dependent retention is the near-universalnext step past a single λ (mcp-memory-service, Letta, OpenViking); (2) extractive,-zero-LLM compression is a shipped default elsewhere (agentmemory, mcp-memory-service)-— we can do it without a provider; (3) DBSCAN with adaptive eps is the standard+zero-LLM compression is a shipped default elsewhere (agentmemory, mcp-memory-service),+so we can do it without a provider; (3) DBSCAN with adaptive eps is the standardcold-cluster dedup; (4) the dream-pass consensus is **event+idle withcancel-on-activity** and **surprisal-first** ordering; (5) the documented failure-mode of belief-strength is **entrenchment** (raw proof-count wins) — Hindsight's own-warning, which our B1 must design against.+mode of belief-strength is **entrenchment** (raw proof-count wins). That is Hindsight's own+warning, and our B1 must design against it.---@@ -167,7 +167,7 @@ Everything in A works with no provider and does not require ranking changes.- *Mechanism:* extend `DecayParams` with an optional `half_lives:HashMap<Tier, f64>` (and optionally by kind) resolved once at `Config::load()`;`retention_score_*` takes the per-page λ from the lookup, falling back to the- scalar `lambda`. **No new column** — tier already lives on every page (V01);+ scalar `lambda`. **No new column**: tier already lives on every page (V01);kind is already in frontmatter. Default map = current behavior (all tiers λ=0.02),so byte-identical scores until an operator sets curves.- *Invariants:* pure-function change; #13 intact; identity default preserves #16@@ -187,7 +187,7 @@ Everything in A works with no provider and does not require ranking changes.eviction because the durable facts survive.- *Mechanism:* a new sweep pass, before the decay-eviction pass, that rewrites thepage through `Wiki::write_page`/`apply_batch` (supersession + git preserve the- original — **reversible**: the full body stays in the version chain and git+ original, so it is **reversible**: the full body stays in the version chain and githistory). Regex keep-token miner lives beside the sanitizer's patterns. Needs a**`tier_state`/`compacted` marker** (frontmatter flag + a `pages` column, V65) sothe sweep and `curator.rs` distinguish a *deliberately short* page from a *cold*@@ -241,7 +241,7 @@ Everything in A works with no provider and does not require ranking changes.finding. Timestamp resolution only *flags*, never auto-deletes.- *Schema delta:* reuse `page_evidence`/edge tables; add a `contradicts` edge kindif not present (V66 if needed).-- *Invariants:* #13; lint stays advisory (#16 — a contradiction is not a delete).+- *Invariants:* #13; lint stays advisory (#16: a contradiction is not a delete).- *R2 bar:* none for detection; if the edge later feeds *rank* (per`design-hindsight-borrowings.md` §4) that step is R2-gated separately.- *Failure modes:* false-positive band → advisory-only output; the operator/lint@@ -257,7 +257,7 @@ All of B is off by default and touches either ranking or LLM; each gates on R2.- *Why:* the substrate exists and is inert (`competitive-parity.md`); Hindsightshows proof-count is a real signal.- *Mechanism:* exactly the design in- [`design-hindsight-borrowings.md`](design-hindsight-borrowings.md) §3 — a+ [`design-hindsight-borrowings.md`](design-hindsight-borrowings.md) §3: abounded multiplier weighted by **distinct actors and recency, not raw count**,with a confidence cap. This is the anti-entrenchment guard (Hindsight'sdocumented failure mode).@@ -266,8 +266,8 @@ All of B is off by default and touches either ranking or LLM; each gates on R2.breadth weighting keeps #16 (a team's page outranks one loud operator's).- *R2 bar:* prove a triple/QA delta on R2 before default; ships behind a configflag until then.-- *Failure modes:* **belief entrenchment** — a wrong page with many proofs pins- itself → distinct-actor + recency weighting and the confidence cap; `Stale`/`Wrong`+- *Failure modes:* **belief entrenchment** (a wrong page with many proofs pins+ itself) → distinct-actor + recency weighting and the confidence cap; `Stale`/`Wrong`feedback still floors salience.**B2. Cross-session LLM merge/rewrite of cold clusters.**@@ -280,7 +280,7 @@ All of B is off by default and touches either ranking or LLM; each gates on R2.- *Invariants:* #7 (structured output), #16 (never delete a source), #13 (onlyruns when a provider is configured; the zero-LLM path is A3).- *R2 bar:* merged corpus must beat the pre-merge corpus on R2 before default-on.-- *Failure modes:* **hallucinated merge** — invents a fact not in any source →+- *Failure modes:* **hallucinated merge** (it invents a fact not in any source) →never delete the source, `dry_run`, R2 gate, and `page_evidence` records whichsources fed the merge.@@ -293,13 +293,13 @@ All of B is off by default and touches either ranking or LLM; each gates on R2.token dropped on new activity. No unbounded fan-out (#5 spirit).- *Invariants:* #2 (all writes via the actor), #5 (bounded, cancellable).- *R2 bar:* scheduling is mechanism, not quality; it inherits B1/B2's gate.-- *Failure modes:* **silent-window bug** — a pass runs and quietly corrupts →+- *Failure modes:* **silent-window bug** (a pass runs and quietly corrupts) →every run emits an observable `SweepReport`-style outcome (pages touched, merged,superseded) so a bad run is visible, not silent.**B4. Surprisal-first ordering.**- *What:* order the dream pass's work queue by surprisal (novelty) first.-- *Why:* Honcho's finding — the most informative consolidation is on the most+- *Why:* Honcho found that the most informative consolidation is on the mostsurprising material.- *Mechanism:* proxy surprisal = embedding distance to the nearest existing page(already have embeddings); order the `cold_episodic`/cluster queue by it.@@ -313,16 +313,16 @@ All of B is off by default and touches either ranking or LLM; each gates on R2.**C1. Close the read-path reinforcement gap.**- *What:* wire `spawn_access_bump` into `memory_read_page` (`server.rs:3612`), therelated-walk (`related_walk`, `server.rs:3688`), and `memory_explore`- (`server.rs:4701`) — the three read paths that reinforce nothing today.+ (`server.rs:4701`), the three read paths that reinforce nothing today.- *Why:* a page a human opens directly, or one the graph surfaces, is *used* andshould resist decay exactly as a search hit does.-- *Mechanism:* reuse the exact sanctioned path — `spawn_access_bump(ids, actor)`,+- *Mechanism:* reuse the exact sanctioned path: `spawn_access_bump(ids, actor)`,async, throttled by `ACCESS_BUMP_COOLDOWN`, FTS-exempt. For the related-walk,bump the walked pages (not just the seed), keyed per operator.- *Schema delta:* none (V03/V43 exist).- *Invariants:* #2/#3 (already honored by the pattern), #13 (no LLM), #16(per-actor breadth is attribution, not a read filter).-- *R2 bar:* none — this is reinforcement input, not a ranking change; but a recall+- *R2 bar:* none, because this is reinforcement input, not a ranking change; but a recallspot-check that reinforced pages survive a sweep they'd otherwise fail.- *Failure modes:* read-amplification (a walk of 50 pages bumps 50) → the 60sper-(page,operator) throttle already bounds it; cap walk-bump breadth if needed.@@ -333,7 +333,7 @@ All of B is off by default and touches either ranking or LLM; each gates on R2.if not directly hit often.- *Mechanism:* fold a bounded degree term into the retention formula (a secondbreadth-like factor), computed from `page_links` at sweep time (not on the hot- read path — sweep already does a batch pass).+ read path; sweep already does a batch pass).- *Schema delta:* none (`page_links` exists); degree computed in the sweep.- *Invariants:* #2 (sweep-time batch, no hot-path N+1); default weight 0 →identity, no eviction cliff (#16).@@ -363,7 +363,7 @@ All of B is off by default and touches either ranking or LLM; each gates on R2.| V66 *(only if needed)* | `contradicts` edge kind, if not already expressible | A5 || — | none | A1, A3-merge-provenance (reuse `page_evidence`), A4, B1-B4 (reuse V37/V61/V63), C1-C3 (reuse V03/V43/`page_links`) |-Most of the design ships **without new columns** — the substrate (V37 salience,+Most of the design ships **without new columns**: the substrate (V37 salience,V43 per-actor access, V61 abstracts, V63 evidence, `page_links`) already existsand is under-used. The only firm new column is A2's compaction marker.@@ -376,29 +376,29 @@ ships **opt-in / off-by-default** and does not default on until the **R2 harness(now built, #771/#772; `crates/ai-memory-consolidate/tests/recall_eval.rs`) provesa triple/QA delta.-**Phase 1 — cheap, zero-LLM, safe (no ranking change):**-- **PR: C1 access reinforcement on all read paths** — wire `spawn_access_bump`+**Phase 1: cheap, zero-LLM, safe (no ranking change):**+- **PR: C1 access reinforcement on all read paths**: wire `spawn_access_bump`into `memory_read_page`, the related-walk, and `memory_explore` on the existingthrottled async single-writer path. Tests: reinforced page survives a sweep it'dotherwise fail; throttle honored; multi-actor breadth recorded.-- **PR: A1 type/tier retention curves** — config-driven per-`(tier,kind)`+- **PR: A1 type/tier retention curves**: config-driven per-`(tier,kind)`half-lives, identity default. Tests: default map = byte-identical scores;table-driven per-tier eviction.-**Phase 2 — zero-LLM depth:**-- **PR: A2 extractive tier-down** (+ V65 marker) — compact cold episodic instead+**Phase 2: zero-LLM depth:**+- **PR: A2 extractive tier-down** (+ V65 marker): compact cold episodic insteadof evict; reversibility test (restore from supersession); no re-compaction.-- **PR: A3 + A4 cold-cluster dedup + entropy pre-filter** — DBSCAN adaptive-eps+- **PR: A3 + A4 cold-cluster dedup + entropy pre-filter**: DBSCAN adaptive-epsover the `cold_episodic` set; supersede-not-delete; entropy gate. Tests:no O(N²), conservative-eps, recall preserved via survivor.-- **PR: A5 zero-LLM contradiction edges** — 0.4–0.75 band → `contradicts` edge →+- **PR: A5 zero-LLM contradiction edges**: 0.4–0.75 band → `contradicts` edge →`memory_lint` finding, timestamp resolution advisory only.-**Phase 3 — LLM dream pass (opt-in, R2-proven):**-- **PR: B1 belief-strength activation** — clamped authority factor+**Phase 3: LLM dream pass (opt-in, R2-proven):**+- **PR: B1 belief-strength activation**: clamped authority factor(distinct-actor + recency weighted, confidence cap), per`design-hindsight-borrowings.md` §3; behind a flag until an R2 number.-- **PR: B2 + B3 + B4 dream pass** — cold-cluster LLM rewrite through+- **PR: B2 + B3 + B4 dream pass**: cold-cluster LLM rewrite through`experience.rs`/`apply_eval_gate`/`apply_batch` (`dry_run`, sources keptreachable) + event/idle scheduling with cancel-on-activity + surprisal-firstordering. Off by default; each run emits an observable outcome report.@@ -415,14 +415,14 @@ progressive-disclosure work in §R7 (which A2's L0/L1/L2 tier-down feeds).## Migration & upgrade safety (existing stores must not break or lose data)An upgrade to a 2.4 that ships any of this must open a large, already-migrated-store cleanly, keep every index consistent, and lose nothing — the bar the+store cleanly, keep every index consistent, and lose nothing, the same bar theV62/#776 rollout was held to. This section makes the guarantees explicit, perphase, and encodes the lessons from that incident.### 1. Migrations are additive DDL only; backfills are inert / idempotent / resumable / WAL-boundedNew migrations start at **V65** and are additive. A2's `compacted_at` is an-`ADD COLUMN` (nullable) — instant, no table rewrite, no lock on a large store.+`ADD COLUMN` (nullable): instant, no table rewrite, no lock on a large store.No shipped migration's SQL is ever edited in place: doing so trips refinery'sdivergence check, which is exactly why `migrations.rs:33-34` sets`set_abort_divergent(false)` (a hash mismatch on an already-applied migration is@@ -431,45 +431,45 @@ fails closed). Any change to a shipped migration must preserve thatdivergence-tolerance handling.**Any data backfill runs on the boot path, not inside the migration-transaction** — chunked, resumable, and WAL-checkpointed, mirroring the #776+transaction**: chunked, resumable, and WAL-checkpointed, mirroring the #776precedent for V62: `backfill_page_windows` / `backfill_page_windows_in_batches`(`ops.rs:861`, `:867`), which commits in bounded batches(`PAGE_WINDOW_BACKFILL_BATCH`, `ops.rs:824`) and checkpoints the WAL after eachso it never accumulates unbounded WAL on a huge store, and resumes from a cursorif interrupted (`ops.rs:830-839`). A backfill is a **fast no-op** on a store thatdoesn't need it (no rows match the predicate). A2 is the only phase here that-touches page bodies, and it does so lazily through the sweep — there is no+touches page bodies, and it does so lazily through the sweep; there is noone-shot body backfill; the marker column is populated as the sweep compacts, notin a boot migration.### 2. No behavior change surprises an existing user on upgrade-- **A1 type/tier retention curves — defaults reproduce current behavior.** The+- **A1 type/tier retention curves: defaults reproduce current behavior.** Thedefault `half_lives` map is a single ~35-day curve for every tier, byte-identicalto today's scalar `λ=0.02` (`decay.rs:38`). An upgrade therefore does **not**mass-evict episodic memory on the first post-upgrade forget-sweep. Moreaggressive per-tier curves are strictly opt-in via `[decay]` config. (Episodiceviction is already the recoverable cold→tombstone→180-day-grace path, and- pinned/semantic/procedural are exempt — but the explicit rule stands regardless:+ pinned/semantic/procedural are exempt, but the explicit rule stands regardless:no upgrade mass-evicts.)-- **A2 extractive tier-down — reversible and non-destructive.** The full body+- **A2 extractive tier-down: reversible and non-destructive.** The full bodystays in git history and in the supersession chain, so the pre-compactionversion is reachable (invariant #16, loser stays reachable; `restore-page`recovers it). Only episodic pages compact, never pinned/semantic/procedural. The`compacted_at` marker (V65) distinguishes a deliberately-short page from a coldone so the sweep never double-processes or re-compacts. Tier-down is opt-in/gated.-- **A3 cold-cluster dedup + A5 contradiction edges — annotate, never destroy.**+- **A3 cold-cluster dedup + A5 contradiction edges: annotate, never destroy.**A3 collapses via supersession (the merged-away duplicates stay reachable), nevera hard delete of a source; A5 only writes an edge and a lint finding(timestamp resolution is advisory). Both use conservative thresholds and areopt-in.-- **B1 belief-strength → ranking — off by default.** This is the one bucket that+- **B1 belief-strength → ranking: off by default.** This is the one bucket thatchanges *retrieval ranking*, so it is OFF by default and gated on an R2 numberbefore it may default on. An existing user sees no ranking change until they opt in.-- **B2 dream rewrite/merge — never deletes a source.** Originals live in git and+- **B2 dream rewrite/merge: never deletes a source.** Originals live in git andthe supersession chain; `dry_run` first; R2-gated; opt-in LLM. The zero-LLM- default path (#13) is untouched — a provider-less store never runs B2.-- **C1 access reinforcement on more read paths — strictly non-destructive.** It+ default path (#13) is untouched; a provider-less store never runs B2.+- **C1 access reinforcement on more read paths: strictly non-destructive.** Itonly raises retention scores (keeps memory a little longer); it can never lower ascore or delete anything, and it still cannot block TTL cleanup (the TTL passruns regardless of how hot a page is). It stays on the throttled/async@@ -488,8 +488,8 @@ supersession** until the existing 180-day tombstone grace + hard-delete**Proof bar before any release carrying these features** (the #776 / 2.3.2model): the full cross-platform CI matrix green on the exact RC SHA, **and** a-live deploy + verify against the real marvin store — a large, already-migrated-store opening cleanly, indexes consistent, no data loss — exactly as V62/#776 was+live deploy + verify against the real marvin store (a large, already-migrated+store opening cleanly, indexes consistent, no data loss), exactly as V62/#776 wasvalidated. A green unit suite is not sufficient for anything that mutates storedcontent.@@ -497,7 +497,7 @@ content.Additive columns plus `set_abort_missing(true)` (`migrations.rs:34`) mean an olderbinary opening a newer store **fails closed** with the actionable-`StoreError::DataSchemaAhead` (`error.rs:36`, raised at `migrations.rs:55`) — it+`StoreError::DataSchemaAhead` (`error.rs:36`, raised at `migrations.rs:55`). Itnames the applied-vs-supported versions and refuses to open, rather than silentlycorrupting a store it doesn't understand. That guarantee must be preserved byevery new migration.@@ -506,7 +506,7 @@ every new migration.R2 is the reproducible LongMemEval-V2 recall-eval harness(`crates/ai-memory-consolidate/tests/recall_eval.rs`, built in #771/#772). It is-the gate, not a formality:+the gate for this work:- **No-regression gate (mandatory for anything that changes stored content orranking):** A2 compaction, A3 dedup, and A4 filtering must not lower recall vs.@@ -514,7 +514,7 @@ the gate, not a formality:- **Quality gate (mandatory before default-on for B1/B2):** must show a positivetriple-accuracy / QA delta, not just "no worse". Ships behind a flag until thenumber exists.-- **Ordering/scheduling (B3/B4):** no independent R2 bar — they inherit B2's gate;+- **Ordering/scheduling (B3/B4):** no independent R2 bar, since they inherit B2's gate;correctness is proven by unit/integration tests (cancel-on-activity, boundedwork, observable outcome per run).- **Access reinforcement (C1/C2):** reinforcement is an *input* to the sweep, not a@@ -524,4 +524,4 @@ the gate, not a formality:Honest bottom line: buckets A and C are shippable now on our zero-LLM turf andclose a real gap (the read-path reinforcement hole in C1, single-λ decay in A1).Bucket B activates substrate that has been deliberately dormant behind exactly-this harness — it does not default on until R2 says it earns its place.+this harness, and it does not default on until R2 says it earns its place.diff --git a/docs/design-page-ingestion-windows.md b/docs/design-page-ingestion-windows.mdindex 2cebdab3..8d0521bf 100644--- a/docs/design-page-ingestion-windows.md+++ b/docs/design-page-ingestion-windows.md@@ -1,6 +1,6 @@# Design: Page-grain ingestion windows + version-filtered `as_of` (issue #656)-*Status: implemented on the `release/2.2` line (2.2.0) — V62 page-grain+*Status: implemented on the `release/2.2` line (2.2.0): V62 page-grainwindows, version-filtered `as_of` FTS fused via the default path's RRF,`docs/temporal.md` updated. Scope stayed Phase A only; Phase B remainsdeferred (§7). Open question 1 resolved by the v2.1.0 cut (new features@@ -51,9 +51,8 @@ link grain:The issue title frames the feature as valid-time ("true in the world").Phase A's `valid_from`/`valid_to` are **ingestion time**: the version's own-`created_at` and the superseding version's `created_at` — the *same*-dimension the entity-link windows already use, just materialized at page-grain. "Valid-time" stays reserved for the world-time split (Phase B, §7).+`created_at` and the superseding version's `created_at`. That is the *same*+dimension the entity-link windows already use, materialized at page grain. "Valid-time" stays reserved for the world-time split (Phase B, §7).Pinned terms for this doc and the implementation PR:@@ -68,14 +67,14 @@ Pinned terms for this doc and the implementation PR:- `valid_from` mirrors `entity_page_links.valid_from` deliberately: samedimension, same predicate shape, same tests. The "valid" here reads as"the version the store treated as current", never as world truth.-- The window end is **`valid_to`, not `superseded_at`**, for a load-bearing- reason: `pages.superseded_at` already exists with a different meaning —+- The window end is **`valid_to`, not `superseded_at`**, because+ `pages.superseded_at` already exists with a different meaning: it isthe V03 decay-tombstone eviction marker, written exactly when`supersedes IS NULL` (sweep eviction, not supersession). Reusing thatname would conflate "evicted by the forget sweep" with "replaced by anewer version". `valid_to` also covers ends that have no supersedingversion at all (retirement without successor, below), where- "superseded_at" would be a lie.+ "superseded_at" would be wrong.- `valid_from` duplicates `created_at` by construction. That duplication isaccepted (see §4): it keeps the window self-describing per row and the`as_of` predicate symmetric with the link-grain one.@@ -84,15 +83,15 @@ Pinned terms for this doc and the implementation PR:A version's window closes at exactly one of:-1. **Supersede** — a new version of the same path is written. `valid_to` =+1. **Supersede**: a new version of the same path is written. `valid_to` =the new version's `created_at`, closed in the same transaction as the`is_latest` flip (mirrors the link-window close in `upsert_page_in_tx`).-2. **Retire without successor** — decay tombstone, purge-regenerate,+2. **Retire without successor**: decay tombstone, purge-regenerate,graveyard merge (the V58 class). `valid_to` = the retirement instant(recorded explicitly on both grains), closed in the sametransaction as the retire. New retire paths must close both grains;V58's audit is the checklist.-3. **Open** — `valid_to IS NULL` while the version is the latest live one.+3. **Open**: `valid_to IS NULL` while the version is the latest live one.Deletion stays deletion: purged pages cascade away and the timeline doesnot survive a purge, exactly as `docs/temporal.md` already states for@@ -108,23 +107,23 @@ for successor-less retirements. No migration required. Weighed againststored nullable columns + backfill:**View/join.**-- Pro: zero migration — no refinery step, no backup gate, no backfill, no- new V58-class risk; a window can never be left open by construction.+- Pro: zero migration (no refinery step, no backup gate, no backfill, no+ new V58-class risk); a window can never be left open by construction.- Con: every `as_of` FTS query pays a self-join against `pages_fts`candidates on the read path, with an FTS5+join plan to defend in review;- the retirement-instant rule does not disappear, it relocates into the- view definition (the V58 logic must still be specified somewhere); no+ the retirement-instant rule moves into the view definition instead of+ going away (the V58 logic must still be specified somewhere); nocovering index for the range predicate.**Materialized (`ALTER TABLE pages ADD COLUMN valid_from/valid_to` +index + one-shot backfill).**-- Pro: symmetric with the V56 link windows — same predicate shape+- Pro: symmetric with the V56 link windows, with the same predicate shape(`valid_from <= T AND (valid_to IS NULL OR valid_to > T)`), sameclose-in-the-same-transaction discipline, same test shapes; a sargablerange predicate with a covering index for the `as_of` FTS join; eachrow's window is auditable without joining.-- Con: it is a backup-gated store migration (§5) — a bigger step than the- issue frames; it introduces a new leave-open risk, held down only by+- Con: it is a backup-gated store migration (§5), a bigger step than the+ issue suggests; it introduces a new leave-open risk, held down only bytransactional closes plus tests with controls.**Recommendation: materialized.** The deciding factors are predicate@@ -132,16 +131,16 @@ symmetry across the two grains (one window semantic, two tables) andkeeping the `as_of` FTS join sargable. The migration cost is real butbounded and precedented (V56 pattern + the §5 backup gate). If reviewprefers zero-migration, the view is a legitimate fallback with identical-query semantics — the rest of this doc is unchanged either way.+query semantics, and the rest of this doc is unchanged either way.No FTS rebuild is needed in either case: the `pages_fts_*` triggers index-every version row already (including superseded ones); version-filtered-FTS is a join-predicate change, not an index change.+every version row already (including superseded ones), so version-filtered+FTS only changes a join predicate.## 5. Migration: backup-gated, and stated plainlyPhase A is additive (nullable columns + index + backfill, no removed or-renamed surface, no changed defaults) — but additive is not free:+renamed surface, no changed defaults), but it still has costs:- **Refinery migration**, one step: add the nullable columns, backfill(`valid_from = created_at`; `valid_to` from the superseding version's@@ -154,9 +153,9 @@ renamed surface, no changed defaults) — but additive is not free:- **Backup gate.** The migration refuses to run without a verifiedpre-migration safety archive, per the current store-migration policy(the #633 ordering fix: archive *before* the schema migration, abort- when the archive cannot be written or verified). This is the step the- issue understates, stated here so the implementation PR is sized- honestly.+ when the archive cannot be written or verified). The issue understates+ this step; it is listed here so the implementation PR is sized+ correctly.- **Rollback.** Restore the verified pre-migration snapshot from #633before starting the older binary. Refinery rejects newer appliedschema versions; an older binary cannot read the migrated store.@@ -169,9 +168,8 @@ lookup and skips FTS/vector/graph: "mixing current relevance withhistorical validity answers neither honestly" (`server.rs` returns earlywith `streams_active: ["entity"]`, no raw-observation fallback).-Version-filtered FTS at T is a genuine answer to that objection, and this-section is the explicit argument the maintainer asked for rather than a-silent scope slip:+Version-filtered FTS at T answers that objection. The maintainer asked for an+explicit argument instead of a silent scope change, and this section is it:- The original objection is about mixing **present-tense relevance** with**past validity**. Constraining the FTS corpus to versions whose@@ -206,10 +204,10 @@ its precision for entity-phrased questions.could never populate it. `NULL = unknown, fall back to ingestion time`remains a future design, not this one.- **Default-path rank changes.** The issue proposes capping superseded /- validity-expired pages in non-`as_of` ranking — but the default path+ validity-expired pages in non-`as_of` ranking, but the default pathonly indexes `is_latest = 1` rows, so superseded versions never rank- today; the "freshness never touches ranking" complaint is really about- *stale-but-latest* pages, a different problem. Tag-carried staleness+ today. The "freshness never touches ranking" complaint is about+ *stale-but-latest* pages, which is a different problem. Tag-carried stalenessalready has an authority mechanism (`superseded → 0.65`,`historical → 0.80` in `PageAuthority`). Phase A makes **no default-pathrank change**; any freshness signal is a separate proposal with eval@@ -235,7 +233,7 @@ its precision for entity-phrased questions.implementation PR still ride the `release/2.1` line (2.1.x additive)or wait for the next minor?2. Materialized pair (`valid_from` + `valid_to`) vs. minimal single- `valid_to` with `valid_from` read as `created_at` — is the symmetry+ `valid_to` with `valid_from` read as `created_at`: is the symmetryworth the duplicated column?3. In `as_of` mode, should FTS and entity merge via RRF, or should FTSact strictly as fallback when the entity stream misses?diff --git a/docs/design-per-project-authz.md b/docs/design-per-project-authz.mdindex cb6b713a..6f25af79 100644--- a/docs/design-per-project-authz.md+++ b/docs/design-per-project-authz.md@@ -18,8 +18,8 @@ makes `restricted` safe end-to-end:but mutate (delete, feedback, sweep, lint, auto-improve, handoff accept andcancel, message pop and cancel, a message's recipient) resolve at`ProjectAccess::Write`.-- **Unscoped reads** — search, listings, the graph and the workspace- overview — are filtered in SQL before `LIMIT` with the same rule the choke+- **Unscoped reads** (search, listings, the graph and the workspace+ overview) are filtered in SQL before `LIMIT` with the same rule the chokepoint applies; the global preferences scope stays readable by everyone.- **Raw-id entry points** (managed runs, workstreams, session-scopedconsolidation) resolve the id to its project and authorize it.@@ -34,14 +34,14 @@ Per-project administrators remain out of scope: granting, revoking andrestricting are root's alone. Sections below are the original design pass,retained as the spec.-**Original status: proposal for review — not implemented.** This was the design+**Original status: proposal for review, not implemented.** This was the designpass promised on #708 before any code lands. It changes a security boundary, soit is deliberately separated from implementation.## ProblemOn a multi-user server (one where DB users exist, or a trusted identity proxy is-configured — `deployment_distinguishes_operators()` is true), a DB-user token attributes+configured, so `deployment_distinguishes_operators()` is true), a DB-user token attributeswrites to that user but does **not** scope which projects the user may read or write.Any authenticated non-root caller can resolve any `(workspace, project)` and read orwrite it. Attribution exists; authorization does not. `/admin/*` is already root-only,@@ -61,7 +61,7 @@ bitten single-user installs. It is a real gap for a shared server hosting severacarries the resolved user. DB users live in the `users` table (token-hash auth).- **Scope**: `ScopeResolver` resolves `(workspace_id, project_id)`; reads use no-createlookups and fail closed on missing scope. `OwnerFilter` (pages shared, batons owned)- applies to handoffs only — invariant #16 forbids it becoming a page-read filter.+ applies to handoffs only; invariant #16 forbids it becoming a page-read filter.## Proposed model@@ -102,7 +102,7 @@ grant for writes and a `read`/`write` grant for reads; else `AuthzError::ForbiddAnonymous is denied on any restricted project. This must **not** reintroduce theinvariant-#16 hazard: the grant gate is an *authorization* check that returnsallow/deny; it is not an `OwnerFilter` on page rows. A team with grants still sees the-same shared pages — grants gate entry to the project, not row visibility within it.+same shared pages: grants gate entry to the project, not row visibility within it.### Enforcement gaps beyond the choke point (must close before enforcing)@@ -113,7 +113,7 @@ they bypass the gate entirely. Both must be handled or a `restricted` project le1. **Unscoped / cross-project reads.** `memory_query(global=true)`, global `memory_recent`,and cross-project web search fan out across every project and never call the scoperesolver, so `authorize_project` is never reached. These must filter the **result set- by the caller's readable projects inside SQL, before `LIMIT`** — not after. Post-filtering+ by the caller's readable projects inside SQL, before `LIMIT`**, not after. Post-filteringa materialized page would still leak the *existence and count* of hits in projects thecaller cannot read (and could starve the visible results under the limit). Concretely:join candidate rows against `project_grants` (+ `access_mode='open'` + creator + root)@@ -123,7 +123,7 @@ they bypass the gate entirely. Both must be handled or a `restricted` project ledirectly and resolve their project *from the row*, bypassing scope resolution byconstruction: consolidation-by-session-id, managed-run routes, SessionStart handoffdelivery, and `ReaderPool::page_evidence_counts(page_ids)`. Each must resolve the id →- its `(workspace, project)` and then call `authorize_project` before returning content —+ its `(workspace, project)` and then call `authorize_project` before returning content;an unauthorized id is `NotFound`/`Forbidden`, never a silent read. Audit everyentry point that accepts a bare id against this rule; a new one that skips it silentlyreopens the hole while every scoped test still passes.@@ -158,7 +158,7 @@ explicitly, then grants users. Single-user/loopback is unaffected (no DB users## Open questions for review1. **Default for NEW projects on a multi-user server**: keep `open` (least surprise) or`restricted` to the creator (secure-by-default)? Proposal: `open`, with a server- config `[auth] new_projects_restricted = true` to flip it — so secure-by-default is+ config `[auth] new_projects_restricted = true` to flip it, so secure-by-default isavailable without breaking the common case.2. **Global scope (`_global`)**: read-open to all authenticated users (it is sharedpreference context), never restricted. Writing it needs root or an explicit@@ -166,7 +166,7 @@ explicitly, then grants users. Single-user/loopback is unaffected (no DB usersuser's reads, restricted projects included.3. **Interaction with cross-project messaging (V64)**: a `restricted` recipient inboxshould require the sender to hold a `write` grant on the recipient project, or the- message is refused — otherwise grants are bypassable via the mailbox. This ties #708+ message is refused; otherwise grants are bypassable via the mailbox. This ties #708to the messaging feature and is why it must be designed, not bolted on.4. **Handoff `OwnerFilter`**: unchanged; grants and owner-batons are orthogonal.@@ -196,7 +196,7 @@ for the two bypass classes above:Authorization is only sound if two unrelated checkouts that happen to share afolder basename (`~/work/api` and `~/clients/acme/api`) resolve to **different**-projects — otherwise one grant silently covers both. Slice 4 routes captures by+projects. Otherwise one grant silently covers both. Slice 4 routes captures by**repository identity** (the normalized git remote) instead of folder name:- A new `V70` migration adds `projects.identity` / `identity_source`@@ -204,22 +204,22 @@ projects — otherwise one grant silently covers both. Slice 4 routes captures b`(workspace_id, identity) WHERE identity <> ''` and **no backfill** (abackfill on `lower(name)` would fail a workspace holding both `API` and `api`).- Identity is derived by `git2::Repository::discover` (config read only) and- normalized **lexically** (scheme split, credential strip, `.git`/slash tidy) —+ normalized **lexically** (scheme split, credential strip, `.git`/slash tidy),never `fs::canonicalize`. Credentials in a remote URL are stripped client-sideand never sent; the server re-validates any wire `identity` (`accept_wire_identity`).- Resolution order is **explicit scope > declared `project` > git-remote identity> folder name**; a non-git directory falls back to the folder-name behavior(fail-closed, no new collision).-- The same normalization runs at all four capture front doors — native+- The same normalization runs at all four capture front doors (native`ai-memory hook`, the shell bundle, the PowerShell bundle, and the generated- TypeScript integrations — checked by a shared-fixture parity test so they+ TypeScript integrations), checked by a shared-fixture parity test so theycannot drift.**Decision (resolved):** this is **always-on** in 2.5.0, not gated behind aflag. Opt-in would leave the same-basename grant hole open for anyone who did-not opt in, defeating the authorization slices. The trade-off — that an upgrading+not opt in, defeating the authorization slices. The trade-off is that an upgradinginstall's captures re-bucket by repository identity (two same-name repos split; one-repo opened from two folders converges) — is documented in the CHANGELOG.+repo opened from two folders converges); the CHANGELOG documents it.## Path-keyed coordinates (#1033 — staged)@@ -241,7 +241,7 @@ project. #1033 makes a remote-derived key the default name, landing in steps onpath name is used only while no project in the workspace holds it, checkedin the same transaction as the identity match, so `gitlab.com/acme/api`after `github.com/acme/api` falls back to the name it would otherwise get.- Existing projects — matched, claimed or unclaimed — are never renamed.+ Existing projects, whether matched, claimed or unclaimed, are never renamed.Checked against the `styled_key` and `identity_style` sections of`fixtures/remote_identity_cases.json` (core plus shell, PowerShell andTypeScript parity), store adversarial tests, and a two-operatordiff --git a/docs/design-rules-promotion.md b/docs/design-rules-promotion.mdindex 3a173217..e08110c3 100644--- a/docs/design-rules-promotion.md+++ b/docs/design-rules-promotion.md@@ -3,44 +3,44 @@*Cross-project sharing (deferred in §8 below) is designed and implemented bythe profile: see `docs/design-cross-project-profile.md`.*-*Status: design proposal — not implemented. (Originally scoped against the 2.1-line; that and 2.2 shipped without it, so it is un-targeted and still open —-this is the balance research the feature needs before code.)*+*Status: design proposal, not implemented. (Originally scoped against the 2.1+line; that and 2.2 shipped without it, so it is un-targeted and still open.+This document is the balance research the feature needs before code.)*## 1. The idea, and the trapInsight borrowed from ECC (`docs/research-ecc.md`): **"Memory is unreviewedcontext, not executable policy. Promote accepted knowledge into governed-project documentation."** ai-memory already gestures at this — the lint emits-a `rule_suggestion` finding ("this page looks like a durable rule; consider-copying it into CLAUDE.md/AGENTS.md"). The 2.1 feature closes that loop:-turn a durable memory into a **governed, always-loaded rule** the agent obeys-every turn.+project documentation."** ai-memory already points in this direction: the lint+emits a `rule_suggestion` finding ("this page looks like a durable rule;+consider copying it into CLAUDE.md/AGENTS.md"). The 2.1 feature closes that+loop by turning a durable memory into a governed, always-loaded rule the agent+obeys every turn.-The trap the maintainer named, and the one that kills this feature if we get-it wrong: **AGENTS.md is a scarce, shared budget, not a filing cabinet.** If-promotion dumps every learned rule in, AGENTS.md bloats, adherence collapses,-and we've made the agent *worse*, silently.+The maintainer named the trap, and it kills this feature if we get it wrong:+AGENTS.md is a scarce, shared budget. If promotion dumps every learned rule+into it, AGENTS.md bloats, adherence collapses, and the agent silently gets+*worse*.## 2. Why the budget is real (not a preference)From the 2026 best-practice consensus (sources below):-- Frontier models reliably follow only **~150–200 instructions**; the harness- system prompt already spends **~50** of them. The usable budget for- *promoted user rules* is therefore ~**100 instruction-lines**, shared with- everything the human already wrote in AGENTS.md.-- Past ~200 lines, **"context rot" / "lost in the middle"** sets in —- measured adherence drops **>30%**, and it drops for the rules that *matter*,- not just the new ones. Bloat doesn't add weak rules; it weakens strong ones.-- **`@path`/import pointers do not save context** — imported files load at- launch. "Move it to a linked doc" is not a budget saving; it's the same- tokens with indirection.-- The load-bearing test for any AGENTS.md line: *"Would removing this cause- the agent to make a mistake?"* If no, it does not belong there.--Conclusion: promotion must be **subtractive by default** — it competes for a-fixed number of slots and must *evict* to *admit*.+- Frontier models reliably follow only ~150–200 instructions; the harness+ system prompt already spends ~50 of them. The usable budget for promoted+ user rules is therefore ~100 instruction-lines, shared with everything the+ human already wrote in AGENTS.md.+- Past ~200 lines, "context rot" / "lost in the middle" sets in. Measured+ adherence drops by more than 30%, and the drop hits the rules that matter as+ well as the new ones, so bloat weakens the strong rules.+- `@path`/import pointers do not save context, because imported files load at+ launch. Moving a rule to a linked doc spends the same tokens with+ indirection.+- The test for any AGENTS.md line: *"Would removing this cause the agent to+ make a mistake?"* If no, it does not belong there.++Conclusion: promotion must be subtractive by default. It competes for a fixed+number of slots, and admitting a rule means evicting another.## 3. Two tiers, one clear boundary@@ -48,80 +48,80 @@ fixed number of slots and must *evict* to *admit*.|---|---|---|| Loaded | Every turn, always | On demand, during planning, via `memory_query` || Cost | A slot in the scarce budget | Zero standing cost |-| For | Invariants, guardrails, conventions the agent must *never* violate and that apply *broadly* | Context-specific facts, decisions, gotchas, history — "what we did / why X is the way it is" |+| For | Invariants, guardrails, conventions the agent must *never* violate and that apply *broadly* | Context-specific facts, decisions, gotchas, history: "what we did / why X is the way it is" || Test | "Forgetting this causes a mistake on many tasks" | "Relevant only when the task touches it" || Examples | "All SQLite writes go through the single writer actor"; "never write files in place — tmp+rename" | "In July we chose Caddy over nginx because…"; a month-old debugging gotcha |-**The default is retrieval.** A memory is `_rules/`-kind and durable, and it-*still* stays retrieval-only unless it clears a higher bar (below). This is-the anti-bloat stance: promotion is the exception, not the reward for-durability. Old knowledge, one-off gotchas, and decisions-with-context are-*exactly* what should surface during task planning, never permanently.+**The default is retrieval.** A memory can be `_rules/`-kind and durable and+still stay retrieval-only unless it clears a higher bar (below). Promotion is+the exception, and durability alone does not earn it. Old knowledge, one-off+gotchas, and decisions-with-context should surface during task planning and+never be loaded permanently.## 4. What clears the bar for promotionA candidate (a `_rules/`-kind page the lint already flags) is eligible only-if it is **broad, imperative, durable, and cheap to state**:+if it is broad, imperative, durable, and cheap to state:-1. **Broad applicability** — it constrains many tasks, not one file/feature.+1. **Broad applicability.** It constrains many tasks, not one file or feature.Heuristic: referenced/accessed across multiple sessions and paths, not asingle-scope note.-2. **Imperative & falsifiable** — it says *do X / never Y*, not "we discussed- Z." A rule you can catch the agent violating.-3. **Durable & high-confidence** — survived N sessions without contradiction,- with a confidence score (another ECC borrow) above a threshold; no open- `contradicts` typed-edge against it.-4. **Compact** — one or two lines. If it needs a paragraph of context, it is- retrieval knowledge, not a rule.+2. **Imperative & falsifiable.** It says *do X / never Y*, not "we discussed+ Z." You can catch the agent violating it.+3. **Durable & high-confidence.** It survived N sessions without+ contradiction, with a confidence score (another ECC borrow) above a+ threshold, and no open `contradicts` typed-edge points at it.+4. **Compact.** One or two lines. If it needs a paragraph of context, it is+ retrieval knowledge.-Everything that fails any test stays retrieval-only. This keeps the promoted-set small *by construction*, not by after-the-fact pruning.+Everything that fails any test stays retrieval-only. The promoted set stays+small because of these tests, without after-the-fact pruning.## 5. Anti-bloat by mechanism, not discipline-- **Hard budget.** A configurable cap (default small, e.g. **≤ 15 promoted- rules / ~40 lines**) on the managed block. Promotion is admission-controlled+- **Hard budget.** A configurable cap (default small, e.g. ≤ 15 promoted+ rules / ~40 lines) on the managed block. Promotion is admission-controlledagainst it.-- **Evict to admit — but the user chooses.** At the cap, `rules approve`+- **Evict to admit, but the user chooses.** At the cap, `rules approve`refuses to silently overflow: it names the lowest-scoring current rule andasks the user to `remove` it (or raise the cap) first. Nothing is demotedwithout a command. Score = confidence × breadth × recency-of-use, used only- to *rank* and to *suggest* what to drop.+ to rank candidates and suggest what to drop.- **Decay lowers rank, never removes.** A promoted rule that stops beingexercised sinks in `rules recommend` and can be flagged stale for the user- to `remove`, so the block trends toward *current* policy — but the removal- is always a human command, never automatic.-- **Never writes on the hot path.** The classifier/scorer that *produce*+ to `remove`, so the block trends toward current policy. The removal is+ always a human command, never automatic.+- **Never writes on the hot path.** The classifier/scorer that producecandidates can reuse the consolidation machinery, but the AGENTS.md block is- written *only* by an explicit `approve`/`edit`/`remove` — never as a live+ written *only* by an explicit `approve`/`edit`/`remove`, never as a liveside effect of a session (see §6).## 6. Command-driven, never auto-editing (maintainer's call, and the right one)The feature does **not** edit AGENTS.md on its own. There is no background-writer and no "auto-apply." ai-memory only ever *recommends*; the human's-explicit command is the only thing that changes the file. This is strictly-better than staged-auto-apply for the maintainer's stated fear — the user is-in the loop *by construction*, so nothing can change behind their back, and-there is no "did I get notified enough?" problem to tune.+writer and no "auto-apply." ai-memory only recommends; the human's explicit+command is the only thing that changes the file. For the maintainer's stated+fear, this is strictly better than staged auto-apply: the user is always in+the loop, nothing can change behind their back, and there is no "did I get+notified enough?" problem to tune.**The command surface** (CLI, mirrored as MCP tools so an agent can run themwhen the user asks):-- **`ai-memory rules recommend`** — read-only. Lists candidate promotions the- classifier/scorer surfaced (§4–5), ranked, each with: the one-line rule,- source page, confidence, breadth signal, and *why it qualified*. Changes- nothing. This is the discovery surface — the user asks "what have you- learned that's rule-worthy?" and sees a short, ranked list, not a wall.-- **`ai-memory rules approve <id>`** — promote one candidate into the managed- AGENTS.md block. If the block is at budget, the command *tells the user*+- **`ai-memory rules recommend`**: read-only. Lists candidate promotions the+ classifier/scorer surfaced (§4–5), ranked, each with the one-line rule,+ source page, confidence, breadth signal, and why it qualified. Changes+ nothing. This is how the user discovers candidates: they ask "what have you+ learned that's rule-worthy?" and get a short, ranked list.+- **`ai-memory rules approve <id>`**: promote one candidate into the managed+ AGENTS.md block. If the block is at budget, the command tells the user("at 15/15; approving this means dropping <lowest>, or raise the cap") and- does nothing until they decide — eviction is a user choice, never silent.-- **`ai-memory rules edit <id>`** — tweak the rule's wording before/after+ does nothing until they decide. Eviction is a user choice, never silent.+- **`ai-memory rules edit <id>`**: tweak the rule's wording before/afterpromoting (the human phrasing usually beats the extracted one).-- **`ai-memory rules remove <id>`** — demote a promoted rule back to+- **`ai-memory rules remove <id>`**: demote a promoted rule back toretrieval-only. The `_rules/` page is untouched; only the AGENTS.md line goes.-- **`ai-memory rules list`** — show what is currently promoted (the managed+- **`ai-memory rules list`**: show what is currently promoted (the managedblock's contents, with provenance).**Guarantees:**@@ -131,24 +131,24 @@ when the user asks):`<!-- ai-memory: promoted rules (managed) -->`). The human's hand-writtenAGENTS.md outside the markers is **never** touched.- **Provenance per rule.** Each promoted line carries a terse trailer (source- page + confidence) so a reader sees *why* it's there and can open the memory.-- **Recommendations are pull, not push.** Candidates accrue silently; the user- sees them only when they run `recommend`. The one *optional*, low-key nudge:- a single `status` line ("N new rule recommendations — `ai-memory rules- recommend`") when the candidate set grows, off by a config flag. No per-turn- chatter, no pending-writes to babysit.+ page + confidence) so a reader sees why it's there and can open the memory.+- **Recommendations are pulled by the user.** Candidates accrue silently; the+ user sees them only when they run `recommend`. The one optional nudge is a+ single `status` line ("N new rule recommendations — `ai-memory rules+ recommend`") when the candidate set grows, off by a config flag. There is no+ per-turn chatter and no pending-writes queue to watch.- **Fully reversible.** Removing the managed block (or never running `approve`)leaves AGENTS.md exactly as the human wrote it; `remove`/demotion losesnothing (the `_rules/` page remains queryable).-The earlier auto-improve staging path is *not* used here — promotion is a+The earlier auto-improve staging path is *not* used here. Promotion is adeliberate, human-issued edit, not an eval-gated background write. (The-classifier/scorer that *produce* candidates can still reuse the consolidation-machinery; only the write is command-gated.)+classifier/scorer that produce candidates can still reuse the consolidation+machinery; only the write requires a command.)## 7. Reusing what already exists-Nothing here needs a new subsystem — it composes primitives 2.0 already ships:+Nothing here needs a new subsystem. It composes primitives 2.0 already ships:- **Candidate signal:** the lint `rule_suggestion` finding.- **Durability/typed contradiction:** `_rules/` pages, `kind: rule`, typed@@ -156,7 +156,7 @@ Nothing here needs a new subsystem — it composes primitives 2.0 already ships:- **Review gate:** the auto-improve staged, eval-gated, pending-writes path.- **The write surface:** the `routing_snippet` marker-block mechanism thatalready manages a delimited region of CLAUDE.md/AGENTS.md.-- **Confidence:** to be surfaced (a small, legible addition — see+- **Confidence:** to be surfaced (a small, legible addition; see`docs/research-ecc.md`).## 8. Proposed 2.1 scope vs later@@ -164,35 +164,35 @@ Nothing here needs a new subsystem — it composes primitives 2.0 already ships:**2.1 (this feature):**- Config: `[rules_promotion] enabled` (default false), `max_promoted`,`min_confidence`, and `recommend_hint` (the optional one-line `status`- nudge; default off). **No `auto_apply` — there is none.**+ nudge; default off). There is no `auto_apply` option.- The classifier (§4) + scorer (§5) over `_rules/` candidates.- The command surface: `rules recommend` / `approve` / `edit` / `remove` /`list` (CLI + MCP tools), each read-only except the three that the userexplicitly invokes to change the managed block.- The managed "promoted rules" sub-block writer via `routing_snippet`, with- provenance trailers — written **only** by `approve`/`edit`/`remove`.+ provenance trailers, written **only** by `approve`/`edit`/`remove`.- `status` reporting of the currently-promoted set (and the optionalnew-recommendations hint).-- Demotion via `remove`; decay only *lowers a rule's rank in `recommend`* and- can flag a stale promoted rule for the user to `remove` — it never+- Demotion via `remove`; decay only lowers a rule's rank in `recommend` and+ can flag a stale promoted rule for the user to `remove`. It neverauto-removes.**Later (explicitly out of 2.1):**- Cross-project / team rule sharing.- Per-glob scoped rules (Cursor-style) rather than one global block.-- Automatic rule *synthesis* (merging several memories into one crisp rule) —- starts as human-reviewed only.+- Automatic rule *synthesis* (merging several memories into one crisp rule),+ starting as human-reviewed only.## 9. Open questions (for maintainer input before coding)1. Budget default: is ~15 rules / ~40 lines the right ceiling, or tighter?-2. Where should the managed block sit — AGENTS.md, CLAUDE.md, or both (and+2. Where should the managed block sit: AGENTS.md, CLAUDE.md, or both (andhow to avoid double-loading when a tool reads both)?3. Should `approve` also (optionally) emit a small commit so the promotion iscaptured in the repo's history, or leave that to the user's normal flow?4. `recommend`'s default verbosity: top-N only (say 5), with a `--all` flag?-*(Resolved by maintainer, 2026-09-03: no auto-editing of AGENTS.md — the+*(Resolved by maintainer, 2026-09-03: no auto-editing of AGENTS.md. Thefeature only recommends; `approve`/`edit`/`remove` commands are the onlythings that write the managed block. §6 reflects this.)*diff --git a/docs/design-windows-ci.md b/docs/design-windows-ci.mdindex 0aeb7e47..bbe3de5c 100644--- a/docs/design-windows-ci.md+++ b/docs/design-windows-ci.md@@ -1,38 +1,38 @@# Design: a fast local Windows test/build loop (dockur on marvin) alongside `windows-latest`**Status: Phase 0 shipped; Phase 1 measured on marvin (see the results section at the-end).** This began as a feasibility + design study evaluating options for a fast, reliable,+end).** This began as a feasibility and design study of options for a fast, reliable,mostly-local Windows test/build loop to supplement (not blindly replace) the current GitHub`windows-latest` CI. Phase 0 (the cross-compile build gate) has since been implemented and-Phase 1 (the dockur VM) has been stood up and benchmarked; the "Phase 1 results" section at+Phase 1 (the dockur VM) has been stood up and benchmarked. The "Phase 1 results" section atthe end records the measured numbers and the host-specific accommodations, and revises the-recommendation accordingly. The body below is the original study, preserved as the rationale.+recommendation accordingly. The body below is the original study, kept as the rationale.-This is a *written study*. Every recommendation is grounded in the repo's actual setup+This is a *written study*. Every recommendation is based on the repo's actual setup(`.github/workflows/windows.yml`, the enumerated `#[cfg(windows)]` surface, and the-recent flake history) and in cited external sources. Fetched web content was treated as+recent flake history) and on cited external sources. Fetched web content was treated asuntrusted; only facts were extracted.## Problem-Windows is a real, shipped target — "Experimental" in the support matrix+Windows is a real, shipped target. It is "Experimental" in the support matrix(`docs/support-matrix.md`), but tagged releases publish `ai-memory-windows-x86_64.zip`with `ai-memory.exe`, and the PowerShell hook/wrapper surface exists *only* for Windows.The `#[cfg(windows)]` regression tests are the one place several Windows-only code paths-ever execute: the Linux/macOS matrix in `ci.yml` never compiles them. So the coverage is-not optional — but the way we get it hurts.+ever execute: the Linux/macOS matrix in `ci.yml` never compiles them. So we need that+coverage, but the way we get it is expensive.**Quantified cost (from the `windows.yml` header comment).**-- A Windows run takes **~1000s** against **~250s** for the same tests on Linux — slower- linking, and a cache restore that is **~10x slower** over many small files.+- A Windows run takes **~1000s** against **~250s** for the same tests on Linux, because of+ slower linking and a cache restore that is **~10x slower** over many small files.- Every gating job in `ci.yml` finishes in **~8 minutes**. Leaving Windows *in* thatworkflow made every pull request wait **~17 minutes**, with the last ~8 spent on a jobthat was `continue-on-error` and therefore blocked nothing.-- The response was to pull Windows out into its own workflow, gated three ways:- nightly cron (`23 4 * * *`), `workflow_dispatch`, and the `windows` **label** on a PR+- The response was to move Windows into its own workflow, gated three ways:+ nightly cron (`23 4 * * *`), `workflow_dispatch`, and the `windows` label on a PRthat touches platform-sensitive code. The job dropped `continue-on-error`, so those- runs are now red-or-green rather than advisory.+ runs are now red-or-green instead of advisory.**Observed pain beyond raw slowness (from git history + CHANGELOG).**@@ -46,91 +46,91 @@ not optional — but the way we get it hurts.(PR #827). Timing assumptions that hold on Linux do not hold on a shared Windows runner.- **Hook-shell friction on the runner** (#758 family): quote the PowerShell interpreterpath (`2cd18840`), convert MSYS paths before handing them to `powershell.exe`- (`d5afdcbf`), and give the hook bundle its own job then gate it behind the `windows`+ (`d5afdcbf`), and give the hook bundle its own job, then gate it behind the `windows`label (`a8405568`, `deb64063`).- **Fork-PR gating friction.** GitHub requires manual approval ("action_required") beforea workflow runs on a fork PR from an outside contributor. Combined with the label gate,a contributor's Windows-relevant change often needs a maintainer to *both* approve the- run *and* add the `windows` label — and only then wait ~1000s. Feedback on a+ run *and* add the `windows` label, and only then wait ~1000s. Feedback on aWindows-sensitive fork PR is therefore slow and manual.-The through-line: `windows-latest` is **shared, slow, and timing-noisy**, so we pay for it+In short, `windows-latest` is shared, slow, and timing-noisy, and we pay for itwith label-gating friction, hand-relaxed timeouts, and per-flake patches. The maintainerdevelops on Linux and runs a homelab box, **marvin** (Linux, 32 cores, ~2.6 TB free,-KVM available), which is idle capacity that could give a Windows loop measured in *tens of+KVM available). Its idle capacity could give a Windows loop measured in *tens ofseconds of iteration* instead of a ~17-minute round trip through GitHub.-The goal of this study: a fast, reliable, mostly-local way to run the real-Windows surface+The goal of this study is a fast, reliable, mostly-local way to run the real-Windows surfaceon demand (and before every release), **without** taking on the security or licensingliabilities that the obvious "just self-host a runner" answer carries.## The Windows-specific surface (what actually needs real Windows)-The study has to be concrete about *what* must run on native Windows versus what Linux-already covers, or the cost/benefit of every option is guesswork. Enumerated from the code:+The study has to be concrete about *what* must run on native Windows and what Linux+already covers; otherwise the cost/benefit of every option is guesswork. Enumerated from the code:### Only faithfully validated on real Windows-- **Drain-lock `ERROR_LOCK_VIOLATION`** — `crates/ai-memory-cli/src/commands/hook_spool.rs`+- **Drain-lock `ERROR_LOCK_VIOLATION`**: `crates/ai-memory-cli/src/commands/hook_spool.rs`defines `ERROR_LOCK_VIOLATION = 33` and `is_drain_lock_busy_error` treats it as"busy, retry." The *unit* test injects the code via `Error::from_raw_os_error(33)` and soruns on any platform, but whether the OS actually *returns* code 33 for a contendeddrain lock is a real-Windows fact.-- **NTFS file-index "inode" + sharing-violation retry** —+- **NTFS file-index "inode" + sharing-violation retry**:`crates/ai-memory-wiki/src/atomic.rs` reads the NTFS file index via`GetFileInformationByHandle` (`winapi_util::file::information`) so the watcher can skipits own writes, and `persist_with_retry` absorbs a transient- `ERROR_SHARING_VIOLATION (32)` — "the Windows-CI antivirus scenario." The retry test+ `ERROR_SHARING_VIOLATION (32)`, "the Windows-CI antivirus scenario." The retry testinjects error 32 everywhere; the *real* NTFS file-index value and a *real* scanner-heldsharing violation only occur on Windows.-- **libgit2 path-resolution fallback** — `crates/ai-memory-wiki/src/git.rs` carries a+- **libgit2 path-resolution fallback**: `crates/ai-memory-wiki/src/git.rs` carries awhole `#[cfg(windows)]` fallback family (`commit_all_fallback`,`should_try_commit_cli_fallback`, `commit_count_fallback`,`recent_checkpoints_fallback`, `file_at_rev_fallback`) that shells out to the `git` CLIwhen "libgit2 can fail to reopen a freshly initialised wiki repo under dot-prefixed tempdirs with an OS path-resolution error" (`ErrorClass::Os` + `"failed to resolve path"`).- This branch is dead on Linux — it never compiles there — so its behavior is *only* ever+ This branch never compiles on Linux, so its behavior is *only* everexercised on native Windows.-- **Verbatim / UNC / drive-letter path handling** — Windows drive-letter and UNC paths are+- **Verbatim / UNC / drive-letter path handling**: Windows drive-letter and UNC paths aretreated case-insensitively in scope matching (CHANGELOG: `C:\Users\…\repo` vs alower-cased form), plus verbatim-path (`\\?\`) concerns in git/atomic writes and the`%USERPROFILE%`-then-`dirs::home_dir` HOME fallback (`Config::load`). Path *casing* and- verbatim semantics are OS behaviors, not code we can prove correct on Linux.-- **PowerShell hook transport** — `crates/ai-memory-hooks/tests/suite/powershell_utf8.rs`+ verbatim semantics are OS behaviors, and we cannot prove the code correct for them on Linux.+- **PowerShell hook transport**: `crates/ai-memory-hooks/tests/suite/powershell_utf8.rs`and `powershell_home.rs` are `#![cfg(windows)]` and drive the real`hooks/lib/ai-memory-hook.ps1` under a native PowerShell interpreter (UTF-8 body framing,- marker-boundary handling). This is the cold-start flake's home.-- **PowerShell wrapper `bin/ai-memory.ps1`** — the Docker-Desktop wrapper; has had+ marker-boundary handling). This is where the cold-start flake lives.+- **PowerShell wrapper `bin/ai-memory.ps1`**: the Docker-Desktop wrapper. It has hadPowerShell 5.1-specific crashes (redirected native stderr becoming a terminating error,fixed with a localized probe). PS 5.1 behavior is Windows-only.-- **Detached hook-drain process launch** — `hook_drain_process.rs` detaches the background- drainer differently on Windows vs the Unix `setsid` path.+- **Detached hook-drain process launch**: `hook_drain_process.rs` detaches the background+ drainer differently on Windows than on the Unix `setsid` path.- **Assorted `#[cfg(windows)]` in** `install_hooks`, `install_mcp`, `render_shared`, `run`(exec-form quoting, single-command hook strings), and `packaging::slow` tests.### Already covered on Linux (do not pay Windows time for these)-- Every **injected-error** unit test (`from_raw_os_error(32|33)`, the sharing-violation+- Every injected-error unit test (`from_raw_os_error(32|33)`, the sharing-violationretry) compiles and runs on Linux and macOS today.-- The **POSIX hook bundle** (`tests/hooks/test_lib.sh`) runs across four awks on Linux in+- The POSIX hook bundle (`tests/hooks/test_lib.sh`) runs across four awks on Linux in`ci.yml`'s `hooks-shell` job. Only the suite's *PowerShell branch* needs a nativeinterpreter.-- All **path-normalization logic that is lexical** (not OS-dependent) — the code- deliberately normalizes lexically rather than via `fs::canonicalize` (a documented+- All path-normalization logic that is lexical (not OS-dependent). The code+ deliberately normalizes lexically instead of via `fs::canonicalize` (a documentedWindows/macOS divergence), so that logic is testable on Linux.-The practical size of the real-Windows-only surface: **two Rust concerns** (file-locking /+The real-Windows-only surface comes down to **two Rust concerns** (file-locking /NTFS-index / sharing-violation, and the libgit2 path-resolution fallback + verbatim/UNCpath casing) plus **the PowerShell layer** (hook transport + `bin/ai-memory.ps1` + thePowerShell half of the shell suite). Everything else is either injected-and-Linux-covered-or lexical. That is a small, well-bounded target — which is what makes a local VM loop-worthwhile rather than over-engineered.+or lexical. Because the target is small and well bounded, a local VM loop is+worthwhile and not over-engineered.## Options-Setup complexity, one-time and per-run cost, resources, **Windows licensing**, **security-posture (esp. public-repo / fork-PR exposure)**, maintenance, the coverage each gives-against the surface above, and how each integrates with `windows.yml`.+Each option is assessed on setup complexity, one-time and per-run cost, resources, Windows+licensing, security posture (especially public-repo / fork-PR exposure), maintenance, the+coverage it gives against the surface above, and how it integrates with `windows.yml`.### Option A — `dockur/windows` VM on marvin, for **local on-demand** runs@@ -138,45 +138,45 @@ Run a Windows guest as a KVM/QEMU VM inside a Docker container on marvin(`dockur/windows`), driven from the Linux host by a `bin/`-style helper: bring the VM up,sync the repo in (bind-mounted `/shared` → drive `Z:` in the guest, or RDP/SSH), run`cargo test --workspace --all-targets` + the PowerShell hook suite, report, tear down.-`windows-latest` stays exactly as it is (nightly + label + pre-release), catching drift.+`windows-latest` stays exactly as it is (nightly + label + pre-release) and catches drift.-- **Setup complexity:** Medium one-time. `dockur/windows` boots a full Windows via an- automated unattended install; access via web viewer (port **8006**), **RDP** (3389), and+- **Setup complexity:** Medium, one-time. `dockur/windows` boots a full Windows via an+ automated unattended install, with access via a web viewer (port **8006**), **RDP** (3389), anda **`/shared`** host bind-mount that appears as **`Z:`** inside Windows. One-timeprovisioning: install the Rust 1.95 toolchain, Git, and (native) PowerShell in the guest,- then snapshot the disk image so subsequent boots reuse it.+ then snapshot the disk image so later boots reuse it.- **Resources on marvin:** Needs `/dev/kvm` (marvin has it). dockur defaults to 2 cores /4 GB / 64 GB; Win11 realistically wants ≥4 GB and several cores for a tolerable `cargo`- build. marvin's 32 cores / ~2.6 TB free absorb this trivially, and the VM can be given+ build. marvin's 32 cores / ~2.6 TB free absorb this easily, and the VM can be given8–16 cores to beat a shared GitHub runner on link time.-- **Cost/time:** One-time first boot is *minutes* (image pull + retail ISO download +- unattended install). Per-run after provisioning: a warm VM plus an incremental+- **Cost/time:** The one-time first boot takes *minutes* (image pull + retail ISO download ++ unattended install). Per run after provisioning, a warm VM plus an incremental`cargo test` should land far under the ~1000s `windows-latest` figure, because (a) thecache lives on a local disk (no ~10x slow cache *restore* over the network) and (b) wecan throw more cores at linking. Exact numbers must be measured on marvin (see Open- questions) — the dockur README publishes no benchmark.-- **Licensing (address honestly):** dockur downloads **retail** consumer ISOs (Win 10/11- Pro) and installs them **unactivated**. That is **not** covered by any evaluation-license- grant — it is the same posture as any unactivated retail install, best described as- **gray-area / unlicensed**. The cleanly-licensed path is to point dockur at a **Windows+ questions); the dockur README publishes no benchmark.+- **Licensing:** dockur downloads **retail** consumer ISOs (Win 10/11+ Pro) and installs them **unactivated**. No evaluation-license grant covers that; it is+ the same posture as any unactivated retail install, best described as+ **gray-area / unlicensed**. The cleanly licensed path is to point dockur at a **WindowsServer** or **Windows Enterprise evaluation** ISO (Server eval = full-featured **180days**, re-armable up to 6×; client Enterprise eval = **90 days**) via `VERSION=<ISO URL>`or a bind-mounted `/custom.iso`, and re-provision when the window lapses. **Recommendationfor this project: use a Windows Server (or Enterprise) evaluation ISO, not the defaultretail Win11 download**, so the local loop is licensed for testing. (Sources below.)-- **Security posture:** **Best of the VM options.** Nothing here is a CI runner reachable+- **Security posture:** Best of the VM options. Nothing here is a CI runner reachableby fork PRs. It runs only when the maintainer or the agent invokes it, on a trustedbranch, on the maintainer's own box. The public-repo / fork-PR arbitrary-code risk that- sinks Option B **does not apply**.-- **Maintenance:** Re-provision on eval-window expiry and on toolchain bumps; keep a- snapshot. Modest.+ rules out Option B **does not apply**.+- **Maintenance:** Modest. Re-provision on eval-window expiry and on toolchain bumps, and+ keep a snapshot.- **Coverage vs the surface:** **Full.** Real NTFS file-index + sharing violations, reallibgit2 path-resolution fallback, real verbatim/UNC + drive-letter casing, real- PowerShell transport and `bin/ai-memory.ps1` under a native interpreter. Everything the+ PowerShell transport and `bin/ai-memory.ps1` under a native interpreter. That is everything theenumerated surface needs.- **Integration with `windows.yml`:** **Supplement / local-only.** Keep `windows.yml`as-is for drift detection; the VM becomes the *fast* pre-merge and mandatory pre-release- path (dispatch `windows.yml` on the RC SHA still happens — belt and suspenders).+ path (dispatching `windows.yml` on the RC SHA still happens, as a second safeguard).### Option B — Self-hosted GitHub Actions Windows runner on marvin (dockur or dedicated VM)@@ -190,7 +190,7 @@ marvin) and point `windows.yml`'s `runs-on` at it.workflow."* The secure-use reference goes further: self-hosted runners "should almostnever be used for public repositories." A fork PR is exactly the case we *want* Windowsfeedback on, and it is exactly the attack vector.-- **Mitigations exist but are load-bearing and easy to get wrong:** never run fork+- **Mitigations exist, but everything depends on them and they are easy to get wrong:** never run fork`pull_request` on the self-hosted runner (reserve it for `push`/`schedule`/`workflow_dispatch` on trusted refs); require approval for outside contributors; use**ephemeral / just-in-time runners** (at most one job, then destroyed) so one PR cannot@@ -198,14 +198,14 @@ marvin) and point `windows.yml`'s `runs-on` at it.disposable. Even with all of that, a single misconfiguration (or a future`pull_request_target`/`workflow_run` mistake) exposes marvin to arbitrary code from theinternet.-- **Setup/maintenance:** Highest — runner registration + auto-reset ephemeral tooling ++- **Setup/maintenance:** Highest: runner registration, auto-reset ephemeral tooling, andkeeping the isolation invariants true forever, on top of the same VM provisioning as- Option A. Licensing: same retail-vs-eval issue as Option A.-- **Coverage:** Same *full* Windows coverage as Option A (it's the same VM), but reached- through a CI runner instead of a local invocation — which only *adds* the fork-PR risk- without adding coverage over Option A.-- **Verdict:** **Not acceptable for this public repo.** The one thing it buys over Option A- — "Windows results appear automatically on a fork PR" — is precisely the thing GitHub+ Option A. Licensing has the same retail-vs-eval issue as Option A.+- **Coverage:** The same *full* Windows coverage as Option A (it's the same VM), but reached+ through a CI runner instead of a local invocation. That only *adds* the fork-PR risk+ and adds no coverage over Option A.+- **Verdict:** **Not acceptable for this public repo.** The one thing it buys over Option A,+ "Windows results appear automatically on a fork PR", is precisely what GitHubwarns against, and Option A already gives the maintainer the fast local loop safely. Thefork-PR *feedback* need is better served by keeping GitHub-hosted `windows-latest` (whichGitHub licenses and isolates) for that case.@@ -214,108 +214,107 @@ marvin) and point `windows.yml`'s `runs-on` at it.- **`cargo build --target x86_64-pc-windows-gnu`** (MinGW-w64) and**`x86_64-pc-windows-msvc` via `cargo-xwin`** produce Windows binaries from Linux and- prove the code **compiles and links** for the target — this catches `#[cfg(windows)]`+ prove the code **compiles and links** for the target. This catches `#[cfg(windows)]`build breaks, missing imports, and ABI/link errors *cheaply, per merge, on Linux*.- **What it does NOT do:** cross-compiling proves nothing about whether tests *pass* onreal Windows. Running the cross-built test binaries under **Wine** is possible but**cannot be trusted** for this project's surface. Wine is a compatibility layer, not anemulator, and specifically:- **PowerShell** does not run reliably on Wine (64-bit PowerShell stack-overflows;- community wrappers shim to PowerShell *Core*, not real Windows PowerShell) — so the+ community wrappers shim to PowerShell *Core*, not real Windows PowerShell), so theentire PowerShell hook/transport surface is untestable under Wine.- - **NTFS case-folding** — Wine uses the host FS (case-sensitive on Linux); it does not+ - **NTFS case-folding**: Wine uses the host FS (case-sensitive on Linux) and does notreproduce NTFS case-insensitive-but-preserving semantics. Our drive-letter/UNC casingtests would be invalid.- **Win32 file-locking / sharing-violation** semantics (`ERROR_LOCK_VIOLATION`,- `ERROR_SHARING_VIOLATION`) are incomplete/best-effort in Wine — our drain-lock and+ `ERROR_SHARING_VIOLATION`) are incomplete/best-effort in Wine, so our drain-lock andatomic-write retry behavior cannot be validated.- **libgit2 verbatim/`\\?\` path handling** is a Win32 kernel path-parsing feature Winedoes not faithfully reproduce.-- **Verdict:** Genuinely useful as a **cheap per-merge build gate** (add a Linux job that+- **Verdict:** Useful as a **cheap per-merge build gate** (add a Linux job thatcross-builds the Windows target so a `#[cfg(windows)]` compile break is caught in ~8-minCI instead of at release). **Wine is not a runtime replacement** for any part of the- enumerated surface — it is at best a thin, unreliable extra that must never gate+ enumerated surface; at best it is a thin, unreliable extra that must never gatecorrectness. Treat cross-compile as a supplement to Option A, and treat Wine as- out-of-scope.+ out of scope.### Option D — Keep `windows-latest`, just harden (the do-less baseline)Status quo plus more flake-hardening: keep the label gate + nightly + pre-release-dispatch, keep widening the timing tolerances (the 60s connect deadline, relaxed eval-gate+dispatch, and keep widening the timing tolerances (the 60s connect deadline, relaxed eval-gatetimeouts) as flakes surface.-- **Cost/complexity/security/licensing:** Zero new infrastructure; GitHub licenses and+- **Cost/complexity/security/licensing:** Zero new infrastructure. GitHub licenses andisolates Windows for us; no `/dev/kvm`, no VM, no fork-PR exposure.-- **Coverage:** Full real-Windows coverage (it *is* real Windows) — this is the correctness+- **Coverage:** Full real-Windows coverage (it *is* real Windows). This is the correctnessfloor every other option is measured against.- **What it does not fix:** the ~1000s round trip, the ~10x-slow cache restore, thelabel-gating + fork-approval friction, and the reactive per-flake patching. Theiteration loop stays slow, and Windows-sensitive work stays painful to develop.-- **Verdict:** the honest baseline. It must **stay** (for drift + licensed fork-PR+- **Verdict:** the baseline. It must **stay** (for drift + licensed fork-PRcoverage), but on its own it does not deliver the "fast local loop" the problem asks for.### Options summary| Option | Setup | Per-run vs ~1000s | Resources | Licensing | Security (public repo / fork PR) | Coverage vs surface | Role vs `windows.yml` ||---|---|---|---|---|---|---|---|-| A — dockur VM, local on-demand | Medium (1× provision + snapshot) | Much faster (local cache, more cores) — measure | `/dev/kvm`, ~8–16 cores / ≥8 GB on marvin | Gray-area if retail; **licensed if Server/Enterprise eval ISO** | **Low** — not a runner; runs only when invoked on trusted branch | **Full** | **Supplement / local-only** |-| B — self-hosted runner | Highest (runner + ephemeral + isolation) | Fast | Same as A | Same as A | **Unacceptable** — GitHub warns against on public repos; fork PRs = arbitrary code | Full (same VM) | Would replace `runs-on` — **do not** |-| C — cross-compile (+Wine) | Low (add Linux job) | N/A (build only) | Linux CI | Fine (no Windows guest) | Fine | **Build-only**; Wine runtime **untrustworthy** for this surface | **Supplement** (per-merge build gate) |-| D — harden `windows-latest` | None | ~1000s (unchanged) | GitHub-hosted | GitHub-licensed | Fine | Full | **Keep** (baseline / drift / fork-PR) |+| A: dockur VM, local on-demand | Medium (1× provision + snapshot) | Much faster (local cache, more cores); measure | `/dev/kvm`, ~8–16 cores / ≥8 GB on marvin | Gray-area if retail; **licensed if Server/Enterprise eval ISO** | **Low**: not a runner; runs only when invoked on trusted branch | **Full** | **Supplement / local-only** |+| B: self-hosted runner | Highest (runner + ephemeral + isolation) | Fast | Same as A | Same as A | **Unacceptable**: GitHub warns against on public repos; fork PRs = arbitrary code | Full (same VM) | Would replace `runs-on`; **do not** |+| C: cross-compile (+Wine) | Low (add Linux job) | N/A (build only) | Linux CI | Fine (no Windows guest) | Fine | **Build-only**; Wine runtime **untrustworthy** for this surface | **Supplement** (per-merge build gate) |+| D: harden `windows-latest` | None | ~1000s (unchanged) | GitHub-hosted | GitHub-licensed | Fine | Full | **Keep** (baseline / drift / fork-PR) |## Recommendation**Adopt Option A + Option C's build gate; keep Option D; reject Option B.**-1. **Primary fast loop — `dockur/windows` on marvin, local on-demand (Option A).** A+1. **Primary fast loop: `dockur/windows` on marvin, local on-demand (Option A).** A`bin/`-style helper brings up a provisioned Windows VM, syncs the working tree in(bind-mount → `Z:`), runs `cargo test --workspace --all-targets` + the PowerShell hooksuite, and reports. This is the fast pre-merge and mandatory pre-release verificationpath, run by the maintainer/agent on a trusted box. **Provision it from a Windows Server(or Enterprise) evaluation ISO**, not the default retail Win11 download, to keep the loopcleanly licensed for testing.-2. **Cheap per-merge build gate — cross-compile (Option C).** Add a Linux CI job that+2. **Cheap per-merge build gate: cross-compile (Option C).** Add a Linux CI job thatcross-builds the Windows target (`x86_64-pc-windows-gnu`, and/or `-msvc` via`cargo-xwin`) so a `#[cfg(windows)]` *compile* break is caught in the ~8-minute Linux- gate instead of at release time. This does **not** replace runtime Windows testing and+ gate instead of at release time. This does **not** replace runtime Windows testing, andWine is explicitly **not** used to fake it.3. **Keep `windows-latest` label-gated + nightly + pre-release (Option D).** It remains the- drift catcher (toolchain/dependency changes no code touches), the licensed-and-isolated+ drift catcher (toolchain/dependency changes no code touches), the licensed and isolatedpath for **fork-PR** Windows feedback, and the mandatory green-before-tag gate on the RC- SHA (per AGENTS.md). The local loop is *belt*; `windows.yml` stays as *suspenders*.+ SHA (per AGENTS.md). The local loop is the belt; `windows.yml` stays as the suspenders.4. **Do NOT put a self-hosted runner on the public repo (reject Option B).** GitHubexplicitly warns against it; fork PRs could run arbitrary code on marvin. The only thing- it adds over Option A is automatic Windows results on fork PRs — a need already met,- safely, by keeping `windows-latest`.+ it adds over Option A is automatic Windows results on fork PRs, a need that keeping+ `windows-latest` already meets safely.-Why this shape: the real-Windows-only surface is small and bounded (file-locking / NTFS /+The reasoning: the real-Windows-only surface is small and bounded (file-locking / NTFS /sharing-violation, libgit2 path fallback + verbatim/UNC casing, and the PowerShell layer),-so a **local** VM that the maintainer already has the hardware for gives full, faithful-coverage at iteration speeds `windows-latest` can't match — *without* importing the-fork-PR attack surface or making a Windows license the thing standing between a-contributor and a merge.+so a **local** VM on hardware the maintainer already has gives full, faithful+coverage at iteration speeds `windows-latest` can't match. It does so *without* importing the+fork-PR attack surface or putting a Windows license between a contributor and a merge.## Phased adoption planEach phase is independently shippable and reversible; nothing removes `windows.yml`.-- **Phase 0 — Cheap win, no VM.** Add a Linux CI job that cross-compiles the Windows target+- **Phase 0: cheap win, no VM.** Add a Linux CI job that cross-compiles the Windows targetto gate `#[cfg(windows)]` compile breaks per merge (Option C build-only). Document thatWine is *not* used for correctness. Low risk, immediate value.-- **Phase 1 — Provision the VM manually.** Stand up `dockur/windows` on marvin from a+- **Phase 1: provision the VM manually.** Stand up `dockur/windows` on marvin from a**Server/Enterprise evaluation ISO**; install Rust 1.95 + Git + native PowerShell;snapshot. **Measure** warm `cargo test --workspace --all-targets` + PowerShell suite time- and compare to the ~1000s `windows-latest` figure. This measurement decides whether+ and compare it to the ~1000s `windows-latest` figure. This measurement decides whetherPhase 2 is worth automating (it almost certainly is, given local cache + more cores).-- **Phase 2 — The `bin/` helper.** Script "up → sync tree (`/shared`→`Z:`) → `cargo test` ++- **Phase 2: the `bin/` helper.** Script "up → sync tree (`/shared`→`Z:`) → `cargo test` +hook suite → report → down" as a `bin/`-style command, mirroring existing helpers(`bin/ai-memory`, `bin/deploy`, `bin/release`). Keep it read/report only; never let itmutate the host tree. Document it in `docs/windows.md` and reference it from AGENTS.md'spre-release Windows step as the *fast* pre-check that precedes the mandatory`windows.yml` dispatch on the RC SHA.-- **Phase 3 — Optional convenience.** A one-command "run the Windows surface before I push+- **Phase 3: optional convenience.** A one-command "run the Windows surface before I pusha platform-sensitive change" wrapper, and (if desired) a scheduled *local* run on marvin- that emails/logs drift — still **not** a GitHub runner, still trigger-only, no fork+ that emails/logs drift. This is still **not** a GitHub runner, still trigger-only, with no forkexposure.At every phase, `windows.yml` stays: nightly, `windows` label, `workflow_dispatch`, and@@ -329,22 +328,21 @@ green-before-tag on the RC SHA.snapshotted VM so only the incremental `cargo test` is on the critical path.- **Eval-window churn.** Server eval = 180 days (re-armable ~6×), Enterprise client eval =90 days. Re-provisioning is a recurring chore; a documented snapshot + rebuild runbook- keeps it cheap. Risk if forgotten: the guest starts hourly-shutting-down mid-run.+ keeps it cheap. Risk if forgotten: the guest starts shutting down hourly mid-run.- **Retail-ISO temptation.** dockur's *default* is a retail Win11 download (unactivated =gray-area). The plan must explicitly pin an eval ISO; a future contributor copying adockur quickstart could silently reintroduce the retail default. Call this out in`docs/windows.md`.- **PowerShell parity.** The guest must run the *Windows PowerShell 5.1* (and/or the pinned- PowerShell the hook lib targets) that `bin/ai-memory.ps1` and the hook suite exercise —- the 5.1-specific redirected-stderr crash we already fixed shows version matters. Ensure+ PowerShell the hook lib targets) that `bin/ai-memory.ps1` and the hook suite exercise.+ The 5.1-specific redirected-stderr crash we already fixed shows the version matters. Ensurethe eval edition ships the right PowerShell, or install it during provisioning.- **Nested-virt / GPU / `/dev/kvm` availability.** Confirmed available on marvin per thebrief, but the helper should fail loudly with a clear message if `/dev/kvm` is absent(e.g., run from a container without the device passed through).- **Drift the local loop can't see.** A local snapshot pins toolchain/dependency versions;`windows-latest`'s nightly is what catches *upstream* drift the snapshot would hide. This- is the reason `windows.yml` must stay, not be replaced — the two are complementary, not- redundant.+ is why `windows.yml` must stay instead of being replaced: the two complement each other.- **Cross-compile ABI gap.** `-gnu` cross-builds catch most compile breaks, but the shippedrelease is MSVC (`ai-memory.exe`); a `-gnu`-only gate could miss an MSVC-specific break.If Phase 0 uses `-gnu` for simplicity, note the gap and consider `cargo-xwin` (`-msvc`)@@ -354,10 +352,10 @@ green-before-tag on the RC SHA.External sources (fetched as untrusted data; facts only):-- **dockur/windows** — image, access ports (8006 web / 3389 RDP / `/shared`→`Z:`),+- **dockur/windows**: image, access ports (8006 web / 3389 RDP / `/shared`→`Z:`),`VERSION` editions, defaults (2 cores / 4 GB / 64 GB), `/dev/kvm` requirement:https://github.com/dockur/windows-- **Windows licensing for VMs / testing** — Server evaluation (180 days, re-armable):+- **Windows licensing for VMs / testing**: Server evaluation (180 days, re-armable):https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2022 ·https://learn.microsoft.com/en-us/answers/questions/2128668/vm-licensing-under-windows-server-evaluation ;Windows 11 Enterprise dev VMs (90-day eval, cannot activate):@@ -392,16 +390,16 @@ The study above proposed Phase 1 as "provision the VM manually and **measure**,the dockur README publishes no benchmark and that number decides whether Phase 2 is worthautomating." That measurement has now been done on marvin (AMD Ryzen AI Max 395, 32cores, 62 GB, `/var` on btrfs, SELinux enforcing). It also proved Phase 0 on a real-runner. Findings, kept honest because they change the recommendation:+runner. The findings change the recommendation:### Phase 0 (cross-compile gate): shipped, works`cargo xwin build --workspace --all-targets --target x86_64-pc-windows-msvc` is green both-locally (57s warm) and on `ubuntu-latest` (9m1s cold / **3m19s warm** — under the ~8-min-gate, and parallel to the existing slowest job). It compiles and links the whole workspace-for Windows — bundled SQLite and vendored libgit2 under clang-cl, `windows-sys`/`winapi-util`,-and every `#[cfg(windows)]` **test** binary — so a Windows-only compile/link break is caught-per-merge on Linux. Landed as the `windows cross-build (msvc)` job in `ci.yml`. Gotcha for+locally (57s warm) and on `ubuntu-latest` (9m1s cold / **3m19s warm**, under the ~8-min+gate and parallel to the existing slowest job). It compiles and links the whole workspace+for Windows (bundled SQLite and vendored libgit2 under clang-cl, `windows-sys`/`winapi-util`,+and every `#[cfg(windows)]` **test** binary), so a Windows-only compile/link break is caught+per merge on Linux. It landed as the `windows cross-build (msvc)` job in `ci.yml`. Gotcha forfuture maintainers: the target's `rust-std` must be added to the **1.95** toolchain that`rust-toolchain.toml` pins, not `stable`, or the build fails with "can't find crate for`core`"; the job pins `toolchain: "1.95"` for that reason.@@ -411,61 +409,61 @@ future maintainers: the target's `rust-std` must be added to the **1.95** toolchWindows Server 2025 (Evaluation, licence-clean 180-day) installs and boots to an autologondesktop under `dockurr/windows` on marvin, and the **full suite passes green**, includingthe `#[cfg(windows)]` tests executing on native Windows (PowerShell transport, NTFS atomic-writes, libgit2 path fallback). Measured, GNU toolchain (rustc 1.95 + MinGW gcc 16.1),+writes, libgit2 path fallback). Measured with the GNU toolchain (rustc 1.95 + MinGW gcc 16.1),8 vCPU / 8 GB:| Run | Time (CoW on) | Time (CoW off) | Notes ||---|---|---|---|| Cold full (`test --workspace --all-targets`, first compile) | **2408s (~40m)** | **3146s (~52m)** | 400 crates, all tests ok; cold is compile-bound, CoW makes no reliable difference (run variance) |-| Warm full (nothing changed, test execution only) | **1600s (~27m)** | **1193s (~20m)** | 0 recompiled — pure *test-execution*; CoW-off is ~25% faster here |+| Warm full (nothing changed, test execution only) | **1600s (~27m)** | **1193s (~20m)** | 0 recompiled, pure *test-execution*; CoW-off is ~25% faster here || Warm single crate (`test -p ai-memory-hooks`) | **73s** | — | the realistic focused-iteration cost || GitHub `windows-latest` full run (from the study) | **~1000s** | — | warm cache |-The decisive, unwelcome result: **the warm full suite is slower than `windows-latest`-(~1000s)** whether or not CoW is disabled, and it is dominated by *test execution*, not-compilation (0 crates recompiled). The suite is I/O-bound — SQLite, `git2`/libgit2, and-fsync-heavy atomic-write tests — and marvin's `/var` is **btrfs**, so the QEMU raw disk-image pays copy-on-write cost on every fsync. So the "iteration measured in tens of seconds"-premise does **not** hold for a full-suite run on this box; the local VM's honest value is-(a) **on-demand focused iteration** (one crate in ~1 min, no ~17-min GitHub round trip and+The decisive and unwelcome result: **the warm full suite is slower than `windows-latest`+(~1000s)** whether or not CoW is disabled, and the time goes to *test execution*, not+compilation (0 crates recompiled). The suite is I/O-bound (SQLite, `git2`/libgit2, and+fsync-heavy atomic-write tests), and marvin's `/var` is **btrfs**, so the QEMU raw disk+image pays copy-on-write cost on every fsync. The "iteration measured in tens of seconds"+premise therefore does **not** hold for a full-suite run on this box. The local VM is+useful for (a) **on-demand focused iteration** (one crate in ~1 min, no ~17-min GitHub round trip andno fork-approval friction) and (b) full local Windows coverage before a push. It is not afaster full gate.The CoW optimisation was tried (fresh install onto a `chattr +C` storage dir, so the raw-image is created nodatacow): it cut the I/O-bound warm run by **~25% (1600s → 1193s)**,-confirming fsync-on-CoW was the execution bottleneck — but not enough to beat+image is created nodatacow). It cut the I/O-bound warm run by **~25% (1600s → 1193s)**,+confirming fsync-on-CoW was the execution bottleneck, but that was not enough to beat`windows-latest`. Cold got slightly *worse* (compile-bound; within run-to-run variance).-Verdict unchanged: keep Phase 0 + `windows.yml`; the VM is a **focused-iteration / full+The verdict is unchanged: keep Phase 0 + `windows.yml`. The VM is a **focused-iteration / fulllocal coverage** tool, not a faster full gate, and does not justify Phase 2 full-suiteautomation on this hardware. Measured 2026-09-22 on marvin (Server 2025 Eval, GNUtoolchain, 8 vCPU / 8 GB, Defender disabled).### Host-specific accommodations dockur needs on marvin (none anticipated by the study)-1. **SELinux `:Z`/`:z` on every bind mount** — otherwise `/storage` is not writable.-2. **`security_opt: [label:disable]`** — SELinux blocks `/dev/net/tun`, so dockur silently+1. **SELinux `:Z`/`:z` on every bind mount**, otherwise `/storage` is not writable.+2. **`security_opt: [label:disable]`**: SELinux blocks `/dev/net/tun`, so dockur silentlyfalls back to user-mode (passt) networking, which breaks the `\\host.lan\Data` sharedfolder and custom port-forwarding. With the label disabled it gets real NAT.-3. **The `/oem` `RunOnce` auto-provision did not fire** — the VM reached an autologon+3. **The `/oem` `RunOnce` auto-provision did not fire.** The VM reached an autologondesktop but the first-logon provisioning never ran. Driving it via the **QEMU monitor**- (`sendkey` to type a launch command, `screendump` to read the screen — the monitor lives+ (`sendkey` to type a launch command, `screendump` to read the screen; the monitor livesat `/dev/shm/monitor.sock` inside the container) worked reliably and is the mechanism a- `bin/` helper should use, not `RunOnce`.-4. **Microsoft Defender must be disabled/excluded** — real-time scanning *quarantined build+ `bin/` helper should use instead of `RunOnce`.+4. **Microsoft Defender must be disabled/excluded.** Real-time scanning *quarantined buildartifacts mid-build* and killed cargo (silent early exit). `Set-MpPreference-DisableRealtimeMonitoring $true` + exclusions for `.cargo`/`.rustup`/the build dir fixedit. This is the same Defender-exclusion guidance AGENTS.md already gives for Windows dev,here promoted from "slow" to "correctness-breaking".5. **Isolation flakiness**: `test -p ai-memory-wiki` hung/crawled when run alone (file-watcher- / libgit2 tests) although the same tests passed inside the `--all-targets` run — a+ / libgit2 tests) although the same tests passed inside the `--all-targets` run. This is areliability caveat to investigate before relying on per-crate runs for that crate.### Revised recommendation-- **Phase 0 — ship** (done). Unambiguous win, no Windows infra.-- **Phase 1/2 — feasible, but re-measure with CoW disabled before automating.** The VM gives+- **Phase 0: ship** (done). A clear win with no Windows infra.+- **Phase 1/2: feasible, but re-measure with CoW disabled before automating.** The VM givesfaithful full Windows coverage on demand, but is not a faster full gate on btrfs. If Phase 2- proceeds, the `bin/` helper must: apply fixes 1–2 in compose, disable Defender (4), drive+ proceeds, the `bin/` helper must apply fixes 1–2 in compose, disable Defender (4), driveprovisioning + runs via the QEMU monitor (3), and prefer focused per-crate invocations.- **Option D (`windows.yml`) stays** the authoritative, licence-clean, fork-safe pre-tag gate- regardless — the VM is *belt*, `windows.yml` remains *suspenders*.+ regardless. The VM is the belt; `windows.yml` remains the suspenders.diff --git a/docs/design-yolo-safety-ai-jail.md b/docs/design-yolo-safety-ai-jail.mdindex 342075ca..95593cbf 100644--- a/docs/design-yolo-safety-ai-jail.md+++ b/docs/design-yolo-safety-ai-jail.md@@ -15,14 +15,14 @@ every tool call with no confirmation. Three gaps:1. **No warning.** A user types `--yolo` and the agent is immediatelyunsupervised, with no reminder of what that means or a way to back out.2. **No sandbox nudge.** ai-jail exists precisely to contain an unsupervised- agent, but nothing connects the two — the user must remember to type+ agent, but nothing connects the two: the user must remember to type`ai-jail ai-memory run …` themselves.3. **Claude still pauses.** Even with `--dangerously-skip-permissions`, ClaudeCode still prompts on explicit `permissions.ask` rules and on its owncommand-safety checks (e.g. "Contains brace with quote character (expansionobfuscation)"), so an "unattended" yolo run can stall. Anthropic documents- these under "Actions no mode auto-approves": no permission mode — including- `bypassPermissions` — skips them.+ these under "Actions no mode auto-approves": no permission mode, including+ `bypassPermissions`, skips them.## Non-goals@@ -39,7 +39,7 @@ every tool call with no confirmation. Three gaps:### 1. Yolo warning prompt (all OSes)Before `apply_yolo` runs in `run.rs`, when `--yolo` is requested **and** the-session is interactive (`stdin` and `stderr` are both terminals — the same+session is interactive (`stdin` and `stderr` are both terminals, the samegate the native-session picker already uses) **and** we are not already insideai-jail:@@ -63,7 +63,7 @@ The offer appears only when accepting it can actually work`ai-jail --dry-run` preflight then applies ai-jail's own backend trust and localconfiguration checks before the offer is shown. It never appears on Windows,where ai-jail is unsupported, even if a file named `ai-jail` happens to be on `PATH`.-When ai-jail is not usable there is no question at all — the run proceeds+When ai-jail is not usable there is no question at all; the run proceedsdirectly after the §1 warning. The re-exec runs the exact path this checkresolved, never a bare `ai-jail` re-looked-up through `PATH` (which missed a`~/.local/bin`-only install after the user had already accepted).@@ -90,8 +90,8 @@ ai-jail --network --agent-state --no-save-config \`ai-jail cmd --network` means the sandbox or the child. `ai-memory run`shares flag names with ai-jail (`--env`, …), so without the separator aforwarded `run claude --env GH_TOKEN=…` aborted the launch. After `--`- ai-jail passes everything to the wrapped command verbatim — from ai-jail- 2.4.2; earlier releases' guard ignores `--` (despite its error text+ ai-jail passes everything to the wrapped command verbatim, starting with ai-jail+ 2.4.2. Earlier releases' guard ignores `--` (despite its error textsuggesting it), so a colliding forwarded flag still fails there. ai-memoryemits the separator regardless, as the documented contract.@@ -102,8 +102,8 @@ ai-jail --network --agent-state --no-save-config \- **`--network` (not `--allow-host`).** ai-jail only adds `--unshare-net` whennetwork is *off* (`bwrap.rs`: `if !network_enabled { push("--unshare-net") }`),so `--network` shares the host network namespace and the host-side ai-memory- server on `127.0.0.1:49374` — which the managed run and the agent's hooks- both need — is reachable. Filtered `--allow-host` uses a private netns with a+ server on `127.0.0.1:49374`, which the managed run and the agent's hooks+ both need, is reachable. Filtered `--allow-host` uses a private netns with aCONNECT proxy for *external* hosts only, so it would cut the loopback serveroff; we deliberately do not use it. This is soft protection (full egress),which is acceptable: the agent needs outbound network for its own model API@@ -133,7 +133,7 @@ observable surface, per OS:- **macOS:** seatbelt has no UTS namespace, so the hostname is unchanged.ai-jail forces `PS1` to begin with `(jail) ` on both backends; on macOS thatis the available signal. Weaker (a shell can overwrite `PS1`), but it only- ever *suppresses* the warning — a false negative just shows the warning+ ever *suppresses* the warning: a false negative just shows the warningagain inside the jail, which is safe; a false positive is unlikely becauseai-memory is exec'd directly by ai-jail, not through an interactive shellthat would reset `PS1`.@@ -141,7 +141,7 @@ observable surface, per OS:the ai-jail offer is never shown.When detected as already jailed, both the warning and the ai-jail offer are-skipped and the run proceeds directly — a user who typed+skipped and the run proceeds directly, so a user who typed`ai-jail ai-memory run … --yolo` sees no extra friction.### 4. Claude "true yolo" (opt-in, all OSes; recommended only under ai-jail)@@ -160,7 +160,7 @@ What it deliberately does **not** claim to do, verified against Claude Code*union* with the user/project/local scopes instead of replacing them, so anempty `ask` array there is a no-op (earlier releases injected one). To runwithout those pauses, remove the `ask` rules from your own settings; `deny`- rules never pause — they block — so keeping them costs no interruptions.+ rules never pause (they block), so keeping them costs no interruptions.- It cannot skip Claude Code's built-in command-safety checks.- Earlier releases also set three `CLAUDE_CODE_DISABLE_*RM*` environmentvariables. Claude Code reads none of them (they are absent from its binary@@ -173,9 +173,9 @@ Off by default. **`--true-yolo` is a superset of `--yolo`**: it implies`--yolo` (the §1 warning, the §2 offer, and each harness's dangerous-modemapping) and adds the Claude extras above, so passing both is redundant butharmless. For every non-Claude harness it is simply interchangeable with-`--yolo`. Like `--yolo`, it is recognized anywhere after `run` — including-after native arguments (`run claude --model opus --true-yolo`), where clap-leaves it in the native argv — and never forwarded to the harness as an+`--yolo`. Like `--yolo`, it is recognized anywhere after `run`, including+after native arguments (`run claude --model opus --true-yolo`) where clap+leaves it in the native argv, and it is never forwarded to the harness as anunknown flag.The `claude_true_yolo` config key only upgrades a launch that is already`--yolo`/`--true-yolo`; on its own it never turns an ordinary run into a@@ -186,7 +186,7 @@ permission-bypassing one without the warning.ai-jail keeps credentials and host devices out by default and exposes eachthrough a boolean toggle (`--X` / `--no-X`). A jailed agent that cannot reach`gh`, the AWS CLI, or an SSH key often cannot finish the task, so the user-picks what the jail mounts — from the CLI or an interactive checklist — and+picks what the jail mounts, from the CLI or an interactive checklist, andpressing Enter does the friendly thing.**CLI.** Two wrapper flags on `ai-memory run` (and recognized after native@@ -201,7 +201,7 @@ arguments too, like `--yolo`; neither ever reaches the harness):`--jail` needs `=` for its list (`require_equals`), so `ai-memory run --jailclaude` keeps `claude` as the harness. It works with or without `--yolo` and-in non-interactive runs too — that is how a script gets a jailed run. When+in non-interactive runs too; that is how a script gets a jailed run. Whenai-jail is not usable on the host (§2) it fails with an error instead ofsilently running unjailed. An explicit `--jail` re-execs *before* the managedrun is prepared, so no lease is opened and cancelled outside the jail. Inside@@ -210,7 +210,7 @@ ai-jail (§3) both flags are ignored: no nesting, no error.There are deliberately **no bare `--github`-style flags** on `ai-memory run`.They would collide with harness-native flags of the same name (Claude Codehas its own `--worktree`), and wrapper flags after the harness name are-stripped from the native argv — a bare `--worktree` meant for Claude would be+stripped from the native argv: a bare `--worktree` meant for Claude would besilently taken away from it. The single namespaced `--jail=` list has no suchcollision.@@ -233,7 +233,7 @@ collision.Why these defaults: every credential is pre-checked when present because auser who keeps `gh` or AWS credentials on the machine almost always wants theagent able to use them, and a box shown only when the path exists never mounts-nothing. The credential rows check the exact path ai-jail mounts — `GH_CONFIG_DIR`+nothing. The credential rows check the exact path ai-jail mounts. `GH_CONFIG_DIR`is not consulted, because ai-jail 2.5.0 mounts `~/.config/gh` regardless. SSHis shown but left unchecked for an HTTPS remote, since only an SSH `origin`makes `git push` need it. `worktree` is pre-checked in a linked worktree,@@ -242,11 +242,11 @@ capabilities stay off: they widen the sandbox without being needed for theusual task.**Semantics: an explicit selection is exact.** ai-jail's own config can-enable toggles too — the trusted global `~/.ai-jail` may turn on, say,+enable toggles too: the trusted global `~/.ai-jail` may turn on, say,`docker`. So whenever the user makes a selection, ai-memory states everyvisible row explicitly, and ai-jail's CLI flags override its config:-- **Interactive checklist:** every row the user saw is passed as marked —+- **Interactive checklist:** every row the user saw is passed as marked:checked `--X`, unchecked `--no-X` (`marked_choices`). An unchecked`[ ] Docker socket` stays off even when `~/.ai-jail` enables it; thechecklist is what-you-see-is-what-you-get.@@ -274,7 +274,7 @@ ai-memory. When a regular file `.ai-jail` exists there:| bare `--jail` | smart-default rows on; the rest left to ai-jail config | no toggles: the file is loaded as-is || `--jail=LIST` | exactly the list; unnamed visible rows `--no-X` | the same exact list, on top of the file (CLI flags override config in ai-jail) |-A project file is untrusted — it lives in the repository the agent works on.+A project file is untrusted because it lives in the repository the agent works on.ai-jail lets it disable capabilities but never enable credentials, `docker`,`agent_state`, and the like, so ai-memory must not pre-check anything on itsbehalf either, and an untrusted repository must not be able to steer the@@ -291,7 +291,7 @@ into the project config and writes `.ai-jail` back. Without the flag, thefirst jailed run would persist ai-memory's transient flags (`--network`,`--agent-state`, the checked credentials) into the user's repository; everylater run would then find a project file, skip the checklist, and silently-lose the credential mounts a project file cannot enable — and ai-jail would+lose the credential mounts a project file cannot enable, and ai-jail wouldwarn that the project file's `agent_state` is ignored because it weakens thebaseline sandbox. `--no-save-config` sits in the baseline next to `--network`/ `--agent-state`, before the `--`, guarded by the same `--help` detection (both@@ -370,7 +370,7 @@ directly.## Code shape- `ai-memory-workstream/src/jail.rs` (new): pure, OS-aware, dependency-injected- detection + command construction — `usable_ai_jail(os, lookup)`,+ detection + command construction: `usable_ai_jail(os, lookup)`,`inside_ai_jail(env, hostname)`, `build_ai_jail_invocation(exe, args, env_names)`.Pure functions so the OS branches and the argv/env assembly are unit-testedwithout a sandbox.diff --git a/docs/desktop/antigravity.md b/docs/desktop/antigravity.mdindex 86640a4d..6ca19381 100644--- a/docs/desktop/antigravity.md+++ b/docs/desktop/antigravity.md@@ -7,13 +7,13 @@## Product shape (as of 2026-10)-Google ships **Antigravity 2.0** (the desktop agent app), the **Antigravity-IDE** (standalone Windsurf-derived editor), the **Antigravity CLI** (`agy`),+Google ships Antigravity 2.0 (the desktop agent app), the Antigravity+IDE (standalone Windsurf-derived editor), the Antigravity CLI (`agy`),and an SDK, all documented at <https://antigravity.google/docs/>. The localmachine runs the IDE (`/usr/share/applications/antigravity-ide.desktop`,`antigravity-ide-url-handler.desktop`, Electron/VS Code profile at-`~/.config/Antigravity IDE/` — `User/globalStorage/state.vscdb`,-`workspaceStorage`, `languagepacks.json` confirm the VS Code fork layout).+`~/.config/Antigravity IDE/`, where `User/globalStorage/state.vscdb`,+`workspaceStorage` and `languagepacks.json` confirm the VS Code fork layout).`~/.gemini/` exists locally with `antigravity-cli/` and `antigravity-ide/`subdirs plus `config/`, `settings.json`, `oauth_creds.json`.@@ -54,13 +54,13 @@ Official: <https://antigravity.google/docs/hooks/>**`transcriptPath`**, `artifactDirectoryPath`, `modelName`, plus`toolCall`, `stepIdx`, etc. Handlers are shell commands with a `timeout`(default 30s).-- **Crucially, the payload names the transcript file**:+- The payload names the transcript file:`<app_data_dir>/brain/<conversationId>/.system_generated/logs/transcript.jsonl`where `<app_data_dir>` = `~/.gemini/antigravity` (2.0),`~/.gemini/antigravity-cli` (CLI), **`~/.gemini/antigravity-ide` (IDE)**.**Consequence for ai-memory:** `install-hooks --agent antigravity-cli` writes-`~/.gemini/config/hooks.json`, which the **IDE also loads** — so global+`~/.gemini/config/hooks.json`, which the IDE also loads, so globalcapture likely already extends to IDE sessions, with the IDE distinguishableby its `transcriptPath` prefix (`antigravity-ide/brain/...`). Differences tohandle: no `SessionStart`/`SessionEnd` events (session boundaries must be@@ -107,7 +107,7 @@ needed for capture conclusions.)- <https://antigravity.google/docs/mcp/>, <https://antigravity.google/docs/hooks/>,<https://antigravity.google/docs/cli/overview/>- Local: `~/.config/Antigravity IDE/` (VS Code-fork layout,- `User/globalStorage/state.vscdb` — no MCP keys configured yet),+ `User/globalStorage/state.vscdb`; no MCP keys configured yet),`~/.gemini/` (config root shared by CLI + IDE),`/usr/share/applications/antigravity-ide*.desktop`- ai-memory repo: `docs/mcp-install.md` (Antigravity CLI section)diff --git a/docs/desktop/capture-and-dedup.md b/docs/desktop/capture-and-dedup.mdindex 65775f0b..8bb64678 100644--- a/docs/desktop/capture-and-dedup.md+++ b/docs/desktop/capture-and-dedup.md@@ -23,8 +23,8 @@ apps; Cursor is the exception") needs revision after this research:### What the MCP server can see server-side (all apps)ai-memory *is* the MCP server, so on any MCP-connected app we observe:-tool calls (name + args + results), call timestamps, and — through the MCP-session — nothing else. We do **not** see chat turns, prompts, or model+tool calls (name + args + results) and call timestamps, and nothing else+through the MCP session. We do **not** see chat turns, prompts, or modeloutput. Practical consequences:- Server-side observation is enough for **usage telemetry** (which tools an@@ -39,18 +39,18 @@ output. Practical consequences:Now concrete per app (paths verified locally unless noted):-- `~/.claude/projects/<munged-cwd>/<session>.jsonl` — Claude Code-family+- `~/.claude/projects/<munged-cwd>/<session>.jsonl`: Claude Code-familytranscripts (desktop Code tab included). Watcher optional: hooksalready cover it; a watcher adds value only for hookless flows (e.g.user disabled hooks).-- `~/.codex/sessions/**/rollout-*.jsonl` + `~/.codex/history.jsonl` — Codex.-- `~/.gemini/antigravity{,-ide,-cli}/brain/<conversationId>/**/transcript.jsonl`- — Antigravity (per hooks doc; not yet verified locally — no IDE chats on- the machine).-- Zed native agent: internal DB in Zed's data dir — **do not** build on it+- `~/.codex/sessions/**/rollout-*.jsonl` + `~/.codex/history.jsonl`: Codex.+- `~/.gemini/antigravity{,-ide,-cli}/brain/<conversationId>/**/transcript.jsonl`:+ Antigravity (per hooks doc; not yet verified locally because there are no IDE+ chats on the machine).+- Zed native agent: internal DB in Zed's data dir. **Do not** build on it(unstable, version-fragile); rely on ACP agents instead.-- Claude Chat tab / hosted ChatGPT / Grok Bot: **no local store** — watcher- class does not apply.+- Claude Chat tab / hosted ChatGPT / Grok Bot: **no local store**, so the+ watcher class does not apply.A watcher/importer remains the importer-envelope (`/hook/batch`) patternfrom `companions/ai-memory-importer`; keep it out of core (RFC #878 rule).@@ -81,7 +81,7 @@ Verified mechanics (see `claude-desktop.md`):session metadata for filtering.The desktop-side record (`~/.config/Claude/claude-code-sessions/.../local_*.json`) provides `title`, `createdAt`, account/org and the- `local_* ↔ cliSessionId` mapping if we want to enrich/label — but it is+ `local_* ↔ cliSessionId` mapping if we want to enrich/label, but it isan implementation detail of a closed app; treat as optional hint, nota dependency (it can move without notice).2. **Bridging id exposure**: the desktop id (`local_*`) never reaches@@ -90,15 +90,15 @@ Verified mechanics (see `claude-desktop.md`):`entrypoint: claude-desktop` + `hostSessionId` while a process runs. Notarchival; useful at most for a tray app's "current desktop sessions" view.- The cc-socks Unix sockets (`/run/user/<uid>/cc-socks/<pid>.sock`) are an- internal IPC of the closed app — **do not** build on them.+ internal IPC of the closed app; **do not** build on them.### CodexOne Codex host per user: CLI + desktop + IDE extension share `~/.codex`(config **and** session rollout store). Session ids are the rollout UUIDs;`(agent=codex, session_id)` is already correct, and a session started in-the desktop app is distinguishable only by content/absence of TUI markers —-no id-level split. Hosted ChatGPT/Codex-cloud sessions are cloud ids that+the desktop app is distinguishable only by content/absence of TUI markers,+with no id-level split. Hosted ChatGPT/Codex-cloud sessions are cloud ids thatnever touch the local store; if cloud-side capture ever matters it arrivesvia export/API, mapped as a *separate* agent kind (e.g. `codex-cloud`) toavoid double-counting with local rollouts.@@ -110,7 +110,7 @@ for the same conversation; the surface is distinguishable by the`transcriptPath` prefix (`antigravity-ide/` vs `antigravity-cli/` vs`antigravity/`). Map to ai-memory: `agent=antigravity`, session_id =`conversationId`, cwd = `workspacePaths[0]` (fallback: last path; the-payload has no scalar `cwd`). Hook set lacks SessionStart/SessionEnd —+payload has no scalar `cwd`). The hook set lacks SessionStart/SessionEnd, soderive session boundaries from first/last observation timestamps perconversation id (ai-memory sessions are already built from observationstreams, so a Stop-hook flush marker is enough; optional).@@ -121,7 +121,7 @@ Dedup key stays `(agent, session_id)`; **surface variants of one agentecosystem that share an id space stay one agent kind** (claude-code coversCLI+desktop; codex covers CLI+desktop+IDE ext; antigravity coversIDE+CLI+2.0). Where a closed app keeps its own id (desktop `local_*`),-never invent capture from it — treat as metadata only.+never invent capture from it; treat it as metadata only.## 3. Open questions@@ -134,7 +134,7 @@ never invent capture from it — treat as metadata only.3. Claude Desktop Chat tab: is any local conversation cache planned(desktop extensions/plugins evolve fast)? Re-check quarterly; notbuildable today.-4. Grok Bot `mcpBoxServers` entry format — reverse-engineer only if the+4. Grok Bot `mcpBoxServers` entry format: reverse-engineer only if theproduct gains traction with users; no docs.5. Scope for scratch-workspace sessions: single `desktop/claude-scratch`pool vs per-scratch projects (product decision; affects auto-scope).diff --git a/docs/desktop/chatgpt-desktop.md b/docs/desktop/chatgpt-desktop.mdindex a350276e..84a6dc57 100644--- a/docs/desktop/chatgpt-desktop.md+++ b/docs/desktop/chatgpt-desktop.md@@ -2,27 +2,27 @@> Research for RFC #878. Two different things get called "ChatGPT desktop"> in late 2026; both are covered. The local machine has no official ChatGPT-> desktop app — its `ChatGPT.desktop` is an Omarchy webapp launcher-> (`Exec=omarchy-launch-webapp https://chatgpt.com/`), i.e. a browser-> wrapper, not the app. Research therefore rests on official docs.+> desktop app. Its `ChatGPT.desktop` is an Omarchy webapp launcher+> (`Exec=omarchy-launch-webapp https://chatgpt.com/`), a browser wrapper+> rather than the app, so this research rests on official docs.## 1. The ChatGPT desktop app (Codex host) — official-As of 2026-10 OpenAI ships **one desktop app** that hosts both ChatGPT-(chat/Work) and **Codex** (coding agent): "Download ChatGPT for macOS,+As of 2026-10 OpenAI ships one desktop app that hosts both ChatGPT+(chat/Work) and Codex (coding agent): "Download ChatGPT for macOS,Windows, or Linux… Choose ChatGPT or Codex. In ChatGPT, use the toggle abovethe composer to select Chat or Work" (<https://developers.openai.com/codex/app>).All MCP/hook mechanics of this app are covered in-[`codex-desktop.md`](codex-desktop.md) — summary:+[`codex-desktop.md`](codex-desktop.md). In summary:- **MCP: yes** (stdio + streamable HTTP), configured in`~/.codex/config.toml` `[mcp_servers.*]` or Settings → MCP servers; configshared with Codex CLI and IDE extension.- **Lifecycle hooks: yes** (Codex hooks framework, `~/.codex/hooks.json`) on- the Codex side; whether hooks fire for Chat-mode conversations is **not- documented** — Chat/Work conversations are cloud-thread-shaped and the+ the Codex side. Whether hooks fire for Chat-mode conversations is **not+ documented**: Chat/Work conversations are cloud-thread-shaped, and thehooks doc speaks of Codex sessions/turns. Treat Chat-mode auto-capture as- unavailable; Codex-mode capture as available (verify live).+ unavailable and Codex-mode capture as available (verify live).- **Transcripts**: Codex-mode sessions land in `~/.codex/sessions/`rollout JSONL on the Codex host. Chat-mode conversations are cloud-stored;no local transcript store documented.@@ -33,7 +33,7 @@ All MCP/hook mechanics of this app are covered inCodex clients can also connect directly to MCP servers… ChatGPT webdoesn't read local Codex configuration files"(<https://developers.openai.com/codex/extend/mcp>).-- The extension surface is **plugins**: MCP server (+ optional UI, events,+- The extension surface is plugins: MCP server (+ optional UI, events,skills) published to the ChatGPT plugin directory(<https://developers.openai.com/plugins>). Auth is OAuth/Sign-in-with-ChatGPT; no stdio/local servers in hosted Chat.@@ -41,7 +41,7 @@ All MCP/hook mechanics of this app are covered in(<https://developers.openai.com/codex/enterprise/apps-and-connectors>).- **Implication for ai-memory:** an ai-memory *plugin* (hosted remote MCPpointing at a user-run server) is the only sanctioned path into hosted- ChatGPT chat — same shape as RFC #878's "remote-only connectors"+ ChatGPT chat, which matches RFC #878's "remote-only connectors"conclusion. A local loopback ai-memory server cannot be reached fromhosted Chat; a tunnel (e.g. OpenAI's "Secure MCP Tunnel" docs exist at<https://developers.openai.com/api/docs/guides/secure-mcp-tunnels>) or a@@ -52,7 +52,7 @@ All MCP/hook mechanics of this app are covered inThe official app now supports Linux(<https://developers.openai.com/codex/linux/linux-app>); historically Linuxusers only had web/wrappers (as on this machine). The AUR `codex-desktop`-family (distsystem fork) predates/parallels official Linux availability —+family (distsystem fork) predates/parallels official Linux availability;see [`codex-desktop.md`](codex-desktop.md).## Capture / dedup notes@@ -72,4 +72,4 @@ see [`codex-desktop.md`](codex-desktop.md).<https://developers.openai.com/plugins>,<https://developers.openai.com/api/docs/guides/secure-mcp-tunnels>- Local: `~/.local/share/applications/ChatGPT.desktop` (Omarchy webapp- launcher — proves no official app installed here)+ launcher, which shows no official app is installed here)diff --git a/docs/desktop/claude-desktop.md b/docs/desktop/claude-desktop.mdindex e2c6cfca..0d63f9e3 100644--- a/docs/desktop/claude-desktop.md+++ b/docs/desktop/claude-desktop.md@@ -10,7 +10,7 @@ One Electron app, three tabs: **Chat** (claude.ai consumer chat), **Cowork**(long-running agentic work / Dispatch), **Code** (Claude Code sessions).Officially on macOS and Windows; **Linux is an official beta** (apt/.deb forUbuntu 22.04+ and Debian 12+ only; other distributions are pointed at the-CLI — <https://code.claude.com/docs/en/desktop>,+CLI; see <https://code.claude.com/docs/en/desktop>,<https://code.claude.com/docs/en/desktop-linux>). On Linux, Cowork runs itstasks inside a QEMU/KVM virtual machine the app hosts. The local machine runs theLinux build (`/usr/share/applications/com.anthropic.Claude.desktop`,@@ -24,28 +24,28 @@ app reads the same settings files as the CLI"The desktop app ships and auto-manages its own Claude Code CLI copy:`~/.config/Claude/claude-code/2.1.280/claude` (+ `.payload`, `.verified`-marker files) — found locally.+marker files), found locally.## MCP client supportTwo distinct MCP surfaces:-1. **Chat tab (consumer app)** — local stdio MCP servers via the classic+1. **Chat tab (consumer app)**: local stdio MCP servers via the classicconfig file `claude_desktop_config.json` under an `mcpServers` key, plusremote HTTPS connectors configured in-app ("Connectors"). Config paths:- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`- Windows: `%APPDATA%\Claude\claude_desktop_config.json` (or the MSIX- AppContainer path — ai-memory's `install-mcp --client claude-desktop`+ AppContainer path; ai-memory's `install-mcp --client claude-desktop`already detects both)- Linux: `~/.config/Claude/claude_desktop_config.json` (**verified- locally**; the file exists with a `preferences` object — the Linux beta+ locally**; the file exists with a `preferences` object, so the Linux betareuses the same file). `docs/mcp-install.md` documents it, and`install-mcp --client claude-desktop` writes it on Linux.- Source: <https://modelcontextprotocol.io/quickstart/user> (mac/winpaths), local file inspection, ai-memory `docs/mcp-install.md`.- Local MCP logs: `~/Library/Logs/Claude/mcp*.log` (mac),- `%APPDATA%\Claude\logs` (win) — same source.-2. **Code tab (Claude Code host)** — the same MCP configuration the CLI uses:+ `%APPDATA%\Claude\logs` (win), same source.+2. **Code tab (Claude Code host)**: the same MCP configuration the CLI uses:`~/.claude.json` (local/user scope), `.mcp.json` (project scope), settingsfiles, and **plugins** (a plugin can bundle MCP servers + hooks; thedesktop app has a plugin browser). Connectors in the prompt "+" menu are@@ -55,7 +55,7 @@ Two distinct MCP surfaces:in-process `type: "sdk"` reserved for host applications such as thedesktop app (<https://code.claude.com/docs/en/mcp>).-Remote per-session MCP servers also appear in desktop session state —+Remote per-session MCP servers also appear in desktop session state:`~/.config/Claude/claude-code-sessions/<account>/<org>/local_*.json` containsa `remoteMcpServersConfig` list (verified locally; two remote servers incl.Anthropic's own Docs MCP).@@ -70,10 +70,10 @@ tab's extension surface.## Lifecycle hooks / capture surface- **No push hooks in the Chat/Cowork tabs.** Capture for consumer-chat- conversations stays model-discretion (memory tool calls) — unchanged from+ conversations stays model-discretion (memory tool calls), unchanged fromRFC #878's conclusion.- **The Code tab is full Claude Code**, and it reads the user's- `~/.claude/settings.json` — where ai-memory's hooks are already installed+ `~/.claude/settings.json`, where ai-memory's hooks are already installed(verified locally: `hooks.SessionStart` →`ai-memory ... hook --event session-start --agent claude-code ...`).Therefore **ai-memory already captures desktop Code sessions today**, keyed@@ -101,18 +101,18 @@ real and observable on this machine. Mechanism, from local artifacts:1. **Every running `claude` process registers a live descriptor** at`~/.claude/sessions/<pid>.json` (verified locally). Fields include:- - `sessionId` — the Claude Code session UUID+ - `sessionId`: the Claude Code session UUID- `entrypoint: "claude-desktop"` when desktop-spawned- - `hostSessionId: "local_<uuid>"` — the desktop app's own session id+ - `hostSessionId: "local_<uuid>"`: the desktop app's own session id- `cwd`, `version`, `peerProtocol`, `peerFeatures`(`notify_idle`, `reply_across_default_dirs`, `artifact_yield`)- - `messagingSocketPath: /run/user/<uid>/cc-socks/<pid>.sock` — a Unix+ - `messagingSocketPath: /run/user/<uid>/cc-socks/<pid>.sock`: a Unixsocket used for cross-surface messaging between desktop and CLI peers.2. **Desktop-side session records** live at`~/.config/Claude/claude-code-sessions/<account>/<org>/local_<uuid>.json`(verified locally) and carry the join key:- `sessionId: "local_<uuid>"` (desktop id)- - `cliSessionId: "<CLI session UUID>"` — **the same UUID as the+ - `cliSessionId: "<CLI session UUID>"`: **the same UUID as the`~/.claude/projects/.../<uuid>.jsonl` transcript**- plus `cwd`, `originCwd`, `model`, `permissionMode`, `title`,`remoteMcpServersConfig`, timestamps.@@ -126,7 +126,7 @@ real and observable on this machine. Mechanism, from local artifacts:computer, again continuing the same session.4. **Deep links**: `claude-cli://` URL scheme handled by`~/.local/share/applications/claude-code-url-handler.desktop` →- `claude --handle-uri %u` (verified locally) — how other apps hand a+ `claude --handle-uri %u` (verified locally). This is how other apps hand asession to Claude Code.5. Desktop's "work across sessions" surface only sees sessions the desktopapp itself runs (local/SSH/WSL), **not** terminal CLI or VS Code extension@@ -136,7 +136,7 @@ real and observable on this machine. Mechanism, from local artifacts:### What ai-memory's `(agent, session_id)` key sees- A desktop Code session and the CLI session it came from (via- `--resume`/`/desktop`) are **one session id** — capture dedups naturally.+ `--resume`/`/desktop`) are **one session id**, so capture dedups naturally.- A desktop Code session started without a folder is a *new* CLI session(new UUID) whose cwd is a fresh scratch workspace; ai-memory sees it as aclaude-code session in an auto-named project derived from the scratchdiff --git a/docs/desktop/codex-desktop.md b/docs/desktop/codex-desktop.mdindex 7d0674ce..0f955544 100644--- a/docs/desktop/codex-desktop.md+++ b/docs/desktop/codex-desktop.md@@ -10,21 +10,21 @@OpenAI has merged Codex into the **ChatGPT desktop app**: "Download ChatGPTfor macOS, Windows, or Linux… Choose ChatGPT or Codex"-(<https://developers.openai.com/codex/app>). Officially supported on-**macOS, Windows, and Linux** (docs at+(<https://developers.openai.com/codex/app>). It is officially supported on+macOS, Windows, and Linux (docs at<https://developers.openai.com/codex/linux/linux-app>). The app is Electron;the local machine runs the community Linux repackaging`codex-desktop-linux` (AUR `codex-desktop-linux` / originally`ilysenko/codex-desktop-linux`, maintained here under the `distsystem` fork)-which **converts the upstream macOS `Codex.dmg` into Linux .deb/.rpm/pacman-packages** — i.e. the app itself is closed; the wrapper is open.+which converts the upstream macOS `Codex.dmg` into Linux .deb/.rpm/pacman+packages. The app itself is closed; the wrapper is open.Local artifacts: `/usr/share/applications/codex-desktop.desktop`(`Exec=... /usr/bin/codex-desktop`), Electron profiles at `~/.config/Codex`(release) and `~/.config/Codex (Dev)` (dev build), `~/.config/codex-desktop`only holds `electron-flags.conf`.-The desktop app drives the **same Codex core** as the CLI — the open-source+The desktop app drives the same Codex core as the CLI. The open-sourcerepo contains `codex-rs/app-server`, `app-server-protocol`,`app-server-daemon`, `app-server-transport` crates(`~/Projects/_desktop-research/codex-research/codex-rs/`), and docs at@@ -39,10 +39,10 @@ and **share MCP configuration for the same Codex host**"(<https://developers.openai.com/codex/extend/mcp>):- Config file: `~/.codex/config.toml`, `[mcp_servers.<name>]` tables;- project scope `.codex/config.toml` (trusted projects only). **Verified- locally**: `~/.codex/config.toml` already contains+ project scope `.codex/config.toml` (trusted projects only). Verified+ locally: `~/.codex/config.toml` already contains`[mcp_servers.ai-memory] url = "http://192.168.0.90:49374/mcp"` (remote- streamable HTTP — works with the desktop app, no Node/npx needed).+ streamable HTTP, which works with the desktop app without Node/npx).- Desktop app GUI: Settings → MCP servers → Add server (STDIO or StreamableHTTP); `/mcp` in the composer lists servers.- CLI: `codex mcp add <name> -- <command>` / `codex mcp list`.@@ -51,7 +51,7 @@ and **share MCP configuration for the same Codex host**"`http_headers_helper`), OAuth incl. CIMD/DCR and ChatGPT session auth.ai-memory's loopback HTTP + optional bearer token maps directly onto this.- Server `instructions` field is read as server-wide guidance (keep first- 512 chars self-contained) — relevant for how ai-memory's tool-routing+ 512 chars self-contained). This matters for how ai-memory's tool-routingguidance is surfaced in Codex.## Lifecycle hooks — full Claude-Code-style model, in core@@ -64,16 +64,16 @@ Codex has a native lifecycle-hooks framework`PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`,`SubagentStart`, `SubagentStop`, `Stop`, `Interrupt`.- Config: `~/.codex/hooks.json` (or inline `[hooks]` in `config.toml`),- repo `<repo>/.codex/hooks.json`, plugin-bundled hooks. **Verified- locally**: ai-memory already writes `~/.codex/hooks.json` with+ repo `<repo>/.codex/hooks.json`, plugin-bundled hooks. Verified+ locally: ai-memory already writes `~/.codex/hooks.json` withSessionStart/UserPromptSubmit/PreToolUse/PostToolUse command hooks calling`ai-memory hook --event ... --agent codex --server-url ...`.- Hook stdin includes `session_id`, `transcript_path`, `cwd`,- `hook_event_name`, `model` — everything ai-memory's capture needs.+ `hook_event_name`, and `model`, which covers everything ai-memory's capture needs.- Trust review: non-managed hooks must be trusted once (`/hooks` in theTUI); trust is recorded against the hook's hash.- Handlers can be `command` or `mcp_tool` (a lifecycle event can call a tool- on a connected MCP server — an interesting future capture path).+ on a connected MCP server, a possible future capture path).**Verified 2026-10-08 (see `verification-2026-10.md`):** the desktop appspawns `codex app-server` from the `codex` on `PATH` with@@ -90,7 +90,7 @@ prompt with the ai-memory hooks in place has not been run yet.`~/.codex/sessions/YYYY/MM/DD/rollout-*-<session-uuid>.jsonl` (verifiedlocally), plus `~/.codex/history.jsonl` (prompt history keyed by-`session_id`). Same store for CLI and (expected) desktop sessions — the+`session_id`). CLI and (expected) desktop sessions share this store because thedesktop app is the same Codex host.## Session bridging@@ -99,15 +99,15 @@ No CLI↔desktop bridge equivalent to Claude's `/desktop` is documented.CLI and desktop are separate conversation lists over the same host config;ChatGPT web/mobile/cloud surfaces are cloud-side and do not read localconfig ("ChatGPT web doesn't read local Codex configuration files",-<https://developers.openai.com/codex/extend/mcp> — web section). `dots`+<https://developers.openai.com/codex/extend/mcp>, web section). `dots`(persistent agents) are cloud-orchestrated; enterprise hooks for dots areremote MCP hooks, not local command hooks.## Open-source status-- `openai/codex` (Apache-2.0): CLI + `codex-rs` core, **hooks crate,- codex-mcp, app-server crates** — open.-- The ChatGPT/Codex **desktop app**: closed (Electron); Linux build only via+- `openai/codex` (Apache-2.0): CLI + `codex-rs` core, hooks crate,+ codex-mcp, and app-server crates are open.+- The ChatGPT/Codex desktop app: closed (Electron); Linux build only viathe community DMG-conversion project (`ilysenko/codex-desktop-linux`,packaged here by `distsystem`).diff --git a/docs/desktop/cursor.md b/docs/desktop/cursor.mdindex f2ae9473..70b03abb 100644--- a/docs/desktop/cursor.md+++ b/docs/desktop/cursor.md@@ -17,7 +17,7 @@ Config and agent data live in `~/.cursor/` (`projects/<workspace>/`,ai-memory already supports Cursor: `install-mcp --client cursor`(`~/.cursor/mcp.json` or `.cursor/mcp.json`) and `install-hooks --agentcursor` (`~/.cursor/hooks.json`, flat `{"version": 1, "hooks": {...}}`-schema) — see `docs/mcp-install.md#cursor`.+schema); see `docs/mcp-install.md#cursor`.## Lifecycle hooks — which files run where@@ -102,21 +102,27 @@ events replayed to the same server got their capture-policy summaries(`tool non-file`). Giving the Cursor event a real `cwd` did not change it,and `Shell` classifies as a non-file tool, so neither is the cause; theremaining differences are `tool_output` instead of `tool_response`, the-camelCase `hook_event_name`, and no `cwd` query parameter. Not yet-isolated; a failing test is the next step.+camelCase `hook_event_name`, and no `cwd` query parameter. The cause was+neither: Cursor was missing from the tool-capture agent list+(`closed_tool_agent` in `crates/ai-memory-hooks/src/payload.rs`, plus the+capture-policy name/input mapping), so its tool events fell through to the+legacy path. Fixed in 2.6.3 (8bb89e28); Cursor tool events now get the same+family title and output summary as Claude Code's.## Open questions (live tests)1. The native `.cursor/hooks.json` payloads (only the Claude-format copyhas been observed) and the `cwd` a conversation gets once a workspace- folder is open — needs a prompt inside the probe workspace.+ folder is open. This needs a prompt inside the probe workspace.2. ~~What the `empty-state-draft` session start does on the server.~~Measured 2026-10-08 by replaying the spooled event against a scratchserver: it creates one `cursor` session with no `cwd` in the`default/scratch` project, and every later launch (a new ingest key, thesame placeholder id) adds another `session-start` observation to that- same session. Clutter, not loss; whether to drop it is a product call.+ same session. That adds clutter but loses nothing; whether to drop it is a+ product call.3. Whether the `cursor-agent` CLI loads the Claude-format hooks (it needs`cursor-agent login` here first).-5. Why Cursor tool events reach the store with empty bodies (above).4. Whether a workspace window imports Claude MCP servers.+5. ~~Why Cursor tool events reach the store with empty bodies.~~ Fixed in+ 2.6.3 (above).diff --git a/docs/desktop/desktop-landscape.md b/docs/desktop/desktop-landscape.mdindex cf83a671..a648197c 100644--- a/docs/desktop/desktop-landscape.md+++ b/docs/desktop/desktop-landscape.md@@ -18,35 +18,35 @@## Highlights vs RFC #878's assumptions (what changed)1. **The capture picture improved for two ecosystems:**- - **Claude Desktop's Code tab is literally Claude Code** — hooks in+ - **Claude Desktop's Code tab is Claude Code itself**: hooks in`~/.claude/settings.json` already capture it (`agent=claude-code`;a folderless session gets a scratch-workspace cwd). RFC #878 classedClaude Desktop wholesale as "no hook/event surface"; that is true ofthe Chat tab, and Cowork is unverified.- **Antigravity (IDE included) has first-class lifecycle hooks** with- `transcriptPath` in every payload — a full auto-capture target the RFC+ `transcriptPath` in every payload, a full auto-capture target the RFCdidn't evaluate (it listed Cursor as the only hook-bearing desktoptarget).2. **Codex is now the ChatGPT desktop app** with shared `~/.codex` config:one `install-mcp`/`install-hooks` write serves CLI + desktop + IDEextension (desktop-app hook firing needs one live verification).3. **Official Linux desktop builds now exist** for Claude Desktop (beta) and- the ChatGPT/Codex app — ai-memory's `docs/mcp-install.md` "Linux: not+ the ChatGPT/Codex app, so ai-memory's `docs/mcp-install.md` "Linux: notofficially distributed" note for claude-desktop is stale.4. **Grok Bot is a Cursor product** (not xAI) with embedded MCP support but- no public docs — opportunistic, not plannable.+ no public docs, so support is opportunistic and cannot be planned.5. Remote/streamable-HTTP MCP is now the norm across Codex/Antigravity/Zed/- Claude(Code) — a loopback ai-memory HTTP server needs **no npx shims** on+ Claude(Code), so a loopback ai-memory HTTP server needs **no npx shims** onany researched app except legacy Claude-Desktop-Chat stdio config.## Ordered capture opportunity (auto-capture without new product code)-1. Claude Desktop Code tab — works today via existing hooks (verified).-2. Codex desktop — its engine fires the existing `~/.codex` hooks once+1. Claude Desktop Code tab: works today via existing hooks (verified).+2. Codex desktop: its engine fires the existing `~/.codex` hooks oncetrusted (verified); one in-app prompt pending.-3. Antigravity IDE — via existing `~/.gemini/config/hooks.json` (agent+3. Antigravity IDE: via existing `~/.gemini/config/hooks.json` (agentmapping/`workspacePaths` handling + verification needed).-4. Zed — via ACP/terminal agents' own hooks (nothing to build).-5. Chat tab / hosted ChatGPT / Grok Bot — model-discretion only (MCP tools);+4. Zed: via ACP/terminal agents' own hooks (nothing to build).+5. Chat tab / hosted ChatGPT / Grok Bot: model-discretion only (MCP tools);hosted ChatGPT additionally needs a published plugin to reach auser-run server at all.diff --git a/docs/desktop/grok-desktop.md b/docs/desktop/grok-desktop.mdindex 909aec28..ad8b2e89 100644--- a/docs/desktop/grok-desktop.md+++ b/docs/desktop/grok-desktop.md@@ -8,15 +8,15 @@## 1. Grok webapp launcher (local `Grok.desktop`)`~/.local/share/applications/Grok.desktop` →-`Exec=omarchy-launch-webapp https://grok.com/` — an Omarchy browser wrapper,-not a native app. Nothing to integrate beyond grok.com's own web features-(remote MCP support on grok.com is **unverified** — xAI docs were not-fetched; do not assume).+`Exec=omarchy-launch-webapp https://grok.com/`. This is an Omarchy browser+wrapper, not a native app, so there is nothing to integrate beyond grok.com's+own web features. Remote MCP support on grok.com is **unverified**: xAI docs+were not fetched, so do not assume it.## 2. Grok Bot — Cursor's desktop agent (native, closed)`/usr/share/applications/grok-bot.desktop` → `/usr/bin/grok-bot`, pacman-package `grok-bot-bin 0.66.0-1` (AUR; local install). Key verified facts:+package `grok-bot-bin 0.66.0-1` (AUR; local install). Verified facts:- **Distributed by Cursor**: the AUR PKGBUILD pulls`https://downloads.cursor.com/grokbot/stable/<commit>/linux/x64/grok-bot_<ver>_amd64.deb`;@@ -35,26 +35,26 @@ package `grok-bot-bin 0.66.0-1` (AUR; local install). Key verified facts:`mcpDisabledToolsByServerId`, …), and `~/.grokbot/settings.json` has`mcpBoxServers: []`, `mcpCustomInstructions`,`mcpCustomInstructionsByServerId`, `mcpDisabledToolsByServerId` keys- (empty — user hasn't configured any). "Box servers" suggests MCP servers- run inside Grok Bot's sandboxed "boxes". **No public official docs found**- (cursor.com product pages not fetched — Grok Bot appears to be- invite/rollout-gated); config format and whether stdio, remote, or both- are supported is **unverified**. Next step if pursued: add an MCP entry+ (empty, because the user hasn't configured any). "Box servers" suggests MCP+ servers run inside Grok Bot's sandboxed "boxes". **No public official docs+ found** (cursor.com product pages were not fetched; Grok Bot appears to be+ invite/rollout-gated). The config format, and whether stdio, remote, or both+ are supported, is **unverified**. Next step if pursued: add an MCP entryvia the app UI and diff `~/.grokbot/settings.json`.- **Local-exec daemon**: `~/.grokbot/local-exec-daemon.log`,`local-exec-supervisor.json`, `local-exec-daemon-credential.json`,- `gateway-descriptor.json` — the agent executes tasks locally through a- supervised daemon (relevant if we ever need to coexist with it; not an- integration surface).+ `gateway-descriptor.json`. The agent executes tasks locally through a+ supervised daemon. This matters only if we need to coexist with it; it is+ not an integration surface.- **No lifecycle-hook surface** documented or evident; no transcript storedocumented. Conversation data appears cloud-side (leveldb holds UI state- only). Capture options collapse to model-discretion via MCP tools — same- as RFC #878's closed-app bucket.+ only). Capture options collapse to model-discretion via MCP tools, the+ same as RFC #878's closed-app bucket.## 3. xAI official desktop appNot verified. No local install; no official docs fetched. Grok Build CLI-(xAI's coding CLI) is a *different* product — ai-memory already supports it+(xAI's coding CLI) is a *different* product, and ai-memory already supports it(`install-mcp --client grok`, `install-hooks --agent grok`, repo`docs/mcp-install.md`). Keep the two separate in any plan.@@ -69,5 +69,5 @@ inspected: the AUR PKGBUILD + local binary/asar strings.download URL, comments)- Local: `/opt/Grok Bot/resources/app.asar` (strings), `~/.grokbot/`,`~/.config/Grok Bot/`, `/usr/share/applications/grok-bot.desktop`-- ai-memory repo: `docs/mcp-install.md` (Grok Build CLI section — separate+- ai-memory repo: `docs/mcp-install.md` (Grok Build CLI section, a separateproduct)diff --git a/docs/desktop/installer-and-coexistence.md b/docs/desktop/installer-and-coexistence.mdindex fa06d02c..d205ac82 100644--- a/docs/desktop/installer-and-coexistence.md+++ b/docs/desktop/installer-and-coexistence.md@@ -7,7 +7,7 @@> (`companions/ai-memory-macos/README.md`), ai-memory repo layout> (`packaging/`, `crates/ai-memory-cli/src/server_profiles*`, hook runner> layout observed locally), and well-known behavior of Docker Desktop /-> Tailscale (pattern references — deep docs not fetched, treat as+> Tailscale (pattern references; deep docs not fetched, so treat as> directional).## 1. Tray-app implementation options@@ -18,12 +18,12 @@events). Linux note: tray mouse-move/enter events unsupported, but icon +context menu work (<https://v2.tauri.app/learn/system-tray/>).- **Bundling the Rust binary**: sidecar/external-binary support- (<https://v2.tauri.app/develop/sidecar/>) — the tray app can embed the+ (<https://v2.tauri.app/develop/sidecar/>), so the tray app can embed theexact pinned `ai-memory` release binary.- **Desktop-app table stakes as plugins**: `single-instance` (avoid twotrays), `autostart` (login launch), `updater` (signed updates),deep-linking (`ai-memory://`) (<https://v2.tauri.app/plugin/>).-- **Packaging matrix from one toolchain** — official distribute targets:+- **Packaging matrix from one toolchain**, with official distribute targets:Linux deb / rpm / AppImage / AUR / Flathub / Snap, macOS DMG + app bundle(+ pkg), Windows installer (NSIS/MSI) + Microsoft Store; per-OS signingguides (<https://v2.tauri.app/distribute/>).@@ -34,9 +34,9 @@- `tray-icon` (tauri-apps org, <https://docs.rs/tray-icon>) + `muda` menus;egui for the settings window. Lightest stack, no webview, one binary.-- Cost: we own everything Tauri gives for free — single-instance, updater,+- Cost: we own everything Tauri gives for free: single-instance, updater,signing/packaging pipelines, deep links. Only worth it if the UI stays- trivial (menu + one settings pane) — which the Swift companion's scope+ trivial (menu + one settings pane), which the Swift companion's scopesuggests it might.### Option C — keep Swift companion + add a Linux counterpart@@ -45,7 +45,7 @@LaunchAgent, data dir survives app replacement, philosophy: "wrapper, nota second operator console").- Linux: a counterpart would duplicate the service governance (systemd user- unit — templates already exist in `packaging/systemd/`) with a GTK/libadw+ unit; templates already exist in `packaging/systemd/`) with a GTK/libadwor Tauri menu. Two codebases for one product; the existing companionexplicitly defers notarization/Homebrew cask, so it has not reached thenon-dev bar yet either.@@ -62,7 +62,7 @@ here.| --- | --- | --- || macOS | `.dmg` (drag-install), `.pkg`, Homebrew cask | Gatekeeper: Developer ID + hardened runtime + notarize/staple (RFC #878 cost analysis stands); Swift companion currently ships un-notarized || Windows | NSIS or MSI (WiX) via Tauri; winget | MSIX optional; AppContainer path quirks for Claude Desktop config already handled by `install-mcp`; Authenticode signing (RFC #878: SignPath Foundation free for OSS) |-| Linux | `.deb`, `.rpm`, AppImage; AUR (we already ship AUR assets in `packaging/aur/`); Flatpak is **problematic** (sandbox vs loopback server + hook execution into arbitrary agent configs — needs portal work; defer) | systemd user unit from `packaging/systemd/`; sysusers/tmpfiles assets exist |+| Linux | `.deb`, `.rpm`, AppImage; AUR (we already ship AUR assets in `packaging/aur/`); Flatpak is **problematic** (sandbox vs loopback server + hook execution into arbitrary agent configs; needs portal work, so defer) | systemd user unit from `packaging/systemd/`; sysusers/tmpfiles assets exist |## 3. Coexistence with the existing CLI (the hard constraints)@@ -70,28 +70,28 @@ Ground truth from the repo/local machine:- **Data dir** holds wiki + SQLite + `config.toml` + spool + models:`~/.local/share/ai-memory` (Linux), `~/Library/Application Support/ai-memory`- (macOS — the Swift companion's documented default), `%LOCALAPPDATA%`+ (macOS, the Swift companion's documented default), `%LOCALAPPDATA%`(Windows). The desktop app MUST detect and reuse it, never fork a secondone silently.- **One writer, one server**: ai-memory's SQLite is single-writer-actor bydesign (repo invariants #2, #9). Two server processes on one data dir is- forbidden — so the tray app's first job is *detection*, not spawning:+ forbidden, so the tray app's first job is detection rather than spawning:1. Probe the configured/default server (`GET /admin/status` on the portfrom `config.toml` / default `127.0.0.1:49374`).2. Check the **`server_profiles` registry** (CLI:- `crates/ai-memory-cli/src/server_profiles.rs` — named profiles with+ `crates/ai-memory-cli/src/server_profiles.rs`: named profiles withurl + project roots + token, used by hooks via `--server-url`). On thismachine the hooks point at a LAN server (`--server-url- http://192.168.0.90:49374`) — the desktop app must respect that+ http://192.168.0.90:49374`), and the desktop app must respect thatinstead of assuming localhost.3. Only if no reachable server: offer (a) start bundled server as a- managed service (LaunchAgent/systemd user unit/Startup task — reuse+ managed service (LaunchAgent/systemd user unit/Startup task, reusing`packaging/` templates), or (b) connect to remote with URL+token.- **Hooks are decoupled from app bundles already**: hooks installed byai-memory invoke `~/.local/share/ai-memory/native-runner/ai-memory` (thenative-runner copy inside the data dir; verified in local`~/.claude/settings.json` and `~/.codex/hooks.json`). Replacing a desktop- app bundle therefore never rewrites hooks or breaks capture — preserve+ app bundle therefore never rewrites hooks or breaks capture. Preservethis invariant: **the tray app must not move or duplicate thenative-runner path**; at most refresh it with the user's consent.- **Version independence**: bundled binary (in the .app/resources) and any@@ -104,12 +104,12 @@ Ground truth from the repo/local machine:knows claude-desktop incl. MSIX paths, codex, antigravity-cli, zed, grok,…). The desktop app should call the same library code, show a checklistof detected apps, and write configs idempotently (preserve unrelated- servers — existing behavior).+ servers, as it already does).## 4. The "desktop users don't know Docker" constraintai-memory today is a self-contained Rust binary (bundled SQLite, vendored-libgit2) — **Docker is already optional** (`docs/install.md` ships native+libgit2), so **Docker is already optional** (`docs/install.md` ships nativepackages + systemd). The tray app completes that story:- Default path: bundled binary + local data dir + loopback bind + zero@@ -118,7 +118,7 @@ packages + systemd). The tray app completes that story:tray settings → written to `server_profiles` so hooks and MCP installspoint at the same remote.- Anti-goal: the tray app becoming an admin console. Keep the Swift- companion's rule — open `/web` and the config file; don't duplicate.+ companion's rule: open `/web` and the config file; don't duplicate.## 5. Comparable tools (pattern reference)@@ -132,12 +132,12 @@ packages + systemd). The tray app completes that story:the CLI is a symlink into the bundle. Pattern to copy: explicit"connected/backend state" tray affordance; CLI/daemon version skewtolerated by protocol.-- **Raycast**: tray-first launcher without a bundled background *service*- — mostly useful as UI scope reference (menu + extensions), not service- coexistence.+- **Raycast**: tray-first launcher without a bundled background service.+ It is mostly useful as a UI scope reference (menu + extensions), not for+ service coexistence.(These are well-known public behaviors; not re-verified against docs in-this pass — directional only.)+this pass, so treat them as directional only.)## 6. Open questionsdiff --git a/docs/desktop/plan.md b/docs/desktop/plan.mdindex 7d11a61e..9937bee8 100644--- a/docs/desktop/plan.md+++ b/docs/desktop/plan.md@@ -6,7 +6,7 @@## What the research changed vs the RFC-RFC #878's headline — "connection is solved, capture is the crux" — still+RFC #878's headline, "connection is solved, capture is the crux", stillholds, but two of its premises moved:1. **"Most desktop chat apps expose no hook/event surface"** is now false@@ -18,7 +18,7 @@ holds, but two of its premises moved:in the payload. The truly hookless set is now: Claude Desktop Chat tab,hosted ChatGPT chat, Grok Bot.2. **"Claude Desktop .mcpb bundle"** as the Phase-1 one-click route:- re-validated 2026-10-08 — Anthropic's support article presents `.mcpb`+ re-validated 2026-10-08. Anthropic's support article presents `.mcpb`desktop extensions as the main way to install a local MCP server in thedesktop app. Plugins (marketplace; can bundle MCP servers + hooks) arethe Code tab's extension surface.@@ -28,7 +28,7 @@ holds, but two of its premises moved:Status 2026-10-08: docs done, verification mostly done; results in[`verification-2026-10.md`](verification-2026-10.md).-1. Update `docs/mcp-install.md`: **done** — Linux beta and its config path+1. Update `docs/mcp-install.md`: **done**. Covers the Linux beta and its config path(with the `--config-file` the CLI needs there), the Code tab's capturethrough Claude Code hooks, `.mcpb` status, the Cowork boundary.2. Live verifications (machine with the apps installed):@@ -52,7 +52,7 @@ Status 2026-10-08: docs done, verification mostly done; results in## Phase 1 — Antigravity IDE capture parity (smallest new-code step)-The research's best new target — not the RFC's `.mcpb`:+The research's best new target, ahead of the RFC's `.mcpb`:- Ensure `install-hooks --agent antigravity-cli` output also satisfies theIDE (same global file; verify; add `.agents/hooks.json` workspace install@@ -69,11 +69,11 @@ The research's best new target — not the RFC's `.mcpb`:- Decide scratch-workspace routing: single `desktop/claude-scratch` projectvs per-scratch projects with a `claude-desktop` tag (see`capture-and-dedup.md` §2). This is the only dedup work the research- found necessary — CLI↔Desktop handoffs keep one session id, so no+ found necessary: CLI↔Desktop handoffs keep one session id, so noid-level dedup layer is needed.- Optional metadata enrichment from`~/.config/Claude/claude-code-sessions/**/local_*.json` (titles,- account/org) — strictly optional, closed-app internals.+ account/org). Strictly optional, since these are closed-app internals.## Phase 3 — explicit capture for hookless surfaces (RFC Phase 1, adjusted)@@ -96,7 +96,7 @@ The research's best new target — not the RFC's `.mcpb`:- Hosted-ChatGPT plugin (remote MCP to a user-run server): real but a newdistribution surface; needs published-plugin review requirements- (<https://developers.openai.com/plugins/deploy/app-review>) — separate+ (<https://developers.openai.com/plugins/deploy/app-review>). SeparateRFC if demand appears.- Watching Zed's native-agent database: fragile, version-locked; ACPagents already give us capture for free.@@ -109,7 +109,7 @@ The research's best new target — not the RFC's `.mcpb`:1. Codex-in-app hook firing: engine verified; one in-app prompt left.2. Antigravity IDE honoring global hooks (Phase 0 verification).-3. `.mcpb` vs plugins for Claude Desktop one-click: resolved — `.mcpb` is+3. `.mcpb` vs plugins for Claude Desktop one-click: resolved. `.mcpb` isAnthropic's current route for local MCP servers in the desktop app.4. Scratch-workspace scoping product decision (Phase 2).5. Tray stack choice + Flatpak feasibility (Phase 4).diff --git a/docs/desktop/verification-2026-10.md b/docs/desktop/verification-2026-10.mdindex c397db92..25de30e0 100644--- a/docs/desktop/verification-2026-10.md+++ b/docs/desktop/verification-2026-10.md@@ -161,8 +161,9 @@ needs `--config-file ~/.config/Claude/claude_desktop_config.json`.`tool_output` alongside Cursor's fields; the transcript lands under`~/.cursor/projects/<slug>/agent-transcripts/<id>/<id>.jsonl` and its pathappears only on `stop`. Replayed to a scratch server, the prompts are- stored but the tool events get empty bodies, unlike Claude Code's; the- cause is not yet isolated (`cursor.md`).+ stored but the tool events got empty bodies, unlike Claude Code's, because+ Cursor was missing from the tool-capture agent list; fixed in 2.6.3+ (`cursor.md`).- `cursor-agent` is not logged in.## Still unverified@@ -173,5 +174,4 @@ needs `--config-file ~/.config/Claude/claude_desktop_config.json`.| Does the Antigravity IDE run `.agents/hooks.json` / `~/.gemini/config/hooks.json`, with the same payload as the CLI? | One IDE prompt in a scratch workspace carrying a recorder `.agents/hooks.json` || Do host hooks and MCP servers reach Cowork's VM on Linux (and on macOS/Windows)? | One Cowork task after the VM images download, then look for hook output in its transcript || Cursor: the native `.cursor/hooks.json` payloads and the `cwd` inside an open folder | One prompt in the probe workspace, which carries recorder `.cursor/hooks.json` and `.claude/settings.json` files |-| Cursor: why tool events reach the store with empty bodies | A failing test that posts the captured payload, then bisect the field differences || Is a per-turn Antigravity session-start acceptable, or should it be gated per conversation? | A product decision once the server-side effect of repeated session-start posts is measured |diff --git a/docs/desktop/zed.md b/docs/desktop/zed.mdindex 168d5400..e6f90387 100644--- a/docs/desktop/zed.md+++ b/docs/desktop/zed.md@@ -11,18 +11,18 @@ Open-source editor (Rust) with an Agent Panel supporting three agent paths1. **Zed Agent** (native, built-in)2. **External Agents** via **ACP** (Agent Client Protocol,- <https://agentclientprotocol.com/>) — e.g. Gemini CLI, Claude Code,- codex-acp, opencode. **Verified locally**: the user's+ <https://agentclientprotocol.com/>), e.g. Gemini CLI, Claude Code,+ codex-acp, opencode. Verified locally: the user's`~/.config/zed/settings.json` configures `agent_servers`:`opencode` (`type: "registry"`), `codex-acp`, `claude-acp`.-3. **Terminal Threads** — native CLIs run in Zed's terminal with their own+3. **Terminal Threads**: native CLIs run in Zed's terminal with their ownconfig (so a `claude`/`codex` TUI inside Zed behaves exactly like theCLI: ai-memory hooks fire as usual, keyed by cwd).## MCP client support- Config: **`context_servers`** in the Zed `settings.json` (Linux- `~/.config/zed/settings.json` — verified locally; macOS+ `~/.config/zed/settings.json`, verified locally; macOS`~/Library/Application Support/Zed/settings.json` per Zed docs/ai-memory`docs/mcp-install.md`). Entries:- local stdio: `{"command", "args", "env"}`@@ -46,17 +46,17 @@ ai-memory status today: `install-mcp --client zed` exists (repo## Lifecycle hooks / capture surface-- **No push hooks in Zed itself** (no equivalent of Claude Code/Codex/Antigravity- hook files). Auto-capture must come from the *agent*, not the editor:+- Zed itself has no push hooks (no equivalent of Claude Code/Codex/Antigravity+ hook files). Auto-capture must come from the agent running inside Zed:- Terminal Threads and ACP external agents (claude-acp / codex-acp /- opencode) fire **their own** hooks — ai-memory captures those sessions+ opencode) fire their own hooks, and ai-memory captures those sessionsthrough the existing per-agent hook integrations (agent kind reported bythe CLI; session lands in the project keyed by cwd, which Zed sets tothe workspace dir).- The native Zed Agent has no hook surface; its threads are stored inZed's own database (source: `crates/agent`, `crates/agent_ui` in the- clone; a poll/watch importer would be per-version fragile — same bucket- as RFC #878 option (c), only if demand appears).+ clone; a poll/watch importer would break across Zed versions, so it falls in+ the same bucket as RFC #878 option (c), only if demand appears).## Session identity / dedup@@ -64,12 +64,12 @@ Zed does not sit in the session path: session ids are whatever theunderlying agent (Zed Agent / ACP server / terminal CLI) mints. For ACPagents, ai-memory sees the agent's own session id via its hooks; a ZedACP-run claude-acp session and a terminal `claude` session in the same repo-are two sessions in the same project — cwd-keyed project scope already+are two sessions in the same project, and cwd-keyed project scope alreadymerges them correctly. No Zed-specific dedup work identified.## Open-source status-**Open** — github.com/zed-industries/zed (cloned, shallow, for crate+Open source: github.com/zed-industries/zed (cloned, shallow, for cratelayout: `crates/agent`, `crates/agent_servers`, `crates/agent_settings`,`crates/language_extension` etc.).diff --git a/docs/examples/backup/README.md b/docs/examples/backup/README.mdindex f1ba4dac..fc58ad27 100644--- a/docs/examples/backup/README.md+++ b/docs/examples/backup/README.md@@ -7,17 +7,17 @@ SQLite index and models cache that the mirror repo deliberately excludes.See [`docs/backup.md`](../../backup.md) for the walkthrough. The pieces in thisdirectory are:-- `ai-memory-snapshot.sh` — the rsync + git push + tarball loop. Configurable+- `ai-memory-snapshot.sh`: the rsync + git push + tarball loop, configurablethrough six environment variables (`REPO_DIR`, `DATA_SRC`, `CFG_SRC`,`TARBALL_DIR`, `LOG_DIR`, `SECRET_EXCLUDES`) with sensible defaults for asingle-user Linux/WSL/macOS install.-- `ai-memory-backup.service` — a `systemd --user` oneshot that runs the+- `ai-memory-backup.service`: a `systemd --user` oneshot that runs thescript. `%h` expands to the user's home directory.-- `ai-memory-backup.timer` — a daily user timer with a small randomised delay+- `ai-memory-backup.timer`: a daily user timer with a small randomised delayand `Persistent=true` so the missed run after a reboot still fires.-- `.gitignore` — the exclusion list to drop into the root of the mirror- repository. Belt-and-braces to the rsync/tar exclude lists in the script- itself.+- `.gitignore`: the exclusion list to drop into the root of the mirror+ repository, as a second layer behind the rsync/tar exclude lists in the+ script itself.## Quickstartdiff --git a/docs/experience.md b/docs/experience.mdindex 74f351bd..83642d78 100644--- a/docs/experience.md+++ b/docs/experience.md@@ -1,20 +1,19 @@# The experience pass (cross-session abstraction)*2.0 item 6.* Per-session auto-improvement reviews one trajectory at a-time — it can never see that four sessions repeated the same workflow,-or that the operator keeps re-stating a preference no page records, or-that recent sessions quietly contradict a stored decision. The-experience pass reads the last N session summaries of a project **side-by side** and proposes exactly that cross-trajectory knowledge.+time, so it cannot see that four sessions repeated the same workflow,+that the operator keeps re-stating a preference no page records, or+that recent sessions contradict a stored decision. The experience pass+reads the last N session summaries of a project **side by side** and+proposes that cross-trajectory knowledge.## Why "experience"-It is the Reflection→Experience step the 2026 agent-memory literature-converges on (the survey's third stage; TriMem's narrative layer): raw+It is the Reflection→Experience step that the 2026 agent-memory literature+settles on (the survey's third stage; TriMem's narrative layer): rawcapture → per-session summaries → durable knowledge distilled acrosstrajectories. The pass targets pattern/procedure/preference/-architecture pages — the pages that make session #50 cheaper than-session #5.+architecture pages, which make session #50 cheaper than session #5.## When to turn it on — and when not to@@ -29,8 +28,8 @@ experience_sessions = 10 # read the last 10 session summariesTurn it on when per-session auto-improve is already working for you andthe project has real session history (the pass skips scopes with fewersession pages than the cadence floor). Leave it off when the project is-young — cross-session patterns need sessions to cross — or when no LLM-is configured: the pass is LLM-hosted and the zero-LLM default path+young (cross-session patterns need enough sessions to compare) or when no+LLM is configured: the pass is LLM-hosted and the zero-LLM default pathnever runs it.## What a proposal looks like@@ -55,7 +54,7 @@ Evidence: sessions 2026-08-28 ("rebuilt release, numbers changed"),```It stays in `_pending/` (with `require_approval = true`) until a human-approves it — the same review flow as every other auto-improve+approves it, the same review flow as every other auto-improveproposal.## What it costs and what guards it@@ -65,11 +64,11 @@ per-session reviewer. Every proposal flows through the **identical**machinery: JSON-schema constrained output, validation, the confidencefloor, the eval gate, the rejection buffer (rejected ideas are shown tolater runs so they are not re-proposed), and pending-writes staging with-sidecars — reviewable, never silent. `require_approval` applies+sidecars, so every proposal is reviewable and none is applied silently. `require_approval` appliesunchanged. The system prompt demands evidence spanning **at least twosessions**, naming them; single-session findings are the per-sessionreviewer's job and are rejected here.The cadence anchors on enablement: switching the pass on against an old-store does not re-digest history — it waits for the next+store does not re-digest history; it waits for the next`experience_every_sessions` completed sessions.diff --git a/docs/frontend-api.md b/docs/frontend-api.mdindex adcfd3b2..40341b42 100644--- a/docs/frontend-api.md+++ b/docs/frontend-api.md@@ -4,15 +4,15 @@> frontends against an `ai-memory` server. Added in **v0.6.0** (PR #7).> Everything below is sourced from the actual route handlers in> `crates/ai-memory-web/src/routes/api.rs` and the response structs in-> `crates/ai-memory-store/src/reader.rs` — keep them as the canonical+> `crates/ai-memory-store/src/reader.rs`. Treat those files as the canonical> reference if anything here drifts.## 1. What this surface is (and isn't)| | What you can do | What you can't do ||---|---|---|-| `/api/v1/*` | Browse workspaces, projects, pages; read full page markdown + frontmatter + back-links; FTS5 search (global or scoped, single or multi-project); aggregate "overview" snapshots; drill into stale / duplicate / orphan pages; list a project's sessions and read one session's raw observations. | Write, delete, rename, lint, consolidate, run sweeps, manage handoffs. The `/api/v1` surface is **read-only by construction** — the handlers contain zero writer calls. Writes still go through `/admin/*` (used by the CLI) or MCP tools. |-| `--web-ui-dir` | Host any SPA at `/web` (or `--web-slug`), same-origin with the API, behind the same auth. The default built-in `/web` browser stays the fallback when the flag is absent. | Host the SPA on a *different* origin without a reverse proxy — use same-origin hosting or configure CORS deliberately (see §9). |+| `/api/v1/*` | Browse workspaces, projects, pages; read full page markdown + frontmatter + back-links; FTS5 search (global or scoped, single or multi-project); aggregate "overview" snapshots; drill into stale / duplicate / orphan pages; list a project's sessions and read one session's raw observations. | Write, delete, rename, lint, consolidate, run sweeps, manage handoffs. The `/api/v1` surface is **read-only by construction**: the handlers contain zero writer calls. Writes still go through `/admin/*` (used by the CLI) or MCP tools. |+| `--web-ui-dir` | Host any SPA at `/web` (or `--web-slug`), same-origin with the API, behind the same auth. The default built-in `/web` browser stays the fallback when the flag is absent. | Host the SPA on a *different* origin without a reverse proxy. Use same-origin hosting or configure CORS deliberately (see §9). |## 2. Auth model@@ -202,7 +202,7 @@ on disk (the body is read from the markdown file at request time).### 4.5 Search-Two forms — query-string for the common single-scope or global case,+Two forms: query-string for the common single-scope or global case, and aJSON body for multi-scope.```http@@ -250,7 +250,7 @@ Rules:top-level `workspace`/`project`.- `snippet` contains FTS5 HTML markers (`<mark>…</mark>`) around thematched terms.-- `rank` is FTS5 rank — **lower is better** (closer to query terms).+- `rank` is FTS5 rank; **lower is better** (closer to query terms).### 4.6 Recent@@ -310,7 +310,7 @@ parameter retain the legacy array, descending order and cache behavior.GET /api/v1/workspaces/{workspace}/projects/{project}/briefing?limit=10```-Same payload `memory_briefing` returns — counts + activity windows ++Same payload `memory_briefing` returns: counts + activity windows +last-observation + open handoffs + `_rules/` + `_slots/` + N most-recentpages. No LLM, deterministic.@@ -350,7 +350,7 @@ GET /api/v1/workspaces/{workspace}/projects/{project}/handoffs?all_owners=true`state` accepts `open` | `accepted` | `expired`; omit it to list every state,which is how you find a baton that was already consumed. Results are scoped byowner: an authenticated caller sees their own plus the shared handoffs, an-anonymous browser sees only shared ones — an owned handoff (and the prompt-+anonymous browser sees only shared ones. An owned handoff (and the prompt-derived text inside it) is never rendered to someone it does not belong to.The same scoping applies to the `handoff` field of both overview endpoints andto `pending_handoff_count`, so the count and the fetch always agree.@@ -358,8 +358,8 @@ For recovery, a root-authorized request may pass `all_owners=true` to list alloperators' rows. User and anonymous requests receive `403`; the default remainsown plus shared, including for root.-On a server that authenticates, the listing's prompt-derived fields —-`summary`, `open_questions`, `next_steps` — are served to a caller the server+On a server that authenticates, the listing's prompt-derived fields+(`summary`, `open_questions`, `next_steps`) are served to a caller the servercan name and to the root operator; an automatic handoff synthesises themverbatim from the operator's prompts, and the listing returns the project'swhole history rather than the single newest open row. A caller that is neither@@ -374,7 +374,7 @@ one, otherwise the username. An ingress that terminates OIDC and forwards both`X-Memory-Actor-Issuer` and `X-Memory-Actor-Sub` therefore reads its ownhandoffs and the shared ones with `redacted: false`, and no rung of the authchain produces an-authenticated-but-unnameable caller today — the redacting arm is a fail-safe+authenticated-but-unnameable caller today. The redacting arm is a fail-safefloor, not a live tier. `owner` / `accepted_by` carry the qualified storage key(`user:alice`, `oidc:<issuer-byte-length>:<issuer><subject>`).@@ -437,7 +437,7 @@ either response, `handoff` is `null` when no open handoff matches the scope:}```-> Note: `handoff` is **not** consumed by the read API — the+> Note: `handoff` is **not** consumed by the read API. The> handoff stays "open" and can still be accepted by the next agent.### 4.9 Cross-project graph@@ -477,8 +477,8 @@ GET /favicon.icoReturns the same transparent PNG the built-in web UI serves as theheader logo. Browsers fetch this path automatically. The route ispresent whenever the web UI is enabled (`--enable-web`) and is-mounted at the absolute host root — outside `--base-path` and outside-the `/web` nest — so the browser's automatic fetch reaches it even+mounted at the absolute host root, outside `--base-path` and outside+the `/web` nest, so the browser's automatic fetch reaches it evenunder a subpath deployment. The response is `image/png` despite the`.ico` URL (modern browsers accept PNG icons), and the route is**exempt from authentication and host allowlist**: a fresh tab can fetch the@@ -668,8 +668,8 @@ characters (`[A-Za-z0-9-._~]`). Three things collapse the prefix todowngrade in the log:- `.` or `..` segments. Their characters are unreserved on their own,- but at the segment boundary they mean "current" and "parent" — one- typo and your prefix is a traversal vector.+ but at the segment boundary they mean "current" and "parent", so a+ single typo would turn your prefix into a traversal vector.- Any character outside the unreserved set (spaces, `<`, `"`, etc.).- Empty / whitespace-only input.@@ -679,7 +679,7 @@ client-side and never reach the server.When `--web-ui-dir` is **absent**, the built-in server-side `/web`browser is the default (read-only HTML rendering, FTS5 search,-project tree). No regression.+project tree), unchanged from before.## 7. Worked example: minimal SPA fetch@@ -776,7 +776,7 @@ Read these:## 9. CORS`/api/v1` accepts cross-origin requests when the operator configures-the allow-list. The CORS layer is scoped to that router only — `/mcp`,+the allow-list. The CORS layer is scoped to that router only; `/mcp`,`/hook`, `/admin/*`, and `/web` stay same-origin.Configure via either `--cors-allow-origin <origin>` (repeatable) on@@ -794,7 +794,7 @@ accepting wildcard. The layer allows `GET / POST / OPTIONS`,## 10. Known gaps and deliberate non-goals-- **No write surface, by design — not a pending iteration.** Browsers+- **No write surface, by design.** This is not a pending iteration: browserscan't mutate, and won't. The wiki is a record of what a projectproduced, authored by automated summarisation over capturedobservations; retrieval, provenance and the audit trail all rest on@@ -803,12 +803,12 @@ accepting wildcard. The layer allows `GET / POST / OPTIONS`,"what did someone want it to say", with no way to tell the two apartafterwards.- This is not a ban on human input. `memory_write_page` exists for+ Human input is still allowed. `memory_write_page` exists fordurable human annotations and lands them in the same lineage aseverything else (pages supersede on body change). The line is betweenadding to the record through the normal path and editing it fromoutside. A human-editable wiki is a reasonable thing to want and a- separate product — see #482.+ separate product; see #482.- **Rate limiting** is shared with `/mcp` + `/admin` (only the bodycap is enforced today). A future global limiter would tighten theauthenticated-misbehaviour case.diff --git a/docs/https-via-proxy.md b/docs/https-via-proxy.mdindex afc8bba4..8232a693 100644--- a/docs/https-via-proxy.md+++ b/docs/https-via-proxy.md@@ -4,12 +4,12 @@> the operator's guide to fronting it with a mature TLS terminator> (Caddy, Cloudflare Tunnel, nginx) so tokens and `/web` cookies> travel encrypted between clients and the server. Default install-> stays plain HTTP on loopback — no change for existing users on-> upgrade.+> stays plain HTTP on loopback, so nothing changes for existing users+> on upgrade.## When you don't need this-Skip TLS entirely if you're in one of these shapes — the security+Skip TLS entirely if you're in one of these shapes; the securitybudget is better spent elsewhere:- **Single-user, stdio MCP transport.** `claude mcp add ai-memory -- ai-memory serve --transport stdio` never touches the network. No TLS to worry about.@@ -26,7 +26,7 @@ apply:- **Multi-user mode is on** (at least one user row exists; `[auth].token_pepper`is the credential prerequisite). Native `aim_` keys travel between clients and- the server — sniffable over plain HTTP on the LAN. See+ the server and are sniffable over plain HTTP on the LAN. See[`docs/users.md`](users.md).- **The server is bound beyond loopback** (`AI_MEMORY_BIND=0.0.0.0:49374` or a LAN-routable IP). Anyone on the network segment sees plaintext token traffic and `/web` cookies.- **You access `/web` from a different machine** than the one running ai-memory. The browser session cookie set after password login lives in the clear over HTTP.@@ -46,14 +46,14 @@ cookies are supported only on an actual loopback listener.|---|---|---|| **Caddy + public domain + Let's Encrypt** | Operators with a domain name + port 80/443 reachable from the internet (most homelabs behind a forwarding router). | DNS A/AAAA record pointing at your IP. || **Caddy + internal CA (LAN-only)** | LAN-only multi-user, no public exposure. Each client machine has to trust Caddy's root cert once. | One-time root cert install per client. |-| **Cloudflare Tunnel** | "I don't want to open ports on my router" — outbound-only tunnel, TLS terminated at Cloudflare's edge. | A Cloudflare account (free tier works) + a domain on Cloudflare. |+| **Cloudflare Tunnel** | "I don't want to open ports on my router": outbound-only tunnel, TLS terminated at Cloudflare's edge. | A Cloudflare account (free tier works) + a domain on Cloudflare. || **External cert files (Caddy or nginx)** | You already have a corporate or homelab CA issuing certs to your services. | The cert/key files, however your environment produces them. || **nginx** | You already run nginx for other services and want one config language. | Same as Caddy: a domain or files. |The compose templates in `docker/` are ready to copy:-- [`docker/compose.tls.caddy.yml`](../docker/compose.tls.caddy.yml) — Caddy front, both LE and internal-CA variants documented inline.-- [`docker/compose.tls.cloudflared.yml`](../docker/compose.tls.cloudflared.yml) — Cloudflare Tunnel sidecar, zero open ports.+- [`docker/compose.tls.caddy.yml`](../docker/compose.tls.caddy.yml): Caddy front, both LE and internal-CA variants documented inline.+- [`docker/compose.tls.cloudflared.yml`](../docker/compose.tls.cloudflared.yml): Cloudflare Tunnel sidecar, zero open ports.The sections below walk through each.@@ -104,7 +104,7 @@ volumes:### Caddyfile-A complete one, three lines that actually matter:+A complete Caddyfile is three lines:```caddyfilememory.example.com {@@ -170,7 +170,7 @@ protected data rather than an authentication page.**Safety rules on both flags.** `AI_MEMORY_BASE_PATH` and`AI_MEMORY_WEB_SLUG` go through the same normaliser. Segments must beRFC 3986 unreserved characters (`[A-Za-z0-9-._~]`). Dot-segments-(`.` / `..`) are rejected — they mean "current" and "parent" at a+(`.` / `..`) are rejected: they mean "current" and "parent" at asegment boundary, so accepting them would let a typo turn the prefixinto traversal. Anything outside the unreserved set falls back to aroot mount, and the startup log says why. The trailing-slash redirect@@ -240,11 +240,11 @@ Then install it into each client OS's trust store:| Windows | `certutil -addstore -f "Root" caddy-root.crt` (Administrator PowerShell) || iOS / Android | Email the file to the device, open it, install as a profile in Settings → General → VPN & Device Management. Then **also** explicitly trust it under Settings → General → About → Certificate Trust Settings. |-**The warning that has to be loud**: if you skip the trust-install+**Warning:** if you skip the trust-installstep on a client, that client will either refuse TLS connections(MCP clients, curl) or train the operator to click through warnings(browsers). In the latter case **you have neither HTTP's transparency-nor HTTPS's protection** — you have a security theatre cert that+nor HTTPS's protection**, only a security theatre cert thatmakes everyone less safe. Install the root cert on every clientmachine you connect from, or use Path 1 / Path 3 instead.@@ -261,8 +261,8 @@ Cloudflare's `cloudflared` daemon establishes an outbound-only tunnelto Cloudflare's edge. **No ports open on your router**, no public IPneeded, TLS terminated at the Cloudflare edge with their cert. Pairsparticularly well with the homelab multi-user case because the trust-story is "Cloudflare is the CA" — universally trusted, no per-client-install dance.+story is "Cloudflare is the CA": universally trusted, with no per-client+install step.### One-time Cloudflare setup@@ -270,7 +270,7 @@ install dance.2. In the Cloudflare dashboard, go to **Zero Trust → Networks → Tunnels** → **Create a tunnel** → name it `ai-memory-homelab` (or whatever) → save.3. Cloudflare gives you a long token string. Save it for the compose file.4. Add a public hostname to the tunnel: `memory.example.com` → service `http://ai-memory:49374`. Save.-5. (Optional but recommended) Wrap the hostname in a **Cloudflare Access** application — Cloudflare's zero-trust SSO sits in front of the tunnel and you get human auth via Google/GitHub/etc. **on top of** ai-memory's bearer token.+5. (Optional but recommended) Wrap the hostname in a **Cloudflare Access** application. Cloudflare's zero-trust SSO sits in front of the tunnel and you get human auth via Google/GitHub/etc. **on top of** ai-memory's bearer token.### Compose template@@ -405,7 +405,7 @@ Install Caddy natively (`brew install caddy` / `pacman -S caddy` /(`/etc/caddy/Caddyfile` on Linux, `/opt/homebrew/etc/Caddyfile` onmacOS), and `systemctl enable --now caddy` / `brew services startcaddy`. Everything else (LE, internal CA, external certs) works the-same as the Docker paths above — Caddy doesn't care which side of the+same as the Docker paths above; Caddy doesn't care which side of thecontainer boundary it's on.For Cloudflare Tunnel: `cloudflared service install ${CLOUDFLARE_TUNNEL_TOKEN}`@@ -417,7 +417,7 @@ LaunchDaemon on macOS. Same shape as the Docker variant.## Long-running requests: `bootstrap` and proxy idle timeouts`ai-memory bootstrap` on a large repository holds a **single POST open for-the whole multi-chunk run** — often 20+ minutes — while the server makes+the whole multi-chunk run** (often 20+ minutes) while the server makesLLM calls, with no bytes flowing over the wire in between. A reverse proxywith a default idle/read timeout in front of the server will cut thatconnection (`Connection reset by peer`), and the run is lost.@@ -425,7 +425,7 @@ connection (`Connection reset by peer`), and the run is lost.If you run `bootstrap` through a proxy, raise or disable the upstreamread/write timeout for ai-memory's route.-**Caddy** — disable the backend read/write timeouts on the `reverse_proxy`:+**Caddy**: disable the backend read/write timeouts on the `reverse_proxy`:```caddyfilememory.example.com {@@ -438,7 +438,7 @@ memory.example.com {}```-**nginx** — raise `proxy_read_timeout` / `proxy_send_timeout` (default 60s)+**nginx**: raise `proxy_read_timeout` / `proxy_send_timeout` (default 60s)well past your longest run:```nginx@@ -452,15 +452,14 @@ location / {This only matters for the long-held `bootstrap` POST; ordinary MCP and`/api/v1` requests are short and unaffected. (A genuinely failed chunk still-loses the run today — the durable-progress/`--resume` question is tracked+loses the run today. The durable-progress/`--resume` question is trackedseparately; see #614.)---## Outbound LLM calls fail behind a TLS-inspecting firewall-The paths above are about clients trusting *ai-memory's* certificate. This-section is the mirror image: **ai-memory trusting an upstream interceptor** so+The paths above are about clients trusting *ai-memory's* certificate. This section covers the reverse case: ai-memory trusting an upstream interceptor soits own outbound LLM/embedding calls succeed.**Symptom.** Consolidation, lint, or embeddings fail and the logs show@@ -471,7 +470,7 @@ re-signs TLS with a private interception root the container doesn't trust.**Why it happens.** ai-memory's HTTP client (reqwest + rustls, built with`rustls-tls-native-roots`) trusts the **operating system** certificate store,-not a bundled root list — it reads the container's `/etc/ssl/certs` and honors+not a bundled root list. It reads the container's `/etc/ssl/certs` and honors`SSL_CERT_FILE` / `SSL_CERT_DIR`. The stock image ships only the public Debianroots, so the interception root is unknown. `curl` from your host may succeedbecause your host already trusts that root; the container does not.@@ -479,7 +478,7 @@ because your host already trusts that root; the container does not.**Fix.** Give the container a CA bundle that includes the interception root.1. Export the interception root your gateway presents (from a trusted host),- or — better — get it from your IT team, which is the authoritative source:+ or, better, get it from your IT team, which is the authoritative source:```bashopenssl s_client -showcerts -connect api.openai.com:443 </dev/null 2>/dev/null \@@ -518,15 +517,15 @@ because your host already trusts that root; the container does not.**Notes.**- Point `SSL_CERT_FILE` at the *combined* bundle, never at the interception- root alone — that would drop every public root and break all other TLS.+ root alone; that would drop every public root and break all other TLS.- Native (non-Docker) installs: on Linux, install the root system-wide(`update-ca-certificates` / `trust anchor`) or set `SSL_CERT_FILE`; onWindows the client reads the schannel store, so import the root there- instead — `SSL_CERT_FILE` does not apply.+ instead (`SSL_CERT_FILE` does not apply).## What ai-memory does to support being behind a proxy-Nothing special — the server intentionally generates no absolute URLs+Nothing special. The server intentionally generates no absolute URLsin responses, so it doesn't matter whether `https://` or `http://`sits in front. The bearer token middleware reads `Authorization`directly off the request, which proxies forward verbatim. The@@ -552,12 +551,11 @@ Three things to actively avoid:1. **Don't disable the allowed-hosts guard.** It's the DNS-rebinding defence; pruning it because the proxy "should be" filtering is exactly the kind of "the other layer handles it" assumption that ships bugs. Add the public hostname; don't widen to `*`.2. **Don't skip the trust-install step in Path 2.** The temptation is to add `-k` (curl) or `--insecure` (MCP clients that support it) "just to get it working." If you do, you have a security theatre cert: TLS without authentication, which is worse than HTTP with the bearer because it looks safe and isn't.-3. **Don't run cloudflared with `--no-tls-verify`.** Cloudflare's tunnel daemon validates ai-memory's cert by default — which is fine because ai-memory is on plain HTTP inside the docker network. Don't override the flag; you'd be reaching for it because something else is misconfigured.+3. **Don't run cloudflared with `--no-tls-verify`.** Cloudflare's tunnel daemon validates ai-memory's cert by default, which is fine because ai-memory is on plain HTTP inside the docker network. Don't override the flag; you'd be reaching for it because something else is misconfigured.-If you can't take one of these paths cleanly, the honest answer is-"keep ai-memory loopback-only" or "front it with the proxy you-already trust." The configuration that gives operators the wrong-mental model — looking secure, not being secure — is worse than+If you can't take one of these paths cleanly, keep ai-memory loopback-only or+front it with the proxy you already trust. A configuration that gives operators+the wrong mental model, looking secure without being secure, is worse thaneither.## The session-aware MCP bridge and HTTPS@@ -566,9 +564,9 @@ either.its transport pulled in a second `reqwest` with no TLS backend compiled, so anynon-`http` scheme was refused before a connection was attempted. If you frontai-memory with a TLS-terminating proxy as described above, point the bridge at the-proxied `https://` URL directly — a second, local proxy on each client machine is+proxied `https://` URL directly; a second, local proxy on each client machine isnot needed.The bridge uses the platform certificate verifier, so it trusts the same roots the-operating system does. A certificate the OS does not trust — a self-signed one, or a-private CA that has not been installed into the system trust store — is rejected.+operating system does. A certificate the OS does not trust (a self-signed one, or a+private CA that has not been installed into the system trust store) is rejected.diff --git a/docs/install.md b/docs/install.mdindex ecdb8252..e8842e92 100644--- a/docs/install.md+++ b/docs/install.md@@ -101,8 +101,8 @@ ai-memory install-hooks --agent claude-code --scope project --applyThis writes the repository's gitignored `.claude/settings.local.json` at thegit root (the main checkout's root from a worktree), which is where Claude Code-reads that file even when launched from a subdirectory — see-[where Claude Code looks for each file](https://code.claude.com/docs/en/settings#where-claude-code-looks-for-each-file).+reads that file even when launched from a subdirectory (see+[where Claude Code looks for each file](https://code.claude.com/docs/en/settings#where-claude-code-looks-for-each-file)).On Windows, and when the repository root is your home directory, Claude Codereads the launch directory instead, so the installer writes to the currentdirectory there: run it, and launch Claude Code, from the same directory.@@ -118,7 +118,7 @@ next to the file, so nothing new appears in `git status`.`ai-memory uninstall --only hooks --apply` run from inside the checkoutremoves the entries again; run elsewhere it does not reach into therepository, so run it in every project-scoped checkout before removing-ai-memory — those files otherwise keep calling the removed binary and data+ai-memory. Otherwise those files keep calling the removed binary and datadir. `upgrade` and the `ai-memory run` auto-wire leave the user-level filealone while a project-scoped install is the only one present. `upgrade`replaces the binary the hook commands call but does not rewrite project@@ -226,7 +226,7 @@ choice explicitly for upgrade safety. Repositories without a valid remote use`basename(cwd)`, including from a git subdirectory. Because an agent shell keeps its working directory between tool calls, a single`mkdir sub && cd sub` reparents the rest of the session into a phantom projectnamed `sub`. To make every session for an install resolve its project from the-git repo root instead — collapsing subdirectories and worktrees — bake the+git repo root instead, collapsing subdirectories and worktrees, bake thestrategy into the hooks:```bash@@ -239,7 +239,7 @@ already baked into that agent's ai-memory hooks, including during the wrapper'sautomatic post-upgrade refresh. Pass `basename` explicitly to remove anexisting `repo-root` default. This works for every agent and delivery path. Aper-repo `.ai-memory.toml` marker's own `project_strategy` / `project` still-take precedence — see+take precedence; see[the marker-file reference](marker-file.md#install-wide-default-no-marker).---@@ -408,7 +408,7 @@ curl -sI http://127.0.0.1:49374/handoff> [below](#anthropic-via-claude-subscription-oauth).) See> [`docs/llm-providers.md`](llm-providers.md) for the full table. And you can> skip an LLM entirely: the default zero-LLM path still captures, searches-> (FTS), and writes rule-based summaries with no provider at all —+> (FTS), and writes rule-based summaries with no provider at all, and> [`docs/local-embeddings.md`](local-embeddings.md) makes vector search> keyless too.@@ -563,21 +563,21 @@ stream; tool and session-boundary capture continues unchanged.**Capture only repositories that opt in.** The controls above narrow *what* iscaptured; this one narrows *where*. By default a repository with no`.ai-memory.toml` marker is still captured, so a machine that works across many-checkouts captures every new one automatically — forgetting a marker means+checkouts captures every new one automatically. Forgetting a marker meanscapturing more, not less. Allowlist mode inverts that:```bashai-memory install-hooks --apply --capture-mode allowlist```-A repository without a marker then emits **no lifecycle event at all** — not a+A repository without a marker then emits **no lifecycle event at all**, not even atrimmed one. The event is dropped in the hook process before it can reach thelocal spool or the wire, so nothing is written to disk for a repository that-never opted in. Opting a repository in is just placing a `.ai-memory.toml`+never opted in. To opt a repository in, place a `.ai-memory.toml`marker in it, which is the same file that already configures routing and`ignore_paths`.-**It is enforced by native `ai-memory hook` commands only** — the same+**It is enforced by native `ai-memory hook` commands only**, the sameboundary that already applies to `[capture] ignore_paths`, and for the samereason: the gate runs inside the hook binary, immediately before it spools.@@ -594,8 +594,8 @@ the install it is writing cannot enforce it.Within that boundary the mode is not per-agent: it is stored once in the datadirectory and every native hook command reads it, whichever agent invoked it.That also means a later bare-`install-hooks --apply` — including the auto-refresh inside `ai-memory upgrade`-— leaves it alone by construction rather than by re-detecting it. Every+`install-hooks --apply`, including the auto-refresh inside `ai-memory upgrade`,+leaves it alone by construction rather than by re-detecting it. Every`--apply` prints the mode in force. Return to the default with`--capture-mode denylist`.@@ -624,14 +624,14 @@ instead of falling back. Native hook commands route profiles; the generatedTypeScript integrations and the script hooks drop routed repositories. See[`marker-file.md`](marker-file.md#routing-capture-to-another-server-server).-Some agent harnesses attach the assistant's final turn to their `Stop` event —+Some agent harnesses attach the assistant's final turn to their `Stop` event;Claude Code sends it as a raw `last_assistant_message`. By default that text isnever persisted: the native hook binary strips the raw field before it can reachthe local spool or the wire, and the server strips it defensively on arrival.**Opt-in capture (#196).** You can opt in to storing a sanitized, 2 KB-cappedexcerpt of the assistant's final turn as the Stop body. It is a **double-opt-in** — enable the server first, then the client:+opt-in**: enable the server first, then the client:1. **Server:** set `capture_assistant = true` in the live`<data_dir>/config.toml` (or the service's configured TOML file), or set@@ -646,12 +646,12 @@ opt-in** — enable the server first, then the client:The client sanitizes (built-in patterns) and truncates the excerpt before ittouches the spool or wire; the server re-scrubs with its `[sanitize]` patterns-before storing. If either side is off — or the marker is malformed — the Stop+before storing. If either side is off, or the marker is malformed, the Stopstays empty. Re-running `install-hooks` without `--capture-assistant` removesthe flag (idempotent). `--capture-assistant` is Claude Code, Codex andOpenCode 2 (`--agent opencode2`) on a native hook platform only; on any other agent or the script fallback theinstaller refuses it rather than enabling something that cannot take effect. Assistant text is-privacy-sensitive — read the `SECURITY.md` notes on what it can contain and where+privacy-sensitive. Read the `SECURITY.md` notes on what it can contain and whereit flows (consolidation/reviewer prompts, and out to a cloud LLM provider if oneis configured) before enabling it.@@ -696,8 +696,8 @@ passes when the server is unreachable. Set `max_attempts = 0` under`AI_MEMORY_HOOK_SPOOL_MAX_ATTEMPTS=0`) to keepretrying until the 7-day age limit or 10,000-file spool cap applies. A positivevalue sets the number of failed passes before a drop. The same bounds apply to-`ai-memory run`'s degraded offline launches, which rely on this spool — see-[Degraded offline launches](managed-workstreams.md#degraded-offline-launches).+`ai-memory run`'s degraded offline launches, which rely on this spool (see+[Degraded offline launches](managed-workstreams.md#degraded-offline-launches)).The built-in timings stay short on agent-facing paths, but high-latency orlarge-backlog instances can raise them with whole-minute runtime env vars in the@@ -715,7 +715,7 @@ agent's environment; no `install-hooks` rerun is needed:The retry setting can also be written as `max_attempts` under `[hook_spool]` in`<data_dir>/config.toml`; the runtime environment wins when both are set. A setbut invalid `AI_MEMORY_HOOK_SPOOL_MAX_ATTEMPTS` value (non-numeric) falls back to-the built-in default of 8, overriding any `config.toml` value — same convention+the built-in default of 8, overriding any `config.toml` value, the same conventionas the timing vars. A zerovalue still leaves the 7-day age limit and 10,000-file spool cap active.@@ -808,16 +808,16 @@ AI_MEMORY_NATIVE_TEST_IMAGE=quay.io/toolbx/arch-toolbox:latest scripts/test-natiUser-facing NixOS module setup lives in the [README NixOSsection](../README.md#nixos) (`nixosModules.default`,`services.ai-memory.enable`). This section is the maintainer test ladder-for the flake and module — what CI runs, and what each tier proves.+for the flake and module: what CI runs, and what each tier proves.### Maintainer test ladder-1. **Package smoke** — `nix build .#packages.<system>.default` then+1. **Package smoke**: `nix build .#packages.<system>.default` then`scripts/check-nix-packaging.sh ./result` (binary `--version`, hookstree, config template, `nix run`). Linux runs on every path-filtered`nix.yml` PR; Darwin is schedule / `workflow_dispatch` / `nix` or`full-ci` label only.-2. **Eval contracts** — `nix build .#checks.x86_64-linux.nixos-module-eval`+2. **Eval contracts**: `nix build .#checks.x86_64-linux.nixos-module-eval`and `nixos-sandbox-parity`. Cheap Linux-only asserts for enable/bind/`--config`/secrets wiring, API-only vs web mounts, refusal messages (age+sops mutex, secrets in`settings.auth`, `settings.bind`), escaped `ExecStart` (`--data-dir`,@@ -825,7 +825,7 @@ for the flake and module — what CI runs, and what each tier proves.`dataDir` tmpfiles/`ReadWritePaths`, and sandbox key parity with`nix/systemd-sandbox.nix`. Runs on path-filtered PRs with the Linuxpackage job.-3. **Toplevel → OCI → container smoke** — one closure path. Building+3. **Toplevel → OCI → container smoke**: one closure path. Building`packages.x86_64-linux.nixos-ai-memory-docker` builds`system.build.toplevel` once (via the nixpkgs docker-image tarball);there is no separate bare-toplevel CI job. Then:@@ -903,7 +903,7 @@ source-build, Docker-wrapper, and hand-installed launchd paths remain in> `install-mcp --server-url` accepts either the bare server origin or the full> MCP endpoint and appends a missing `/mcp` exactly once.> `install-hooks --server-url` takes the bare server **origin**-> (e.g. `http://homelab:49374`) — hook scripts append `/hook`, `/handoff`,+> (e.g. `http://homelab:49374`); hook scripts append `/hook`, `/handoff`,> etc. themselves.Each agent CLI needs two things:@@ -1040,7 +1040,7 @@ Kimi Code keeps MCP servers in `~/.kimi-code/mcp.json` and lifecycle hooks inThe CLI also accepts `--agent kimi` as an alias. `install-mcp` writes theserver URL with a `?flavor=moonshot` query because the Moonshot API rejectsroot-level `anyOf`/`oneOf`/`allOf` in tool parameter schemas ("moonshot-flavored json schema") — the ai-memory server answers flavored requests with+flavored json schema"). The ai-memory server answers flavored requests withflat schemas, and all other clients keep the upstream shape.```bash@@ -1054,11 +1054,11 @@ ai-memory install-hooks --agent kimi-code --apply \````install-hooks` merges `[[hooks]]` entries into `config.toml`, preserving the-provider/model settings the same file holds. Entries cover 10 events —-`SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`,+provider/model settings the same file holds. Entries cover 10 events+(`SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`,`PostToolUseFailure` (Kimi Code reports tool failures separately fromsuccessful calls; it reuses the post-tool-use handler), `Stop`,-`SubagentStart`, `SubagentStop`, and `PreCompact` — and default to+`SubagentStart`, `SubagentStop`, and `PreCompact`) and default tonative `ai-memory hook --event … --agent kimi-code` commands on local installs(local spool plus batched delivery, capture-policy v1 enforced); the stagedscript bundle under `~/.local/share/ai-memory/hooks/kimi-code/` is the@@ -1234,7 +1234,7 @@ stores. See### Pool (Poolside Agent CLI)Pool reads lifecycle hooks from a project-scoped `.poolside/settings.yaml` at-the root of each repository it runs in — there is no user-global hook file for+the root of each repository it runs in; there is no user-global hook file forai-memory to merge. `install-hooks --agent pool` (alias `poolside`) thereforestages the hook scripts to the stable user-global location and prints aready-to-paste `hooks:` snippet; ai-memory deliberately does not write@@ -1250,7 +1250,7 @@ ai-memory install-hooks --agent pool --apply \--auth-token "$TOKEN"```-The snippet wires Pool's five documented events — `SessionStart`,+The snippet wires Pool's five documented events: `SessionStart`,`UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` (Claude-shapednames, snake_case JSON payload on stdin, verified against Poolside CLIv1.0.16). Local installs use the native `ai-memory hook` command, so Pool's@@ -1269,7 +1269,7 @@ ai-memory finalize-session --agent pool --session-id <uuid>Pool tolerates hook stdout, but model-visible context injection from`SessionStart` stdout is not demonstrated, so the session-start hook captures-only and never fetches the (single-use) handoff — recover a prior session's+only and never fetches the (single-use) handoff. Recover a prior session'shandoff via the MCP `memory_handoff_accept` tool. No first-party`install-mcp` client and no managed workstream (`ai-memory run pool`) areclaimed: Pool's native session-store contract is not demonstrated, per@@ -1278,7 +1278,7 @@ claimed: Pool's native session-store contract is not demonstrated, per### ZCode (z.ai)ZCode wires lifecycle hooks in the root `hooks` block of-`~/.zcode/cli/config.json` — the same file that holds its other CLI+`~/.zcode/cli/config.json`, the same file that holds its other CLIregistration. `install-hooks --agent zcode` (alias `zai`) merges ai-memory'sentries into that block around any third-party hooks you already have, and isidempotent: re-running strips only ai-memory's own entries (marked by@@ -1295,7 +1295,7 @@ ai-memory install-hooks --agent zcode \```Entries are exec-form `{"type": "process", "command": <ai-memory>, "args":-[…]}` — ZCode spawns them with the event JSON on stdin and no shell, which the+[…]}`. ZCode spawns them with the event JSON on stdin and no shell, which thenative `ai-memory hook` command reads directly, so the local spool, bearerauth, and `[capture] ignore_paths` exclusions all apply. Every emitted key isfrom ZCode's documented hook schema (`type`, `command`, `args`, `enabled`,@@ -1313,7 +1313,7 @@ design.ZCode injects `SessionStart` stdout as model context(`hookSpecificOutput.additionalContext`), so unlike Pool, Zero, and Grok theprior session's handoff is delivered automatically at session start. There is-no true session-end event — `Stop` fires at the end of every turn — so close+no true session-end event (`Stop` fires at the end of every turn), so closefinished sessions explicitly; use the exact id when several ZCode sessions areopen in the same project:@@ -1330,8 +1330,8 @@ No first-party `install-mcp` client and no managed workstreamCopilot CLI keeps its config in `~/.copilot` (or `$COPILOT_HOME`).`install-mcp --client copilot-cli` merges the remote server entry into`mcp-config.json` there, and `install-hooks --agent copilot-cli` writes-`hooks/ai-memory.json` — Copilot's standalone `{"version": 1, "hooks": {…}}`-format — merging around any third-party entries already in each file:+`hooks/ai-memory.json` in Copilot's standalone `{"version": 1, "hooks": {…}}`+format, merging around any third-party entries already in each file:```bashai-memory install-mcp --client copilot-cli --apply \@@ -1382,7 +1382,7 @@ ai-memory install-hooks --agent hermes \```Hermes splits each configured `command` with `shlex.split` and runs it with-**no shell**, passing the event JSON on stdin — so the generated entry invokes+**no shell**, passing the event JSON on stdin, so the generated entry invokesthe native `ai-memory hook` command directly (the same exec-form shape Zero andZCode use) and there is no script bundle to stage. There is also no `--apply`that writes the file: `~/.hermes/config.yaml` is YAML you also edit, and Hermes@@ -1494,7 +1494,7 @@ and MCP locations.> ai-memory only ever opens that database read-only; the migration risk> comes from launching `opencode2` itself, not from this integration.>-> **The beta's background service defaults to port 49374 — ai-memory's own+> **The beta's background service defaults to port 49374, which is also ai-memory's> default.** Running both on defaults crash-loops the opencode2 service> (`Managed service port 49374 ... is already in use`). Move one side:> `opencode2 service set port <free-port>`, or start ai-memory with@@ -1552,7 +1552,7 @@ Pi's whole `~/.pi/agent` home), the extension is written toThe Pi and OMP extensions use distinct filenames (`ai-memory-pi.ts` and`ai-memory-omp.ts`) so installing one never overwrites the other. They are-not interchangeable — only Pi's bridges MCP tools.+not interchangeable: only Pi's bridges MCP tools.#### OMP profiles@@ -1765,8 +1765,8 @@ The generated TypeScript integrations survive an unreachable server thesame way the native hooks do: a delivery that fails at the network level(or gets a 5xx, 408, 425 or 429) is written to `<data_dir>/hook-spool/` in the exactformat `ai-memory hook-drain` reads, and the plugin drains that backlog-itself once the server is reachable again — so a day of laptop work off-the server's network is captured, not silently dropped. Each spooled+itself once the server is reachable again. A day of laptop work off+the server's network is therefore captured, not silently dropped. Each spooledentry carries an idempotency key, so the plugin's own drain and amanual `hook-drain` can race without double-ingesting. Note the spoollands in the *agent host's* data dir (`AI_MEMORY_DATA_DIR` or the@@ -1795,8 +1795,8 @@ automatically; you only set it by hand for custom container setups.Most users should stick to the docker wrapper from the Quick start. ArchLinux users have the [AUR packages](#arch-linux-native-packages-aur). For any-other host, `mise` installs a tagged release binary directly from GitHub —-no Rust toolchain needed:+other host, `mise` installs a tagged release binary directly from GitHub,+with no Rust toolchain needed:```bashmise use -g github:akitaonrails/ai-memory@@ -1810,7 +1810,7 @@ it and puts `ai-memory` on `PATH`. (mise can also check GitHub artifactattestation and SLSA provenance where a project publishes them; ai-memory'srelease workflow does not emit either today, so only the checksum applies.)No dedicated mise plugin or-registry entry is required — the backend works against any repo whose+registry entry is required; the backend works against any repo whoserelease assets follow this naming convention. By default mise also holds backthe very newest release for a short safety window([`minimum_release_age`](https://mise.jdx.dev/dev-tools/github-backend.html)),@@ -1821,7 +1821,7 @@ that.`cargo install ai-memory` is not available: the crate name is already takenby an unrelated project on crates.io, as is `ai-memory-core` (the workspace'sfoundational internal crate). Publishing would require renaming at least-that crate for the registry — a naming decision the project hasn't made yet.+that crate for the registry, a naming decision the project hasn't made yet.Build from source only when hacking on ai-memory itself or running on aplatform none of the above covers. On macOS, tagged releases also publish@@ -1852,10 +1852,10 @@ The `serve` subcommand also accepts:|---|---|---|| `--enable-web` | `AI_MEMORY_ENABLE_WEB=true` | Mount the read-only web browser and `/api/v1` JSON API. || `--enable-api` | `AI_MEMORY_ENABLE_API=true` | Mount only the protected, read-only `/api/v1` JSON API for companions and other non-browser clients. |-| `--base-path /wiki` | `AI_MEMORY_BASE_PATH` | Host the entire HTTP surface (`/mcp`, `/hook`, `/admin/*`, `/api/v1`, `/web`) under a configurable subpath — useful behind a reverse proxy sharing a hostname. `.` and `..` segments are rejected; unsafe chars cause a fallback to root with a warning. See [`docs/https-via-proxy.md`](https-via-proxy.md#hosting-under-a-subpath). |+| `--base-path /wiki` | `AI_MEMORY_BASE_PATH` | Host the entire HTTP surface (`/mcp`, `/hook`, `/admin/*`, `/api/v1`, `/web`) under a configurable subpath, useful behind a reverse proxy sharing a hostname. `.` and `..` segments are rejected; unsafe chars cause a fallback to root with a warning. See [`docs/https-via-proxy.md`](https-via-proxy.md#hosting-under-a-subpath). || `--web-slug /web` | `AI_MEMORY_WEB_SLUG` | Where the web UI mounts within the base-path. Default `/web`; set to `/` to mount the UI at the base-path root. || `--web-ui-dir <path>` | `AI_MEMORY_WEB_UI_DIR` | Serve a custom SPA from `<path>` instead of the built-in browser. ai-memory injects `<base href>` and `<meta name="ai-memory-base-path">` so the SPA can build relative URLs and API calls under the configured prefix. |-| `--cors-allow-origin <origin>` | `AI_MEMORY_CORS_ALLOW_ORIGINS` (CSV) | Allow listed origins to call `/api/v1`. Layer is scoped only to that route — `/mcp`, `/hook`, `/admin`, and `/web` remain origin-locked. |+| `--cors-allow-origin <origin>` | `AI_MEMORY_CORS_ALLOW_ORIGINS` (CSV) | Allow listed origins to call `/api/v1`. The layer is scoped only to that route; `/mcp`, `/hook`, `/admin`, and `/web` remain origin-locked. || _(config only)_ | `AI_MEMORY_HOOK_RATE_PER_SEC`, `AI_MEMORY_HOOK_RATE_BURST` | Optional per-actor/session hook ingest token bucket. Unset/`0` rate disables it; burst defaults to the rate (minimum one token when enabled). |On macOS, see [`docs/macos.md`](macos.md); use the archive matching your@@ -1912,17 +1912,17 @@ If you set only the provider, ai-memory picks a sensible default:| `AI_MEMORY_LLM_PROVIDER=codex` | `gpt-5.6-luna` | Reuses only `access_token` and `account_id` from Codex's `auth.json`; token renewal is delegated to `codex app-server --stdio`. || `AI_MEMORY_LLM_PROVIDER=copilot` | `gpt-5.5` | GitHub Copilot Chat backend. ai-memory stores a GitHub user token in `<data_dir>/auth.json`, exchanges it for a short-lived Copilot API token, and refreshes before expiry. || `AI_MEMORY_LLM_PROVIDER=gemini` | `gemini-3.5-flash` | Google's hosted option with a generous free tier. ai-memory disables Gemini 3.5 Flash's default dynamic thinking so hidden thought tokens do not truncate strict JSON. Set `GEMINI_API_KEY` (or `GOOGLE_API_KEY`). |-| `AI_MEMORY_LLM_PROVIDER=opencode` | `mimo-v2.6-flash` | [OpenCode](https://opencode.ai) cloud API. Defaults to the **Go** endpoint, `opencode.ai/zen/go/v1` — a cost-optimised model subset. Published Responses models, including GPT-5.6 Luna and GPT-6 Luna, use `/responses`; supported Claude and Qwen Messages models use `/messages`. MiniMax M3/M2.7 and Qwen3.8 Max use Messages on Go and Chat Completions on Zen; Go Muse Contributor models use Responses. Changing the base URL reselects the transport and preserves request settings. See the [Go](https://opencode.ai/docs/go/#endpoints) and [Zen](https://opencode.ai/docs/zen/#endpoints) endpoint tables. For **Zen**'s full catalogue, set `AI_MEMORY_LLM_BASE_URL=https://opencode.ai/zen/v1` plus an `AI_MEMORY_LLM_MODEL` from it, such as `claude-sonnet-5-5`; the default model id is Go's. Requests identify ai-memory by version and reuse one session header across related attempts. Both endpoints take `OPENCODE_API_KEY` (key from `opencode.ai/auth`). Alias: `opencode-zen` — historical, and it selects Go like the others; the endpoint is chosen by the base URL, not the alias, with no automatic billing-product switch. |+| `AI_MEMORY_LLM_PROVIDER=opencode` | `mimo-v2.6-flash` | [OpenCode](https://opencode.ai) cloud API. Defaults to the **Go** endpoint, `opencode.ai/zen/go/v1`, a cost-optimised model subset. Published Responses models, including GPT-5.6 Luna and GPT-6 Luna, use `/responses`; supported Claude and Qwen Messages models use `/messages`. MiniMax M3/M2.7 and Qwen3.8 Max use Messages on Go and Chat Completions on Zen; Go Muse Contributor models use Responses. Changing the base URL reselects the transport and preserves request settings. See the [Go](https://opencode.ai/docs/go/#endpoints) and [Zen](https://opencode.ai/docs/zen/#endpoints) endpoint tables. For **Zen**'s full catalogue, set `AI_MEMORY_LLM_BASE_URL=https://opencode.ai/zen/v1` plus an `AI_MEMORY_LLM_MODEL` from it, such as `claude-sonnet-5-5`; the default model id is Go's. Requests identify ai-memory by version and reuse one session header across related attempts. Both endpoints take `OPENCODE_API_KEY` (key from `opencode.ai/auth`). Alias: `opencode-zen` (historical); it selects Go like the others, and the endpoint is chosen by the base URL, not the alias, with no automatic billing-product switch. || `AI_MEMORY_EMBEDDING_PROVIDER=openai` | `text-embedding-3-small` (1536-dim) | 5× cheaper than `-3-large` with marginal recall loss. || `AI_MEMORY_EMBEDDING_PROVIDER=openai` + `AI_MEMORY_EMBEDDING_BASE_URL=https://openrouter.ai/api/v1` | `openai/text-embedding-3-small` via [OpenRouter](https://openrouter.ai) | Uses `EMBEDDING_API_KEY`, else reuses `LLM_API_KEY` or `OPENAI_API_KEY`, with the OpenAI-compatible embedding client. || `AI_MEMORY_EMBEDDING_PROVIDER=openai` + `AI_MEMORY_EMBEDDING_BASE_URL=https://api.orcarouter.ai/v1` | `openai/text-embedding-3-small` via [OrcaRouter](https://www.orcarouter.ai) | Uses `EMBEDDING_API_KEY`, else reuses `LLM_API_KEY`, with the OpenAI-compatible embedding client. || `AI_MEMORY_EMBEDDING_PROVIDER=voyage` | `voyage-3` (1024-dim) | Voyage's current general-purpose recommendation. || `AI_MEMORY_EMBEDDING_PROVIDER=google` / `gemini` | `gemini-embedding-001` (768-dim) | Google-hosted embeddings via `embedContent`. Set `GEMINI_API_KEY` (or `GOOGLE_API_KEY`). |-| `AI_MEMORY_EMBEDDING_PROVIDER=openai-compat` | no default — set model, dim, and base URL explicitly | Self-hosted engines (Ollama, LM Studio, vLLM). Keyless by default; `EMBEDDING_API_KEY`, else `LLM_API_KEY`, is sent as a bearer token when present (gateways). Example: `AI_MEMORY_EMBEDDING_BASE_URL=http://localhost:11434/v1`, `AI_MEMORY_EMBEDDING_MODEL=nomic-embed-text`, `AI_MEMORY_EMBEDDING_DIM=768`. Switching an existing `openai`+base-URL setup to `openai-compat` changes the stored `{provider, model, dim}` triple — run `ai-memory embed --force` to re-embed. Asymmetric models need `AI_MEMORY_EMBEDDING_QUERY_PREFIX` / `AI_MEMORY_EMBEDDING_DOCUMENT_PREFIX`, e.g. `nvidia/Nemotron-3-Embed-1B-BF16` wants `query: ` / `passage: ` — see [`docs/llm-providers.md`](llm-providers.md) for that and for Qwen3-Embedding/instruction-tuned E5, which need a different (query-only) format. |-| `AI_MEMORY_EMBEDDING_PROVIDER=copilot` | `text-embedding-3-small` (1536-dim) | Reuses the `copilot` LLM provider's OAuth login (`ai-memory auth login copilot`, `COPILOT_GITHUB_TOKEN`, or `GITHUB_COPILOT_API_TOKEN`) — no separate API key. Calls Copilot's `/embeddings` endpoint following the OpenAI-compatible contract Copilot documents for chat; that endpoint's exact shape is not covered by a live test against Copilot here, so treat it as needing a real-Copilot smoke test. |+| `AI_MEMORY_EMBEDDING_PROVIDER=openai-compat` | no default; set model, dim, and base URL explicitly | Self-hosted engines (Ollama, LM Studio, vLLM). Keyless by default; `EMBEDDING_API_KEY`, else `LLM_API_KEY`, is sent as a bearer token when present (gateways). Example: `AI_MEMORY_EMBEDDING_BASE_URL=http://localhost:11434/v1`, `AI_MEMORY_EMBEDDING_MODEL=nomic-embed-text`, `AI_MEMORY_EMBEDDING_DIM=768`. Switching an existing `openai`+base-URL setup to `openai-compat` changes the stored `{provider, model, dim}` triple, so run `ai-memory embed --force` to re-embed. Asymmetric models need `AI_MEMORY_EMBEDDING_QUERY_PREFIX` / `AI_MEMORY_EMBEDDING_DOCUMENT_PREFIX`, e.g. `nvidia/Nemotron-3-Embed-1B-BF16` wants `query: ` / `passage: `. See [`docs/llm-providers.md`](llm-providers.md) for that and for Qwen3-Embedding/instruction-tuned E5, which need a different (query-only) format. |+| `AI_MEMORY_EMBEDDING_PROVIDER=copilot` | `text-embedding-3-small` (1536-dim) | Reuses the `copilot` LLM provider's OAuth login (`ai-memory auth login copilot`, `COPILOT_GITHUB_TOKEN`, or `GITHUB_COPILOT_API_TOKEN`), with no separate API key. Calls Copilot's `/embeddings` endpoint following the OpenAI-compatible contract Copilot documents for chat; that endpoint's exact shape is not covered by a live test against Copilot here, so treat it as needing a real-Copilot smoke test. |> **What we don't recommend:** reasoning-mode models (Claude with extended-> thinking, GPT-o3, Gemini "thinking" variants) — they burn token budget on+> thinking, GPT-o3, Gemini "thinking" variants). They burn token budget on> internal reasoning and hang or emit empty responses with the strict-JSON> consolidation prompt. Turn reasoning off if you must use one.@@ -1930,7 +1930,7 @@ If you set only the provider, ai-memory picks a sensible default:`EMBEDDING_API_KEY` is optional and credentials the embedding role alone. Setit when the embedder should authenticate against a different provider than the-LLM — the `openai` and `openai-compat` embedders otherwise borrow the chat+LLM. Otherwise the `openai` and `openai-compat` embedders borrow the chatmodel's `OPENAI_API_KEY` or `LLM_API_KEY`, which is then sent to whatever`AI_MEMORY_EMBEDDING_BASE_URL` points at and rejected with a 401.@@ -1960,7 +1960,7 @@ export EMBEDDING_API_KEY=sk-or-v1-...### Anthropic via Claude subscription (OAuth)> [!WARNING]-> **Unofficial and against Anthropic's usage policies — use at your own risk.**+> **Unofficial and against Anthropic's usage policies. Use at your own risk.**> Anthropic provides no public OAuth API for the Claude Pro/Max subscription;> this reuses the `claude setup-token` credential against `/v1/messages`, which> is **not a supported or sanctioned integration**. Anthropic's terms reserve@@ -1986,7 +1986,7 @@ export EMBEDDING_API_KEY=sk-or-v1-...`anthropic-oauth` is for Claude Pro/Max subscribers who want to use theirexisting subscription instead of an Anthropic Platform API key. It hits the-**same** `/v1/messages` endpoint as the `anthropic` provider — only the auth+**same** `/v1/messages` endpoint as the `anthropic` provider; only the authheaders differ (Bearer token + `anthropic-beta: oauth-2025-04-20`).```bash@@ -2026,9 +2026,9 @@ representative 0.2 value as bootstrap and consolidation, then exercises theprovider's compatibility normalization before sending the request.> [!TIP]-> **Pick a small, fast model.** ai-memory's LLM work — session-> consolidation, lint, and explore — is summarisation/extraction, not hard-> reasoning, so a Haiku-class model is plenty: faster, cheaper, and far easier+> **Pick a small, fast model.** ai-memory's LLM work (session+> consolidation, lint, and explore) is summarisation/extraction, not hard+> reasoning, so a Haiku-class model is enough. It is faster, cheaper, and far easier> on subscription rate limits than Sonnet/Opus. Set e.g.> `AI_MEMORY_LLM_MODEL=claude-haiku-4-5`. Save the high-effort thinking models> for your actual coding agent.@@ -2064,7 +2064,7 @@ Use `ai-memory auth status` to check whether a token is present and> [!TIP]> **Leave the model at the provider default (`gpt-5.5`).** The Codex/ChatGPT> backend behind `openai-oauth` only accepts a small server-defined set of model-> ids and rejects others — including `gpt-5-mini` — with a deterministic 400, so+> ids and rejects others, including `gpt-5-mini`, with a deterministic 400, so> do not set `AI_MEMORY_LLM_MODEL` for this backend. Consolidation / lint /> explore are summarisation tasks, so if the default reasoning is too heavy set> `AI_MEMORY_LLM_REASONING_EFFORT=none` or `low` instead, so hidden thought@@ -2271,7 +2271,7 @@ ceiling to match the gateway's worst-case generation time:Every chat request already carries `User-Agent: ai-memory/<version>`, so agateway can tell what is calling it. Some also require a header of their ownfor request correlation, and reject or throttle traffic without it. Declare-those once — they are sent on every chat request, whatever the provider:+those once; they are sent on every chat request, whatever the provider:```bash-e AI_MEMORY_LLM_HEADERS=x-opencode-session=prod-01,x-opencode-client=ai-memory@@ -2287,7 +2287,7 @@ overrides the default. Values are never logged.The `opencode` provider needs no configuration for this: OpenCode askscallers for `x-opencode-session`, and that provider already sends one id per-logical operation — stable across retries and the structured-output+logical operation. The id is stable across retries and the structured-outputfallback, so one consolidation pass reads as one operation in OpenCode'smetrics. Supply the header through `AI_MEMORY_LLM_HEADERS` to override that,for instance to tell several ai-memory instances apart under one account.@@ -2471,13 +2471,13 @@ remains opt-in and keeps its interval-only behavior (no startup catch-up).`reconcile_tombstones_deleted_pages` (default `false`, also under`[maintenance]`) is a separate, experimental opt-in: it lets the watcher'sown 30s reconcile pass (not the scheduled jobs above) tombstone an-OKF-imported content page (session summary pages are excluded — see+OKF-imported content page (session summary pages are excluded; see`docs/okf.md`) whose file has disappeared from disk, after it has beenmissing on two consecutive passes and survived a circuit breaker thatrefuses to act when more than `max(3, 50%)` of a scope's candidate pageslook missing at once, or when a walk finds nothing at all. The tombstone issoft (`is_latest = 0` + `superseded_at`, the same shape decay eviction uses)-and is picked up by the same aged-tombstone hard-delete sweep — it is not+and is picked up by the same aged-tombstone hard-delete sweep; it is notexempt from it. What actually protects it: a reconcile tombstone is neveritself destroyed while its chain has no successor; if the file returns, thenew version re-links to the tombstoned chain instead of starting fresh, so@@ -2596,8 +2596,8 @@ this is recoverable: review what landed, `docker exec ai-memory gitThe CLI and server write daily-rolling logs to `<data_dir>/logs/`(`~/.local/share/ai-memory/logs/` by default). When that location is not-writable — sandboxes like [ai-jail](https://github.com/akitaonrails/ai-jail)-mount `$HOME` read-only or as throwaway tmpfs — ai-memory degrades instead+writable (sandboxes like [ai-jail](https://github.com/akitaonrails/ai-jail)+mount `$HOME` read-only or as throwaway tmpfs), ai-memory degrades insteadof failing: it falls back to the OS temp dir, then to stderr-only logging,printing the exact path that failed at each step. Commands keep workingeither way. To keep durable file logs (and durable hook spooling) inside a@@ -2620,7 +2620,7 @@ an API key never logs into `/auth/login`.Set a one-shot password, then start `serve`. The engine creates the configured`root_username` (default `root`) with `must_change_password=true` and marksbootstrap complete. Later restarts ignore the value even if it stays in the-environment — unset it so the plaintext is not kept in process env.+environment, so unset it to keep the plaintext out of the process env.```bash# At least 12 characters. Must not equal the root bearer, actor-proxy bearer,@@ -2725,7 +2725,7 @@ named volume.`bootstrap` is in that list even though it only *reads* host files: anunmapped UID and a confined label block reads just as hard, and the failure is-misleading — it degrades silently to `no .git found at /work; bootstrapping+misleading: it degrades silently to `no .git found at /work; bootstrappingfrom README/docs/rules only` before dying with `Permission denied (os error13)`.@@ -2734,7 +2734,7 @@ The two engines report these facts under different keys. Docker answersfails that template, so the wrapper falls back to podman's`{{.Host.Security.Rootless}}` and `{{.Host.Security.SELinuxEnabled}}` when theDocker probe comes back empty. Rootless engines additionally need `-u 0:0`,-because only container UID 0 maps back to the invoking host user — on rootless+because only container UID 0 maps back to the invoking host user. On rootlesspodman with SELinux enforcing, both adjustments are required and neither alonelets the write land.@@ -2826,14 +2826,14 @@ in addition to the 128 MiB response-body cap. Windows uses rename-aside(`.exe` → `.old`, then promote `.new`) becausea running image cannot be overwritten in place. It refuses Homebrew/AUR/`/usr`installs (use the package manager), unwritable prefixes (for example Program-Files — download the zip manually), and in-container binaries (upgrade the+Files; download the zip manually), and in-container binaries (upgrade thehost wrapper/image instead). Windows aarch64 has no release asset yet. Formirrors or hermetic tests, set `AI_MEMORY_RELEASE_BASE_URL` (or`release_base_url` in config.toml) to a Releases-compatible base that serves`{base}/latest/tag` and `{base}/download/<tag>/<asset>` (+ `.sha256`). Thatoverride is a trust boundary: archive and checksum are fetched from the samebase, so the `.sha256` only proves the base served a consistent pair, not that-the binary is genuine — point it only at origins you control. Prefer an+the binary is genuine. Point it only at origins you control. Prefer an`https://` base; a plain-`http://` base has no transit protection, so anon-path attacker can substitute both the archive and its matching checksum.Each response body is capped at 128 MiB.@@ -2851,7 +2851,7 @@ to roll back to the previous version.### Upgrading to 2.3.02.3.0 is a normal forward upgrade (the only new migration, `V64`, just adds the-cross-project `agent_messages` table — nothing existing is altered or removed).+cross-project `agent_messages` table; nothing existing is altered or removed).Two capture/UX conveniences are **on by default**; both are additive andnon-destructive, but worth knowing about for your first session after upgrading:diff --git a/docs/issues-agentmemory.md b/docs/issues-agentmemory.mdindex 935008d0..630c3b1a 100644--- a/docs/issues-agentmemory.md+++ b/docs/issues-agentmemory.md@@ -8,21 +8,21 @@### 1. Install / ops - the single largest bucket- **`iii-engine` is a separate native binary** with its own version, config file, and storage layout. Pinning is fragile: `[email protected]` broke routing because `package.json` used `^0.11.2` (#555, fixed by PR #567 pinning exact). Migrating to `iii-database`/iii 0.11.7 is blocking the SQLite migration (#309 comment). The whole stack is held back by an upstream you don't control.-- **Distroless engine + Docker named volumes** = silent permission denied. UID 65532 can't write to root-owned `/data`; engine logs the error but the wrapper buffers in RAM and looks fine until restart wipes everything (#301 - still OPEN despite an earlier 0.9.7 "fix").-- **Engine writes `data/` to caller's `cwd`**, so launching from different directories produces different state stores. On Windows users believed memories vanished - they were stranded in `E:\文档\New project\data\state_store.db` while the dashboard read `C:\Users\Lenovo\data\` (#303, still OPEN even after PR #314 added `--data-dir`).+- **Distroless engine + Docker named volumes** = silent permission denied. UID 65532 can't write to root-owned `/data`; engine logs the error but the wrapper buffers in RAM and looks fine until restart wipes everything (#301, still OPEN despite an earlier 0.9.7 "fix").+- **Engine writes `data/` to caller's `cwd`**, so launching from different directories produces different state stores. On Windows users believed memories vanished; they were stranded in `E:\文档\New project\data\state_store.db` while the dashboard read `C:\Users\Lenovo\data\` (#303, still OPEN even after PR #314 added `--data-dir`).- **Hooks break on Windows when username has spaces** because `hooks.json` doesn't quote `${CLAUDE_PLUGIN_ROOT}` (#477).-- **Runaway log feedback loop** - `iii::workers::observability` warns about "subscriber lagged", that warn is captured by the same subscriber: 137 GB `daemon.log.new`, system at 98% (#519, still OPEN; `RUST_LOG` not honoured).+- **Runaway log feedback loop**: `iii::workers::observability` warns about "subscriber lagged", and that warn is captured by the same subscriber: 137 GB `daemon.log.new`, system at 98% (#519, still OPEN; `RUST_LOG` not honoured).### 2. Data integrity / silent loss- **State persistence buffered behind a 5s `IndexPersistence` debounce**. When `state::set` times out at 30s, the uncaught `IIIInvocationError` crashes the Node process, losing every in-memory BM25/vector update since the last debounce flush (#204).- **BM25 index `mem%3Aindex%3Abm25.bin` stays at ~96 bytes** because every `state::set` times out at 180s on 10k-observation corpora; each restart pays a 5-minute rebuild (#309, OPEN).- **Sessions never end on Ctrl-C / SSH-drop / laptop sleep**, so the consolidation + graph-extraction pipeline never fires, then the eviction sweep deletes the entire session (#308, "graph would-have-extracted content is permanently lost").-- **`AGENTMEMORY_DROP_STALE_INDEX=true` in `.env` did nothing** - the dimension guard read `process.env` directly while everything else reads `getMergedEnv()`. **Two config-read paths in the same codebase** (#456). Combined with #469 (vector index 2048-dim on disk vs 384-dim from provider), stranded users with no working recovery path.-- **Sessions never created, but observations were** - separate KV scopes; OpenClaw plugin only wrote observations, so `GET /sessions` returned `[]` (#522, OPEN). Masked by `postJson({fallback_on_error:true})` swallowing the 4xx.+- **`AGENTMEMORY_DROP_STALE_INDEX=true` in `.env` did nothing**: the dimension guard read `process.env` directly while everything else reads `getMergedEnv()`. **Two config-read paths in the same codebase** (#456). Combined with #469 (vector index 2048-dim on disk vs 384-dim from provider), stranded users with no working recovery path.+- **Sessions never created, but observations were**: separate KV scopes; OpenClaw plugin only wrote observations, so `GET /sessions` returned `[]` (#522, OPEN). Masked by `postJson({fallback_on_error:true})` swallowing the 4xx.- **`session.summary` and `session.firstPrompt` set to the same truncated title** (#276, OPEN, labelled CRITICAL).### 3. LLM compression / token-cost-- **`AGENTMEMORY_AUTO_COMPRESS=true` was the default in v0.8.7**. User olcor1: *"My allocation is busted within 20 minutes."* - the PostToolUse hook called the LLM on every tool call (#138, brown-paper-bag fix in v0.8.8 flipping default to false). Maintainer: *"this is a real bug in the tool's design, not your setup."*+- **`AGENTMEMORY_AUTO_COMPRESS=true` was the default in v0.8.7**. User olcor1: *"My allocation is busted within 20 minutes."* The PostToolUse hook called the LLM on every tool call (#138, brown-paper-bag fix in v0.8.8 flipping default to false). Maintainer: *"this is a real bug in the tool's design, not your setup."*- **`SessionStart` hook was injecting ~1-2 K tokens into every new session**. Maintainer initially blamed Claude Pro caps, then retracted and gated injection behind `AGENTMEMORY_INJECT_CONTEXT=false` default in v0.8.10 (#143). His own retraction: *"I pattern-matched without verifying against the docs."*- **`mem::compress` silently failed on ~47% of Claude Code tool calls** because `post-tool-use.mjs` read `data.tool_output` but Claude Code sends `tool_response` (#539, fixed PR #561).- **Graph extraction parser drops self-closing `<entity .../>` tags** (#492). Same family: #338.@@ -30,12 +30,12 @@### 4. Retrieval quality / API contract- **MCP `memory_recall` was aliased to `smart_search` and dropped the `format` param**, so full content was unreachable via MCP no matter what the caller asked for (#440 + #507, fixed PR #516). Six weeks of users getting only compact-mode hits.- **Viewer/status show 0 memories on real corpora** because `/agentmemory/memories?latest=true` and `/agentmemory/export` materialize the entire list, time out on >8k memories (#544, OPEN).-- **Event-loop starvation from pure-JS dot products** - VectorIndex.search hangs the loop on 100k vectors; sqlite-vec swap took search from 200-250 ms to 20-40 ms (#195).+- **Event-loop starvation from pure-JS dot products**: VectorIndex.search hangs the loop on 100k vectors; sqlite-vec swap took search from 200-250 ms to 20-40 ms (#195).### 5. Agent integration / MCP surface- **Claude Code requested protocol version 2025-03-26 but the shim pinned 2024-11-05**; Claude Code discarded the tools list as a result (#510, OPEN). Same root in #553 (OpenCode 8/51 tools) and #400.- **Codex worktrees treated as separate projects**, fragmenting lessons/sessions per ephemeral worktree path (#515, OPEN).-- **Hooks blocked startup** - `await fetch(... 5000 ms timeout)` on session-start; 10 parallel `claude -p` jobs OOM-killed the engine (#221, fixed PR #222 making hooks fire-and-forget).+- **Hooks blocked startup**: `await fetch(... 5000 ms timeout)` on session-start; 10 parallel `claude -p` jobs OOM-killed the engine (#221, fixed PR #222 making hooks fire-and-forget).## Design choices that caused the most issues@@ -50,8 +50,8 @@## Maintainer fixes reveal regrets-- **Auto-compress flipped from default-on to default-off** in v0.8.8 the same day #138 was filed - *"the closest thing to an admission that the headline feature was the headline misfeature"*. *"This is exactly the kind of brown-paper-bag issue."*-- **Context injection moved behind `AGENTMEMORY_INJECT_CONTEXT=false`** in v0.8.10 (#143) - maintainer publicly retracted a wrong first diagnosis. Two defaults reversed in two minor versions.+- **Auto-compress flipped from default-on to default-off** in v0.8.8 the same day #138 was filed: *"the closest thing to an admission that the headline feature was the headline misfeature"*. *"This is exactly the kind of brown-paper-bag issue."*+- **Context injection moved behind `AGENTMEMORY_INJECT_CONTEXT=false`** in v0.8.10 (#143); the maintainer publicly retracted a wrong first diagnosis. Two defaults reversed in two minor versions.- **`VECTOR_BACKEND=sqlite-vec` introduced behind a flag**, not flipped on, explicitly because *"some Windows / Alpine Docker users will hit install issues we can't preempt"* (#195).- **Multiple GH-packages mirror experiments reverted within hours** - PRs #545 → #547 → #548. Lots of try/revert.- **PR #500: rebuildIndex made non-blocking on boot**, PR #504: batch-embed in rebuildIndex (25 h → 3 h on large corpora). Admits the original boot path made the daemon unusable for hours.@@ -59,11 +59,11 @@## Still-open architectural debts-- **#309 in-memory BM25/graph → SQLite/FTS5** - blocked on iii v0.11.7. Biggest debt in the repo.-- **#519 daemon.log feedback loop** - offending warn is inside the closed-source `iii` binary.-- **#303 cwd-relative state store on Windows** - still leaks the wrong dir despite #314.-- **#301 distroless docker volume permissions** - still OPEN.-- **#510 / #553 / #400 MCP protocol-version negotiation** - three reports, same root cause.+- **#309 in-memory BM25/graph → SQLite/FTS5**: blocked on iii v0.11.7. Biggest debt in the repo.+- **#519 daemon.log feedback loop**: the offending warn is inside the closed-source `iii` binary.+- **#303 cwd-relative state store on Windows**: still leaks the wrong dir despite #314.+- **#301 distroless docker volume permissions**: still OPEN.+- **#510 / #553 / #400 MCP protocol-version negotiation**: three reports, same root cause.## Seven "do not repeat" lessons for the Rust rewrite@@ -81,7 +81,7 @@7. **Don't depend on an unpinned native sidecar.** Statically link the engine (`tantivy` for BM25, `sqlite-vec` via `rusqlite`, `petgraph` for the concept graph) (#301, #519, #555). Half the install issues in the tracker exist because `iii-engine` is a separate binary the wrapper can't fix.-**Bonus:** Default the data directory to a canonicalized absolute platform path (`dirs::data_local_dir().join("ai-memory")`) and log it loudly on startup - single change would have prevented #303 entirely.+**Bonus:** Default the data directory to a canonicalized absolute platform path (`dirs::data_local_dir().join("ai-memory")`) and log it loudly on startup. That single change would have prevented #303 entirely.### Driver issues#138 (auto-compress default), #143 (context-injection default), #195 (CPU-bound JS), #204 (uncaught SDK timeout), #221 (blocking hooks), #274 (lesson discard), #276 (corrupt session fields), #301 (distroless volume), #303 (cwd state), #308 (sessions never end), #309 (in-memory BM25), #338/#492 (XML parser), #440/#507 (MCP recall aliased), #456/#469 (dim mismatch + two env paths), #477 (Windows quoting), #510/#553/#400 (MCP protocol version), #515 (Codex worktrees), #519 (log feedback loop), #522 (silent error swallow), #539 (tool_response vs tool_output), #540 (no lockfile), #544 (unbounded list endpoints), #555 (iii-sdk semver).diff --git a/docs/issues-basic-memory.md b/docs/issues-basic-memory.mdindex 09ca0f23..d1319935 100644--- a/docs/issues-basic-memory.md+++ b/docs/issues-basic-memory.md@@ -1,60 +1,60 @@# basic-memory - Issue & PR Pain-Point Synthesis> Source: GitHub `basicmachines-co/basic-memory`. Captured 2026-05-21.-> Tracker is unusually high-signal — small team, deep technical replies.+> Tracker is unusually high-signal: small team, deep technical replies.> Dominant themes: sync correctness, multi-project routing, embedding install hell.## Top recurring pain points (ranked)### 1. Sync correctness & file-watcher reliability - the single biggest theme-- **#580** - watch service can go stale while process stays alive (no heartbeat, no liveness signal, `awatch()` blocks forever on macOS FSEvents buffer overflow). Closed with partial fix.-- **#758** - watch service ignored the `--project` constraint, N concurrent MCP processes produced N overlapping watchers and races. The fix found *three independent bugs* while fixing one.-- **#798** - watch service silently dropped events under hidden-directory parents (e.g., projects under `~/.claude/...`) because gitignore-style globs treated *every* component starting with `.` as hidden.-- **#765** - "Stale FTS index entries persist after `reset --reindex`": fixed by detecting **zombie MCP processes holding the old SQLite inode** after `unlink`. > *"That process keeps its connection to the old `memory.db` inode (now unlinked but not freed)... newly-spawned MCP processes attach to the new file. But any tool call that gets routed to a zombie MCP process queries the **old** inode."* Now `bm reset` refuses to run while MCP processes are alive (PR #776).-- **#763** - `write_note` returns *before* semantic indexing completes. Maintainer defends this as intentional architecture but admits the CLI path loses embeddings on process exit.-- **#839** (OPEN) - CLI `write-note` prints `CancelledError` traceback because `_log_task_failure` doesn't handle task cancellation on process exit. Same root cause as #763.-- **#578** - *new entities silently skip embedding generation* after a single sqlite-vec load failure. Background task errors fire-and-forget.-- **#634** - schema-validate uses stale `entity_metadata` when files edited externally.-- **#481** - `alembic/env.py` was unconditionally setting `BASIC_MEMORY_ENV="test"` at module import time, which silently disabled the watch service in production.+- **#580**: watch service can go stale while process stays alive (no heartbeat, no liveness signal, `awatch()` blocks forever on macOS FSEvents buffer overflow). Closed with partial fix.+- **#758**: watch service ignored the `--project` constraint, N concurrent MCP processes produced N overlapping watchers and races. The fix turned up *three independent bugs*.+- **#798**: watch service silently dropped events under hidden-directory parents (e.g., projects under `~/.claude/...`) because gitignore-style globs treated *every* component starting with `.` as hidden.+- **#765**: "Stale FTS index entries persist after `reset --reindex`": fixed by detecting **zombie MCP processes holding the old SQLite inode** after `unlink`. > *"That process keeps its connection to the old `memory.db` inode (now unlinked but not freed)... newly-spawned MCP processes attach to the new file. But any tool call that gets routed to a zombie MCP process queries the **old** inode."* Now `bm reset` refuses to run while MCP processes are alive (PR #776).+- **#763**: `write_note` returns *before* semantic indexing completes. Maintainer defends this as intentional architecture but admits the CLI path loses embeddings on process exit.+- **#839** (OPEN): CLI `write-note` prints `CancelledError` traceback because `_log_task_failure` doesn't handle task cancellation on process exit. Same root cause as #763.+- **#578**: *new entities silently skip embedding generation* after a single sqlite-vec load failure. Background task errors fire-and-forget.+- **#634**: schema-validate uses stale `entity_metadata` when files edited externally.+- **#481**: `alembic/env.py` was unconditionally setting `BASIC_MEMORY_ENV="test"` at module import time, which silently disabled the watch service in production.### 2. Multi-project / multi-workspace routing - the v0.20 trauma cluster-A wave of nearly identical bugs in April–May 2026: **#782, #783, #788, #793, #799, #800, #802, #803, #804, #805, #810, #820, #834**. Every one of them is the same shape: an MCP tool ignores or mis-resolves a project/workspace identifier. Maintainer on #783: > *"Permalinks are unique per project but project is not unique per workspace... any tool that holds only a permalink string cannot distinguish between them."* **Architecture catching up to ambition**: permalinks were designed as a 2-tuple (project, path) and later had to grow a third dimension (workspace) under load.+A wave of nearly identical bugs in April–May 2026: **#782, #783, #788, #793, #799, #800, #802, #803, #804, #805, #810, #820, #834**. All have the same shape: an MCP tool ignores or mis-resolves a project/workspace identifier. Maintainer on #783: > *"Permalinks are unique per project but project is not unique per workspace... any tool that holds only a permalink string cannot distinguish between them."* Permalinks were designed as a 2-tuple (project, path) and later had to grow a third dimension (workspace) under load.### 3. SQLite-vec / embedding provider install hell-- **#735 / #767** - duplicates: "no such module: vec0" on Windows in worker connections. Fixed by ensuring `_ensure_sqlite_vec_loaded` is called on *every* session that touches vec0.-- **#829 / #658** - still-open variants.-- **#741 / #681** - FastEmbed cache defaulted to `/tmp/fastembed_cache`, wiped in sandboxed runtimes like Codex CLI, causing `ONNXRuntimeError: NO_SUCHFILE` on every subsequent semantic search.-- **#830** (OPEN) - `docker-compose-postgres.yml` ships plain `postgres:17` instead of `pgvector/pgvector:pg17`; semantic search silently fails.-- **#831** (OPEN) - `IndexError: pop from an empty deque` during async engine dispose on Postgres/asyncpg.+- **#735 / #767**: duplicates: "no such module: vec0" on Windows in worker connections. Fixed by ensuring `_ensure_sqlite_vec_loaded` is called on *every* session that touches vec0.+- **#829 / #658**: still-open variants.+- **#741 / #681**: FastEmbed cache defaulted to `/tmp/fastembed_cache`, wiped in sandboxed runtimes like Codex CLI, causing `ONNXRuntimeError: NO_SUCHFILE` on every subsequent semantic search.+- **#830** (OPEN): `docker-compose-postgres.yml` ships plain `postgres:17` instead of `pgvector/pgvector:pg17`; semantic search silently fails.+- **#831** (OPEN): `IndexError: pop from an empty deque` during async engine dispose on Postgres/asyncpg.### 4. Parser fragility (markdown-as-source-of-truth)-- **#738** - Parser captured Obsidian callout syntax (`> [!note]`) as observation categories.-- **#721** - `edit_note` fails on notes with long text around inline wikilinks because `relation_type` exceeds `MaxLen`.-- **#528** - Cloud sync prepended duplicate frontmatter to files that already had YAML.-- **#408** - YAML frontmatter parsing fails with unquoted colons in title.-- **#256** - *"Editing notes causes them to disappear from index"* - the search index DELETE was missing a `project_id` filter, so an edit in one project nuked search rows in every project with the same permalink.+- **#738**: Parser captured Obsidian callout syntax (`> [!note]`) as observation categories.+- **#721**: `edit_note` fails on notes with long text around inline wikilinks because `relation_type` exceeds `MaxLen`.+- **#528**: Cloud sync prepended duplicate frontmatter to files that already had YAML.+- **#408**: YAML frontmatter parsing fails with unquoted colons in title.+- **#256**: *"Editing notes causes them to disappear from index"*. The search index DELETE was missing a `project_id` filter, so an edit in one project nuked search rows in every project with the same permalink.### 5. Search quality / pagination-- **#693** - `read_note` pagination params were ignored at the API endpoint.-- **#354** - `tag:tagname` syntax silently treated as literal text.-- **#686** (OPEN) - user hitting MCP response size limits at 57 pages.-- **#666, #618, #603** (all OPEN) - reranking, time-decay, length normalization. Search ranking is admitted-weak by maintainers.+- **#693**: `read_note` pagination params were ignored at the API endpoint.+- **#354**: `tag:tagname` syntax silently treated as literal text.+- **#686** (OPEN): user hitting MCP response size limits at 57 pages.+- **#666, #618, #603** (all OPEN): reranking, time-decay, length normalization. Maintainers admit search ranking is weak.### 6. Backup / undo / git-- **#124** (OPEN since June 2025) - git-based undo. Maintainer wrote design spec but issue remains open: > *"there hasn't been an obvious way to handle when to commit. Commit on every change? Commit every so often, how often? Push to a remote? How to handle conflicts?"*-- **#59** - use `git diff` to prevent knowledge corruption/deletion. OPEN since March 2025.+- **#124** (OPEN since June 2025): git-based undo. Maintainer wrote design spec but issue remains open: > *"there hasn't been an obvious way to handle when to commit. Commit on every change? Commit every so often, how often? Push to a remote? How to handle conflicts?"*+- **#59**: use `git diff` to prevent knowledge corruption/deletion. OPEN since March 2025.### 7. Manual capture friction - present but indirect-**Nobody filed "I'm tired of telling the agent to remember."** But:-- **#297** - Cursor + basic-memory produce sensationalized progress logs (`BREAKTHROUGH - Live Data Packets Detected!`) that pollute search results. Maintainer closes as **not basic-memory's fault, it's the LLM's**: > *"It is just the tools. Your LLM is in charge of how to use it."* That's the philosophical commitment that drives the manual `write_note` workflow - transferring all the noise problems onto the user.-- **#669, #730, #687** (all OPEN) - three separate proposals to add a *sidecar that watches session transcripts and builds the knowledge graph automatically*. **The strongest signal that manual capture is friction.** The maintainer is interested but hasn't started.+**Nobody filed "I'm tired of telling the agent to remember."** The friction shows up indirectly:+- **#297**: Cursor + basic-memory produce sensationalized progress logs (`BREAKTHROUGH - Live Data Packets Detected!`) that pollute search results. Maintainer closes it as **the LLM's fault, not basic-memory's**: > *"It is just the tools. Your LLM is in charge of how to use it."* That position drives the manual `write_note` workflow and moves all the noise problems onto the user.+- **#669, #730, #687** (all OPEN): three separate proposals to add a *sidecar that watches session transcripts and builds the knowledge graph automatically*. **This is the strongest signal that manual capture is friction.** The maintainer is interested but hasn't started.## Design choices that caused the most issues@@ -81,25 +81,25 @@ A wave of nearly identical bugs in April–May 2026: **#782, #783, #788, #793, ### Still-unsolved open issues - and why they're hard-- **#124 git-based undo** - open 11+ months. Hard because commit cadence is ill-defined and conflicts in markdown trees are nasty.-- **#834 local project_id routing in mixed cloud mode** - same root cause keeps spawning new symptoms.-- **#382 / #686 large-context handling** - pagination of search results into LLM context windows is still unsolved.-- **#740 startup time** - 4.6s for `--help` because FastMCP/onnxruntime/fastembed are imported eagerly. Multi-file lazy-import refactor not shipped.-- **#830 / #831 / #829 Postgres + sqlite-vec footguns** - install path still surprises users.-- **#669 / #687 transcript-watching sidecar** - the holy grail; nobody has built it.+- **#124 git-based undo**: open 11+ months. Hard because commit cadence is ill-defined and conflicts in markdown trees are messy.+- **#834 local project_id routing in mixed cloud mode**: same root cause keeps spawning new symptoms.+- **#382 / #686 large-context handling**: pagination of search results into LLM context windows is still unsolved.+- **#740 startup time**: 4.6s for `--help` because FastMCP/onnxruntime/fastembed are imported eagerly. Multi-file lazy-import refactor not shipped.+- **#830 / #831 / #829 Postgres + sqlite-vec footguns**: install path still surprises users.+- **#669 / #687 transcript-watching sidecar**: a long-wanted feature; nobody has built it.## Concrete "do not repeat" lessons for the Rust rewrite-1. **Do not background-task the indexing pipeline behind the tool reply.** `write_note → return → embed later` makes the tool a liar; the next `search_notes` may miss the entity. (#763, #578, #839, #685). Either make indexing synchronous and bounded, or return a structured `index_status: pending|complete` so the caller can `--wait`.+1. **Do not background-task the indexing pipeline behind the tool reply.** `write_note → return → embed later` makes the tool report success too early; the next `search_notes` may miss the entity. (#763, #578, #839, #685). Either make indexing synchronous and bounded, or return a structured `index_status: pending|complete` so the caller can `--wait`.2. **Bake the identity dimension in from day one.** `(workspace, project, permalink)` is a 3-tuple. Retrofitting it caused 12+ bugs (#782/#783/#788/#793/#799/#800/#802/#803/#804/#805/#810/#820/#834). The Rust schema should encode the full coordinate at every layer, even when you only ship single-workspace mode.3. **Liveness > correctness assumptions for the watcher.** A long-lived file watcher *will* go stale. Build heartbeats, watchdog timers, and "did we miss any events" reconciliation passes from the start. (#580, #758, #798). Treat every notify-rs-style loop as suspect.-4. **Treat the embedding/vector backend as a fallible plugin, not a default-on assumption.** sqlite-vec, pgvector, FastEmbed, ONNX - every one of them has bitten basic-memory (#735, #767, #741, #681, #830, #831, #658, #829, #578). In Rust, isolate the embedder behind a trait, fail loudly at startup if the backend can't load (don't silently degrade like #578), and don't default cache paths to `/tmp`.+4. **Treat the embedding/vector backend as a fallible plugin, not a default-on assumption.** sqlite-vec, pgvector, FastEmbed, ONNX: every one of them has bitten basic-memory (#735, #767, #741, #681, #830, #831, #658, #829, #578). In Rust, isolate the embedder behind a trait, fail loudly at startup if the backend can't load (don't silently degrade like #578), and don't default cache paths to `/tmp`.5. **Make `reset` safe.** Unlinking SQLite while a sibling process holds the inode = mystery phantom search results (#765). Acquire an exclusive advisory lock, or psutil-style live-process check before any destructive op.-6. **No inline DDL at runtime, ever.** #727's Postgres deadlock from runtime `ALTER TABLE`. Migrations are migrations; never let "ensure table" code paths execute schema changes.+6. **No inline DDL at runtime, ever.** #727 was a Postgres deadlock from runtime `ALTER TABLE`. Keep schema changes in migrations; never let "ensure table" code paths execute schema changes.-7. **For the manual-capture problem**: the absence of *explicit* complaints in the tracker is a trap. The complaints are encoded as (a) repeated proposals for a transcript-watching sidecar (#669, #687, #730), (b) Cursor-pollution complaints maintainers close as not-our-problem (#297), and (c) the "what should we commit" indecision in #124. **A Rust rewrite that listens to a Claude Code/Codex transcript directory and writes notes without an `@-mention` would convert the loudest implicit pain into the headline feature.**+7. **For the manual-capture problem**: the absence of *explicit* complaints in the tracker is misleading. The complaints show up as (a) repeated proposals for a transcript-watching sidecar (#669, #687, #730), (b) Cursor-pollution complaints maintainers close as not-our-problem (#297), and (c) the "what should we commit" indecision in #124. **A Rust rewrite that listens to a Claude Code/Codex transcript directory and writes notes without an `@-mention` would turn the loudest implicit pain into the headline feature.**diff --git a/docs/issues-cognee.md b/docs/issues-cognee.mdindex c032439c..ad055296 100644--- a/docs/issues-cognee.md+++ b/docs/issues-cognee.md@@ -9,7 +9,7 @@### A. LLM-adapter brittleness (highest volume, highest churn)Every provider has had a wire-level bug in 2026.-- Anthropic adapter dropped `max_tokens`, every call HTTP-422 (#2749, #2782 - **two consecutive releases shipped broken Anthropic**).+- Anthropic adapter dropped `max_tokens`, every call HTTP-422 (#2749, #2782; **two consecutive releases shipped broken Anthropic**).- Ollama / LlamaCpp adapters missing `@observe` decorator (#2820).- vLLM hangs because system message sent after user message (#2537).- vLLM "custom" provider doesn't forward `LLM_ENDPOINT` to LiteLLM (#2412, #2430, #2842).@@ -24,11 +24,11 @@ Every provider has had a wire-level bug in 2026.### B. Multi-store coordination & data integrity bugsThe "graph + vector + relational" tripartite store is the cognee architectural commitment, and it is the source of consistent, high-severity bugs.-- `EntityAlreadyExistsError` - `Entity("institution")` and `EntityType("institution")` collide on UUID (#2510). Second `cognify` blew up.+- `EntityAlreadyExistsError`: `Entity("institution")` and `EntityType("institution")` collide on UUID (#2510). Second `cognify` blew up.- `add_data_points` parallel DB ops cause SQLite `database is locked` deadlock; **still reproducible in 1.0.2**: `multiple PipelineRunErrored ... elapsed 561s before crash` (#2717, OPEN).- `cognify` exceeds asyncpg bind-argument limit during `upsert_edges` for large batches (~4356 edges) (#2829, fixed via batching in #2798, #2586).- `add_data_points` crashes with `asyncpg.CharacterNotInRepertoireError` on null bytes (0x00) (#2612, OPEN).-- `index_data_points`: shallow copy of metadata dict - only the first `index_field` is embedded (#2529, OPEN).+- `index_data_points`: shallow copy of metadata dict, so only the first `index_field` is embedded (#2529, OPEN).- `get_graph_from_model + copy_model` drops user-defined DataPoint id (#2633, OPEN).- Edge deduplication in `retrieve_existing_edges` is non-functional (#2557).- `delete_dataset` fails in non-"public" Postgres schema (#2291).@@ -39,24 +39,24 @@ The "graph + vector + relational" tripartite store is the cognee architectural c### C. Recall quality regressions - the bug a memory server cannot afford-- **#2720 (OPEN)**: "Graph-completion retrieval returns identical subgraph regardless of query". User-built reproducer shows direct LanceDB queries return different top-K for different queries, but cognee's `/api/v1/search` returns ~identical answers - LanceDB IDs are not propagating into the graph projection. User attributes to fallout from #2451: downstream thresholds in `brute_force_triplet_search.py` still expect pre-#2451 [0,1] scale and silently fall back to an unfiltered graph.+- **#2720 (OPEN)**: "Graph-completion retrieval returns identical subgraph regardless of query". User-built reproducer shows direct LanceDB queries return different top-K for different queries, but cognee's `/api/v1/search` returns ~identical answers because LanceDB IDs are not propagating into the graph projection. User attributes to fallout from #2451: downstream thresholds in `brute_force_triplet_search.py` still expect pre-#2451 [0,1] scale and silently fall back to an unfiltered graph.- `SearchType.CHUNKS` silently ignores `node_name` filtering (#2815).-- `CHUNKS/SUMMARIES/GRAPH_COMPLETION` ignores `datasets=` filter when `ENABLE_BACKEND_ACCESS_CONTROL=false` (#2867 - maintainer answer is essentially "datasets only work with access control on").+- `CHUNKS/SUMMARIES/GRAPH_COMPLETION` ignores `datasets=` filter when `ENABLE_BACKEND_ACCESS_CONTROL=false` (#2867; the maintainer's answer is essentially "datasets only work with access control on").- Cognee-mcp GRAPH_COMPLETION discarded all but first dataset (#2617).-- `TemporalRetriever` is event-only, blocks ontology-wide temporal filtering (#2429, closed as superseded by an internal Q2 redesign - not shipped).+- `TemporalRetriever` is event-only, blocks ontology-wide temporal filtering (#2429, closed as superseded by an internal Q2 redesign that has not shipped).- GRAPH_COMPLETION does not search custom DataPoint vector collections (#2495).### D. Dependency-installation hell- macOS arm64 + Python 3.14: `kuzu` wheel does not exist; quick-start fails (#2753).-- `ModuleNotFoundError: No module named 'kuzu' in Docker since v1.0.4` (#2775) - kuzu removed but image not rebuilt.+- `ModuleNotFoundError: No module named 'kuzu' in Docker since v1.0.4` (#2775): kuzu removed but image not rebuilt.- `fastembed` removed from the Docker image entirely because one of its transitive deps was not Apache/MIT (#2807).- LiteLLMEmbeddingEngine truncated `BAAI/bge-m3` to `bge-m3` (#1915).-- `embedding_dimensions` defaulted to 3072 regardless of model - every non-3072-dim embedder broke (#2751, fix #2757).+- `embedding_dimensions` defaulted to 3072 regardless of model, so every non-3072-dim embedder broke (#2751, fix #2757).- LanceDB lance-file writer schema drift / "contained null values" RuntimeError bypassed auto-migration (#2702, #2768).- Pydantic v1/v2 friction: upper bound conflicts with openai-agents (#2019); `.json()` deprecated (#2042); generic validation issues (#1198).- Mistral client import error (#2481).-- `lru_cache` hash invalidation bugs for Vector and Graph configs (#2357), and **`lru_cache` was eventually disabled outright** in PR #2853 - "refactor: reduce lru cache".+- `lru_cache` hash invalidation bugs for Vector and Graph configs (#2357), and **`lru_cache` was eventually disabled outright** in PR #2853 ("refactor: reduce lru cache").### E. MCP server bugs vs FastAPI@@ -64,14 +64,14 @@ The MCP wrapper consistently lags the core API.- MCP `cognify` with valid local file path returns success but creates no Data item (#2250, OPEN).- cognee-mcp Quick Start fails on macOS arm64 + Py 3.14 (#2753).- cognee-mcp `cognify(data=str)` silently dropped all writes after first due to hardcoded `data.txt` filename (#2747).-- MCP recall in default config fails: `'NoneType' object has no attribute 'id'` - wrapper does not pass user to cognee.recall (#2855).+- MCP recall in default config fails: `'NoneType' object has no attribute 'id'` because the wrapper does not pass user to cognee.recall (#2855).- cognee-cli `--api-url` doesn't support remember/recall/improve/forget (#2809, OPEN).- Frontend Docker build broken (#2832), Turbopack import case mismatch (#2605), `cognee-cli -ui` v0.5.5 missing 3 npm deps (#2413), UI compile errors (#2709).### F. Auth / multi-tenancy regressions- Token refresh mechanism literally not implemented; maintainer admits *"we had to reimplement it for our cloud deployment. At this point, we can't allocate resources"* (#2065).-- Request-scoped LLM config impossible because `get_llm_config()` and `get_embedding_config()` use `@lru_cache` - singletons (#2228).+- Request-scoped LLM config impossible because `get_llm_config()` and `get_embedding_config()` use `@lru_cache` singletons (#2228).- Auth disable needs *two* flags: `ENABLE_BACKEND_ACCESS_CONTROL=false` AND `REQUIRE_AUTHENTICATION=False` (#2808, fix #2836).- `cognee.search` ignored ACL when resolving dataset by name for non-owners (#2845); `cognee.add` silently created a new owner-scoped dataset when a non-owner reused a name (#2846); `cognify` silently skipped data added by non-owners (#2847).- Agent display name leaked user ID (#2811).@@ -82,11 +82,11 @@ The MCP wrapper consistently lags the core API.1. **Singleton config via `@lru_cache`.** Breaks multi-tenancy (#2228), invalidation bugs (#2357), eventually reverted (#2853).2. **LiteLLM + Instructor as the universal LLM/structured-output layer.** Source of #2412, #2430, #2537, #2608, #2613, #2749, #2782, #2820, #2840, #2842.3. **SQLite as the default relational backend with greenlet parallelism.** #2717: `OperationalError: database is locked` under parallel cognify, OPEN. Maintainer hedges: *"sqlite is not there for production use-cases"*.-4. **Kuzu as the default embedded graph DB.** Kuzu was archived upstream (#2098), maintainers chose to replace with **Ladybug** (PR #2755) - a *fork* of Kuzu. Immediate post-replacement bugs: #2768, #2775, WAL corruption (PR #2838). **The forked-DB risk has played out.**+4. **Kuzu as the default embedded graph DB.** Kuzu was archived upstream (#2098), maintainers chose to replace with **Ladybug** (PR #2755), a *fork* of Kuzu. Immediate post-replacement bugs: #2768, #2775, WAL corruption (PR #2838). **The forked-DB risk has already produced bugs.**5. **LanceDB as the default vector store** with schema migration assumed to auto-handle drift. Reality: #2702 null-values bypasses migration, #2720 retrieval pipeline drops filter on the path from vector hits to graph subgraph.6. **Tripartite store with implicit sync (graph + vector + relational + optional ontology).** Source of the entire integrity-bug class in section B. Orchestration is handled inside cognee, not by any transactional layer.7. **`@lru_cache` + ContextVar mixed model** for tenant isolation. #2228 explains: db config uses ContextVar pattern, but LLM and embedding configs do not.-8. **Per-collection distance normalization in `brute_force_triplet_search`** (#2030) - fix #2451 removed normalization, breaking downstream threshold assumptions, surfacing as #2720.+8. **Per-collection distance normalization in `brute_force_triplet_search`** (#2030). Fix #2451 removed normalization, breaking downstream threshold assumptions, surfacing as #2720.9. **Backend access control is the orchestration plane.** When `ENABLE_BACKEND_ACCESS_CONTROL=false`, *all* dataset-scoped retrieval silently degrades. (#2867, #2845, #2846, #2847, #2808.)10. **Default-LLM cost coupling**: `embedding_dimensions` defaults to 3072 (text-embedding-3-large), and litellm's `model_cost` table silently overrode user `max_completion_tokens`. Two bugs from "assume OpenAI defaults" (#2751, #2608).@@ -96,14 +96,14 @@ The MCP wrapper consistently lags the core API.- **Subprocess mode + Redis** was added explicitly to escape the SQLite-greenlet trap (#2803, #2812).- **Ladybug is a Kuzu fork** they own. Already shipped "fix: resolve issue with WAL file corruption for ladybug" (#2838).- **Auto-migrate LanceDB on schema drift** had to be added (#2703) after lance-file writer crashed workers.-- **Anthropic adapter broken for a full version cycle** - #2749 then re-broken in 1.0.5 as #2782.+- **Anthropic adapter broken for a full version cycle**: #2749, then re-broken in 1.0.5 as #2782.- **Defaults flipped**: `fastembed` removed from core (#2807), result-cache logging disabled by default (#2851), embedding dimensions auto-derived not defaulted (#2757), auth gated by single switch (#2836).- **Feature deprecated, not fixed**: `TemporalRetriever` (#2429).## Open issues maintainers haven't solved-- **#2717 SQLite deadlock under parallel cognify** - Reproducible across versions.-- **#2720 LanceDB filter not propagating to graph projection** - *Correctness* bug in core retrieval path. No assignee.+- **#2717 SQLite deadlock under parallel cognify**: reproducible across versions.+- **#2720 LanceDB filter not propagating to graph projection**: a *correctness* bug in core retrieval path. No assignee.- **#2840 Thinking-token + Instructor incompatibility.**- **#2532 N+1 query in `/api/v1/cognify`.**- **#2612 null-byte crash in asyncpg.**@@ -111,7 +111,7 @@ The MCP wrapper consistently lags the core API.- **#2228 request-scoped LLM/embedding config.** Architectural.- **#2065 token refresh.** Punted to community.-**What's hard about these**: they all sit at architectural seams (config plane, retrieval pipeline, async orchestration). Not one-PR fixes.+**What's hard about these**: they all sit at architectural seams (config plane, retrieval pipeline, async orchestration), so none is a one-PR fix.## Specific dependency culprits (Rust must bet differently)@@ -138,11 +138,11 @@ The MCP wrapper consistently lags the core API.1. **Do not put the LLM call behind a generic Python-style gateway that silently drops kwargs.** Each provider gets a typed Rust client that errors on unknown fields rather than dropping them. (#2840, #2608, #2782.)-2. **Don't use SQLite for write-parallel pipeline state.** Use Postgres or - for embedded - a single-writer actor in front of an LMDB/Sled/SQLite-with-WAL serialized via a queue. (#2717.)+2. **Don't use SQLite for write-parallel pipeline state.** Use Postgres or, for embedded, a single-writer actor in front of an LMDB/Sled/SQLite-with-WAL serialized via a queue. (#2717.)3. **Don't pin a forked embedded graph DB as the default.** Either commit to a battle-tested external store (Postgres + AGE, Neo4j) or build the graph primitives directly on the relational store. The Kuzu→Ladybug pivot cost real users (#2098, #2768, #2775, #2753, PR#2838).-4. **Treat retrieval filter propagation as a first-class invariant with property tests.** Show test cases like `assert different_queries_yield_different_subgraphs`. The exact bug in #2720 is what kills a memory product.+4. **Treat retrieval filter propagation as a first-class invariant with property tests.** Show test cases like `assert different_queries_yield_different_subgraphs`. A memory product cannot survive the exact bug in #2720.5. **Configuration must be per-request from day one.** No global singletons, no `lru_cache` over config. Use a request-scoped context type passed explicitly. (#2228, #2357, PR#2853.)@@ -154,10 +154,10 @@ The MCP wrapper consistently lags the core API.9. **Dataset isolation must work whether or not "access control" is on.** Dataset is a hard query-time filter on every retriever. (#2867, #2845, #2846, #2847.)-10. **Batch every cross-store mutation.** asyncpg bind-arg limit, SQLite locks, lance writer flushes - all rooted in unbounded fan-out (#2829, #2717, #2702).+10. **Batch every cross-store mutation.** asyncpg bind-arg limit, SQLite locks, lance writer flushes: all rooted in unbounded fan-out (#2829, #2717, #2702).-11. **Single transactional boundary or a documented eventual-consistency contract.** Cognee's silent skips between graph/vector/relational are the deepest class of bug. Pick one.+11. **Single transactional boundary or a documented eventual-consistency contract.** Cognee's silent skips between graph/vector/relational are the deepest class of bug, so pick one of the two.-12. **Audit logs and result caches with retention from day one.** Cognee's relational DB grew unbounded - 42k cached results in 9 days (#2548). They eventually disabled by default; do it before the first user hits it.+12. **Audit logs and result caches with retention from day one.** Cognee's relational DB grew unbounded: 42k cached results in 9 days (#2548). They eventually disabled by default; do it before the first user hits it.**Calibration**: the single most repeated lesson, weighted by both severity and recurrence: **the LLM/structured-output layer (LiteLLM + Instructor) is fragile, and the multi-store sync (graph + vector + relational) is the deepest source of correctness bugs.** A Rust rewrite that gets either of those wrong inherits cognee's tracker.diff --git a/docs/issues-mempalace.md b/docs/issues-mempalace.mdindex 2f7bb4a6..8e0bf3e4 100644--- a/docs/issues-mempalace.md+++ b/docs/issues-mempalace.md@@ -3,8 +3,8 @@> Source: GitHub `MemPalace/mempalace`.> Captured 2026-05-24. Repo: 52.7k stars, MIT, Python, created 2026-04-05,> v3.3.5, 241 open issues, ~1600 PRs in ~7 weeks. The maintainers publish-> unusually candid history notes (see `docs/HISTORY.md` — they publicly retract-> overclaims). Dominant themes: **ChromaDB/HNSW/FTS5 corruption under+> unusually candid history notes (see `docs/HISTORY.md`, where they publicly+> retract overclaims). Dominant themes: **ChromaDB/HNSW/FTS5 corruption under> concurrent writes**, **silent persistence failures**, **repair tooling that> destroys data**, **embedding-model drift**.@@ -18,138 +18,138 @@ all-MiniLM-L6-v2, zero API calls). Retrieval is hybrid vector + BM25 with a"closet" keyword-boost layer. Capture is via explicit `mempalace mine`, atranscript "convo miner", and Claude Code Stop/PreCompact hooks that spawndetached `mempalace mine` subprocesses. Claims 96.6% R@5 on LongMemEval (raw,-no LLM). It is a genuinely strong retrieval system whose pain is almost entirely-**operational/storage**, not retrieval.+no LLM). Its retrieval is strong; almost all of its pain is+**operational/storage**.## Top recurring pain points (ranked)### 1. Concurrent-write corruption of ChromaDB / HNSW / FTS5 - THE dominant themeThis single cluster is the majority of open bugs. Root cause: **multiple-uncoordinated writer paths to one ChromaDB store** - the Stop hook fires an+uncoordinated writer paths to one ChromaDB store**. The Stop hook fires anasync `mempalace mine` on every session end, the PreCompact hook fires another,the MCP server writes on tool calls, and manual `mempalace mine` can run at thesame time. ChromaDB's HNSW index and FTS5 shadow tables are not safe underconcurrent writers, and a writer killed mid-write (SIGTERM during compaction /permission prompts / window close) leaves a malformed index.-- **#1596** - *"The Claude Code Stop hook fires `mempalace mine` asynchronously+- **#1596**: *"The Claude Code Stop hook fires `mempalace mine` asynchronouslyon every session end. When multiple Claude sessions close simultaneously …multiple mine processes start with no mutual-exclusion guard. Theseoverlapping processes write to FTS5 shadow tables concurrently, and when oneis killed mid-write … it leaves `embedding_fulltext_search` in a malformedstate."* `PRAGMA integrity_check` returns `ok` (rows intact) but`quick_check` fails (FTS5 index malformed) → `repair` refuses to run.-- **#1599** - recurring FTS5 corruption under live writes, *after* the+- **#1599**: recurring FTS5 corruption under live writes, *after* thetransient-vector-failure mitigation that was supposed to fix it.-- **#1581** - HNSW corruption from concurrent ChromaDB clients (MCP server ++- **#1581**: HNSW corruption from concurrent ChromaDB clients (MCP server +hook subprocesses + auto-ingest mine) **within a single Claude Code session**.-- **#1253** - PreCompact hook double-ingest race corrupts HNSW: *"no+- **#1253**: PreCompact hook double-ingest race corrupts HNSW: *"nopalace-wide write lock."*-- **#1564** - even the single-writer sweep can trigger stale HNSW quarantine.-- **#1514** (community patch, in Chinese) - dual-client concurrent read/write:+- **#1564**: even the single-writer sweep can trigger stale HNSW quarantine.+- **#1514** (community patch, in Chinese): dual-client concurrent read/write:user shipped a `flock + threading.Lock` double-lock patch themselves.-- **#1343 / #974 / #965** (referenced) - the original "wrap every ChromaDB+- **#1343 / #974 / #965** (referenced): the original "wrap every ChromaDBwrite in `mine_palace_lock`" retrofit; corruption persists in edge cases.-- **#1497** (the tell) - a user asks: *"should MemPalace recommend a+- **#1497** (the tell): a user asks: *"should MemPalace recommend asingle-writer/gateway pattern for multi-agent setups? … our reading is:`mcp-proxy` helps avoid each client spawning its own server, but it does notby itself guarantee that all palace mutations are serialized."* They sketch a- gateway → write-queue → **single writer**. **They are proposing, in an- issue, the exact architecture ai-memory has by construction.**+ gateway → write-queue → **single writer**, which is the architecture+ ai-memory has by construction.### 2. Silent persistence failure - "filed N drawers" but nothing persistedThe write path returns success *before* the data is durably in ChromaDB. Below`hnsw:sync_threshold`, the HNSW segment + `index_metadata.pickle` never flush,-so small mines vanish while the CLI cheerfully reports success.+so small mines vanish while the CLI reports success.-- **#1597** - *"`mempalace mine` reports `Drawers filed: 40` … but the chromadb+- **#1597**: *"`mempalace mine` reports `Drawers filed: 40` … but the chromadbdoes not persist them. `mempalace status` keeps showing the pre-upgradetotal."* Confirmed not a cache issue (`mempalace_reconnect` agrees with thestale count). The v3.3.5 notes had specifically claimed *"integrity,recovery, and cross-process correctness."*-- **#1579** - mines smaller than `hnsw:sync_threshold` never persist+- **#1579**: mines smaller than `hnsw:sync_threshold` never persist`index_metadata.pickle`.-- **#1526** - silent empty index below batch threshold (one of two HNSW failure+- **#1526**: silent empty index below batch threshold (one of two HNSW failuremodes).-- **#1537** - `mempalace mine` reports `Done ✓` with full counts when the mine+- **#1537**: `mempalace mine` reports `Done ✓` with full counts when the mineproduced an FTS5-corrupt palace.-- **#1398** - MCP search returns `Error finding id` after bulk-add until WAL+- **#1398**: MCP search returns `Error finding id` after bulk-add until WALflushes; CLI works (read-after-write inconsistency).-- **#1489** - request to expose `hnsw:sync_threshold` because low-volume MCP+- **#1489**: request to expose `hnsw:sync_threshold` because low-volume MCPworkloads "never flush metadata."### 3. Repair/migrate tooling that cannot recover - or actively destroys dataWhen corruption happens (theme 1) the recovery path is itself unsafe.-- **#1394** - *"`mempalace repair --mode legacy` destroys 99% of SQLite+- **#1394**: *"`mempalace repair --mode legacy` destroys 99% of SQLiteembedding rows on 3.3.4."*-- **#1545** - `repair --mode from-sqlite` "structurally broken at scale:+- **#1545**: `repair --mode from-sqlite` "structurally broken at scale:auto-quarantine destroys rebuild progress mid-run."-- **#1586** - repair cannot recover combined HNSW-dimensionality + FTS5+- **#1586**: repair cannot recover combined HNSW-dimensionality + FTS5corruption (313k drawers).-- **#1589** - repair *rebuilds* an HNSW segment that ChromaDB 1.5.9 then cannot+- **#1589**: repair *rebuilds* an HNSW segment that ChromaDB 1.5.9 then cannotload; the corrupt segment SIGSEGVs in `chromadb_rust_bindings`.-- **#1595** - `mempalace-health.py` parses `header.bin` as uint32 →+- **#1595**: `mempalace-health.py` parses `header.bin` as uint32 →trillion-element HNSW corruption silently passes all checks.-- **#1266** - HNSW pickle corruption after long-running mine: "unsupported+- **#1266**: HNSW pickle corruption after long-running mine: "unsupportedopcode" on next read; repair/migrate cannot recover.-- **#1492 / #1493** - `rebuild_index` deterministically writes+- **#1492 / #1493**: `rebuild_index` deterministically writes`dimensionality=None` into ChromaDB's `index_metadata`.### 4. Data loss by design - miners and swaps destroy verbatim history-- **#1593** - *filed by the founder*: "stop delete-on-remine - verbatim history+- **#1593** (filed by the founder): "stop delete-on-remine - verbatim historyshould never be destroyed by MemPalace miners." Re-mining a source deletes the- old drawers first; for a system whose whole pitch is "verbatim, never lossy,"- this is an existential bug.-- **#1533** - MCP-server processes destroy newly-swapped palace files on first+ old drawers first, which contradicts the project's "verbatim, never lossy"+ pitch.+- **#1533**: MCP-server processes destroy newly-swapped palace files on firstread after an atomic swap (no quarantine re-arm).-- **#1341** - no `SessionEnd` hook: short sessions lose memories on clean exit+- **#1341**: no `SessionEnd` hook: short sessions lose memories on clean exit(only Stop/PreCompact exist, and they don't always fire).-- **#1535** - `mempalace mine --limit N` truncates files *before* the+- **#1535**: `mempalace mine --limit N` truncates files *before* thealready-mined skip, so a run can finish with 0 new drawers.-- **#1329** - Stop hook → 1.9 **TB** palace bloat + ChromaDB Rust-bindings+- **#1329**: Stop hook → 1.9 **TB** palace bloat + ChromaDB Rust-bindingssegfault (verbatim-everything with no decay → unbounded growth).### 5. Embedding-model drift & pluggability gaps-- **#1561** - "persist and verify embedding model metadata in palace+- **#1561**: "persist and verify embedding model metadata in palacecollections." There is currently **no stored `{provider, model, dim}` to- refuse on mismatch** - exactly the failure ai-memory's invariant #8 prevents.-- **#1559** - support external embedding APIs (LM Studio, Ollama,+ refuse on mismatch**, which is the failure ai-memory's invariant #8 prevents.+- **#1559**: support external embedding APIs (LM Studio, Ollama,OpenAI-compatible).-- **#1563 / #1261** - embedding model is hardcoded to all-MiniLM-L6-v2; users+- **#1563 / #1261**: embedding model is hardcoded to all-MiniLM-L6-v2; userswant configuration-driven switching without source edits.-- **#1380** - hash-embedding fallback mode needs a real BM25 lexical path.+- **#1380**: hash-embedding fallback mode needs a real BM25 lexical path.### 6. Native-binding / platform instability (the heavy-dependency tax)ChromaDB drags in `onnxruntime`, `grpcio`, `numpy`, and a Rust bindings layer.-- **#1355** - `chromadb_rust_bindings` segfaults on macOS 26.4 ARM64 - **all- `>=1.5.4,<2` versions affected**. Hard floor on a core dependency.-- **#1247** - Windows ONNX `bad_alloc` + convo mine crash.-- **#1488** - MCP server fails on Cyrillic/non-ASCII on Windows (cp1252 stdin).-- **#1570** - openai-compat provider probe blocked (403) on Cloudflare-fronted+- **#1355**: `chromadb_rust_bindings` segfaults on macOS 26.4 ARM64, with **all+ `>=1.5.4,<2` versions affected**. That puts a hard floor on a core dependency.+- **#1247**: Windows ONNX `bad_alloc` + convo mine crash.+- **#1488**: MCP server fails on Cyrillic/non-ASCII on Windows (cp1252 stdin).+- **#1570**: openai-compat provider probe blocked (403) on Cloudflare-frontedendpoints because of the default `Python-urllib` User-Agent.### 7. MCP correctness & scale-- **#1574** - MCP returns generic `-32000` instead of `-32602 (Invalid params)`+- **#1574**: MCP returns generic `-32000` instead of `-32602 (Invalid params)`on missing required params.-- **#1580** - `_expand_with_neighbors` stitches *unrelated* chunks across MCP+- **#1580**: `_expand_with_neighbors` stitches *unrelated* chunks across MCPdrawers that share an empty `source_file` (silent cross-contamination ofresults).-- **#1379** - overview tools time out on large palaces.-- **#1471** - "HNSW capacity divergence" check runs per-request in the MCP+- **#1379**: overview tools time out on large palaces.+- **#1471**: "HNSW capacity divergence" check runs per-request in the MCPserver (perf).### 8. Capture noise (markdown/transcript parsing)-- **#1333** - `<local-command-*>` tags and ANSI escapes survive+- **#1333**: `<local-command-*>` tags and ANSI escapes survive`strip_noise()`, polluting drawers (same class of problem as basic-memory#738 and our own Claude-Code-tag stripping).@@ -168,41 +168,39 @@ ChromaDB drags in `onnxruntime`, `grpcio`, `numpy`, and a Rust bindings layer.## How ai-memory compares (invariant-by-invariant)-The headline: **MemPalace's biggest pain cluster is the set of failures-ai-memory's cross-cutting invariants exist to prevent.** This is strong-external validation of the architecture, captured by someone else's 241 open-issues rather than our own.+**MemPalace's biggest pain cluster is the set of failures ai-memory's+cross-cutting invariants exist to prevent.** Someone else's 241 open issues+support the architecture choices we made.| MemPalace pain | ai-memory invariant that prevents it ||---|---|-| #1497/#1514/#1343 - debating/retrofitting a single-writer gateway; concurrent writers corrupt HNSW | **#2 Single-writer SQLite actor.** All writes through one mpsc channel, by construction, since M1. No retrofit. |-| #1597/#1579/#1537 - "filed N" but not persisted; write returns before durable | **#3 Indexes commit in the same transaction as the data.** No background-task-indexing-after-return; tool responses block until durable. |-| #1561/#1563 - no stored embedding model identity; drift on model change | **#8 `{provider, model, dim}` stored next to every embedding; refuse on mismatch.** Schema column since M1, enforced at startup. |-| #1394/#1545/#1586 - repair tooling destroys data it should save | **#17 Wiki migrations: no destructive deletes without a graveyard step** (`_graveyard/<migration>/…`) + **#10 atomic tmp+rename+fsync**. |-| #1593/#1533 - miners/swaps destroy verbatim history | **#10 Atomic file writes** + git-versioned wiki (M5): every page change is a commit, recoverable via `git`. |-| #1355/#1247/#1488 - native ONNX + Rust-bindings segfaults, platform floors | **Bundled `rusqlite` (static), pure-Rust, zero-LLM default path (#13).** Vectors (sqlite-vec) deferred to v0.2 precisely to avoid this class of dependency risk. |-| #1596/#1253 - hooks spawn N concurrent writer subprocesses | **#5 Hooks are fire-and-forget POST to one server** with one writer actor - never a process per event. |-| #1329 - verbatim-everything → 1.9 TB bloat | **Karpathy compile-don't-hoard** + **M8 decay/forget-sweep** + log rotation. We compress, we don't accumulate raw forever. |-| #1574 - wrong JSON-RPC error codes | rmcp typed `McpError` variants. (Worth a spot-check that we map param errors correctly - see "gotchas".) |+| #1497/#1514/#1343: debating/retrofitting a single-writer gateway; concurrent writers corrupt HNSW | **#2 Single-writer SQLite actor.** All writes through one mpsc channel, by construction, since M1. No retrofit. |+| #1597/#1579/#1537: "filed N" but not persisted; write returns before durable | **#3 Indexes commit in the same transaction as the data.** No background-task-indexing-after-return; tool responses block until durable. |+| #1561/#1563: no stored embedding model identity; drift on model change | **#8 `{provider, model, dim}` stored next to every embedding; refuse on mismatch.** Schema column since M1, enforced at startup. |+| #1394/#1545/#1586: repair tooling destroys data it should save | **#17 Wiki migrations: no destructive deletes without a graveyard step** (`_graveyard/<migration>/…`) + **#10 atomic tmp+rename+fsync**. |+| #1593/#1533: miners/swaps destroy verbatim history | **#10 Atomic file writes** + git-versioned wiki (M5): every page change is a commit, recoverable via `git`. |+| #1355/#1247/#1488: native ONNX + Rust-bindings segfaults, platform floors | **Bundled `rusqlite` (static), pure-Rust, zero-LLM default path (#13).** Vectors (sqlite-vec) deferred to v0.2 precisely to avoid this class of dependency risk. |+| #1596/#1253: hooks spawn N concurrent writer subprocesses | **#5 Hooks are fire-and-forget POST to one server** with one writer actor, never a process per event. |+| #1329: verbatim-everything → 1.9 TB bloat | **Karpathy compile-don't-hoard** + **M8 decay/forget-sweep** + log rotation. We compress instead of accumulating raw data forever. |+| #1574: wrong JSON-RPC error codes | rmcp typed `McpError` variants. (Worth a spot-check that we map param errors correctly; see "gotchas".) |## What ai-memory could learn / steal from MemPalace-These are the genuinely useful ideas worth a brainstorm - NOT yet adopted.+These ideas are worth a brainstorm. None is adopted yet.1. **A verbatim recall tier as a safety net under the compiled wiki.** This is- the deepest idea. MemPalace proves that *raw text + local semantic search*+ the most important idea. MemPalace shows that *raw text + local semantic search*scores 96.6% R@5 on LongMemEval with zero LLM. ai-memory compiles- observations into wiki pages - which is higher-signal but **lossy**:+ observations into wiki pages, which is higher-signal but **lossy**:consolidation can drop a detail the user later needs. We already keep `raw/`immutable session logs. When vectors land (v0.2), we could expose semanticsearch over the raw observation log as a *fallback recall path* when the- compiled wiki misses - "compiled-first, verbatim-fallback." Best of both+ compiled wiki misses ("compiled-first, verbatim-fallback"), combining bothphilosophies.2. **LongMemEval as a first-class, honest eval (our M10).** MemPalace has theharness wired and *publishes held-out R@5 with retractions* in- `docs/HISTORY.md`. Their `tests/test_readme_claims.py` - tests that fail the- build if a public claim isn't backed by code - is a clever, stealable- pattern. Adopt the methodology (held-out split, no headline-chasing) when we+ `docs/HISTORY.md`. Their `tests/test_readme_claims.py`, which fails the+ build if a public claim isn't backed by code, is a pattern worth copying. Adopt the methodology (held-out split, no headline-chasing) when webuild M10.3. **Deterministic IDs for idempotent, resume-safe ingest.** MemPalace's sweeperuses `session_id + message_uuid` deterministic drawer IDs + a cursor so a@@ -213,28 +211,29 @@ These are the genuinely useful ideas worth a brainstorm - NOT yet adopted.table; MemPalace's KG (`knowledge_graph.py`) and their #1416 "promote drawerclaims into KG triples at end of day" rhymes with our consolidation. Could bea future tier for "facts that change over time" (who owns X now vs. before).-5. **Index-health monitoring + a repair path - done safely.** When sqlite-vec+5. **Index-health monitoring + a repair path, done safely.** When sqlite-veclands in v0.2, monitor index health (MemPalace's link-to-data ratio guard is- smart) AND make repair graveyard-first. Their #1394/#1595 are the cautionary- tales: a repair that destroys rows, and a health check that parses a field+ a good model) AND make repair graveyard-first. Their #1394/#1595 show what+ goes wrong: a repair that destroys rows, and a health check that parses a fieldwrong and passes trillion-element corruption.6. **Transparent benchmark/claims culture.** A `HISTORY.md` that records- corrections builds more trust than a clean marketing page. Worth emulating.+ corrections builds more trust than a clean marketing page, and we should do+ the same.## Gotchas to AVOID that bit MemPalace (cautions for our v0.2 vector work)-- **Never report "indexed/saved" before durable commit** - even for vectors.- MemPalace #1597 is the whole movie. Invariant #3 already covers this; keep it- ironclad when sqlite-vec writes land.+- **Never report "indexed/saved" before durable commit**, even for vectors.+ MemPalace #1597 shows the full failure. Invariant #3 already covers this; keep+ it strict when sqlite-vec writes land.- **Stamp `{provider, model, dim}` on the collection and refuse on mismatch.**- MemPalace #1561 shows the cost of not doing it. We have it - don't regress.+ MemPalace #1561 shows the cost of not doing it. We have it; don't regress.- **Any re-embed / rebuild-index path must graveyard before delete.** MemPalace#1394 destroyed 99% of rows in a "repair." Invariant #17 already mandatesthis; apply it to vector rebuilds too.- **Keep hooks one-writer fire-and-forget.** Do not, under load, spawn a worker- per event (MemPalace #1596). Our design is safe; keep it.-- **Watch raw-log growth.** Verbatim is great for recall but #1329 hit 1.9 TB.- Our compile + decay + log rotation is the antidote - but if we add a verbatim+ per event (MemPalace #1596). Our current design avoids this; keep it.+- **Watch raw-log growth.** Verbatim helps recall but #1329 hit 1.9 TB.+ Our compile + decay + log rotation limits growth, but if we add a verbatimrecall tier (idea #1), give it a retention budget from the start.- **Spot-check MCP param-error codes.** MemPalace #1574 returns the wrongJSON-RPC code on missing params. Confirm rmcp maps our missing/invalid params@@ -250,17 +249,17 @@ Lesson for ai-memory: when/if it gains traction, expect typosquatting of thename, the install one-liner (`curl … | sh`), and the Docker image. Cheappre-emptive moves: claim the obvious domains, document the *only* officialinstall sources (GitHub repo, the `akitaonrails/ai-memory` Docker Hub image,-the raw wrapper URL on `main`), and pin/sign releases so users can verify. This-is a "popular-project" problem we don't have yet - but it's free to pre-empt.+the raw wrapper URL on `main`), and pin/sign releases so users can verify. We+don't have this "popular-project" problem yet, but preparing for it costs+nothing.## Bottom line-MemPalace is a strong, popular, well-tested retrieval engine with a smart-verbatim philosophy and admirably honest maintainers - and it is **drowning in-exactly the storage/concurrency/durability failures ai-memory designed around-from the first milestone**. The single most useful thing to take from it is-not a fix but a feature idea: a *verbatim semantic-recall fallback* beneath the-compiled wiki, so we get MemPalace's lossless recall without inheriting its-ChromaDB corruption surface. The single most useful thing to take as-reassurance: our invariants #2, #3, #8, #10, #17 are not over-engineering - they-are precisely the 241-open-issues someone else is living through.+MemPalace is a popular, well-tested retrieval engine with a sound verbatim+philosophy and honest maintainers, and it is **struggling with the+storage/concurrency/durability failures ai-memory designed around from the+first milestone**. The most useful thing to take from it is a feature idea: a+*verbatim semantic-recall fallback* beneath the compiled wiki, so we get+MemPalace's lossless recall without inheriting its ChromaDB corruption surface.+Its 241 open issues also show that our invariants #2, #3, #8, #10, #17 address+real failures and are not over-engineering.diff --git a/docs/jev-reranker-adapter.md b/docs/jev-reranker-adapter.mdindex b173f241..9a29f711 100644--- a/docs/jev-reranker-adapter.md+++ b/docs/jev-reranker-adapter.md@@ -6,8 +6,8 @@[`AI_MEMORY_RERANKER=llm`](llm-providers.md) reorders `memory_query`candidates with the configured chat provider. That works until the provideris a hosted reasoning model: the reranker prompt is long, a graded judgement-over up to 30 candidates, and a slow model answers in tens of seconds —-longer than one `memory_query` should ever take, and long enough to trip the+over up to 30 candidates, and a slow model answers in tens of seconds.+That is longer than one `memory_query` should ever take, and long enough to trip theserver's completion timeout, which turns the reranker into a dead featurethat stalls every query before falling back to the original order.@@ -37,8 +37,8 @@ configuration; it splits traffic by request shape:3. Each answer's rubric index maps back to `relevance` 0.0 / 0.3 / 0.7 /1.0 (index / 3), and the adapter returns`{"scores": [{"candidate": n, "relevance": f}]}` as plain chat-completion- content — the exact shape the reranker's tolerant parser expects.-4. Every other request — consolidation, lint, bootstrap, plain chats — is+ content, which is the exact shape the reranker's tolerant parser expects.+4. Every other request (consolidation, lint, bootstrap, plain chats) isreverse-proxied to the real upstream byte-for-byte, `Authorization`forwarded verbatim. The adapter stores no secrets.@@ -125,7 +125,7 @@ max 3.07 s), 110/110 rerank translations served, 0 adapter failures. Thegap to the offline arm is candidate-pool shape, not scoring: the liveserver over-fetches 15–30 candidates with its own bounded snippets (theoffline arm rescored a fixed top-10 pool), and in 32 of 34 non-top-1-queries the expected page was still returned — mostly at rank 2 — with+queries the expected page was still returned, mostly at rank 2, withhit@5 at 0.949. Versus the no-reranker baseline that is +16.2 pointshit@1 and +10.4 points NDCG@10 end to end.@@ -147,7 +147,7 @@ On a 30-candidate pool that wording moved the 35B from 0.828 to 0.879 hit@1below is the earlier choice-versus-rubric comparison, not that wording test.That is deliberately the substitution the caveat below used to warn about.-It is sound here because the reranker's consumer is **sort-only**: the+It is sound here because the reranker's consumer is sort-only: theserver reorders candidates by `relevance` and never thresholds or sums itsabsolute value, and a per-question monotonic map preserves order exactly.The old warning applies to consumers that *read* absolute relevance@@ -175,7 +175,7 @@ judge, the choice adapter is the difference between usable and not.Prefer the choice adapter when the reranker leg is the only consumer.Keep the rubric adapter if anything downstream reads absolute relevance-grades (thresholding, logging heuristics, score fusion) — choice+grades (thresholding, logging heuristics, score fusion), because choiceprobabilities carry no absolute meaning and their scale shifts withcandidate count.diff --git a/docs/lifecycle-ops.md b/docs/lifecycle-ops.mdindex 4751b60f..2ebcc5f3 100644--- a/docs/lifecycle-ops.md+++ b/docs/lifecycle-ops.md@@ -8,20 +8,20 @@ on a homelab box where mistakes are harder to undo.| Command | Safe with server **running**? | Wipes data? | Reversible? | Notes ||---|---|---|---|---|-| `purge-project --confirm` | ✅ yes | the one project's data, **plus** any observation stamped into a different project by one of this project's sessions (cascades regardless of the observation's own `project_id`), and it nulls (does not delete) the session reference on any handoff in a different project that this project's sessions authored or accepted | no | Deletes the UUID-namespaced wiki root and raw workstream segments. Refuses with `409` while a managed workstream under the project holds a live run lease — `--force` overrides. Logical delete by default; `--compact` additionally rebuilds the FTS indexes and `VACUUM`s (see below). Without `--confirm` it previews the same counts, including the cross-project ones, before refusing — see below. |-| `purge-session --session-id --confirm` | ✅ yes | the one session's data, **plus** any observation stamped into a different project by this session (cascades regardless of the observation's own `project_id`), and it nulls (does not delete) the session reference on any handoff in a different project that this session authored or accepted | no | Deletes one session by UUID: its row, its observations, the handoffs it **authored**, its `sessions/<id>.md` page and every superseded version, their embeddings, and its auto-improve runs. Strictly scoped — a session that does not belong to the named workspace/project is a `404` and nothing is deleted. Handoffs the session only *accepted* are kept: that text belongs to the session that wrote it. Logical delete by default; `--compact` additionally rebuilds the FTS indexes and `VACUUM`s (see below). Without `--confirm` it previews the same counts, including the cross-project ones, before refusing — see below. |-| `handoffs --expire-all --confirm` | ✅ yes | no (state change only) | no (but nothing is destroyed) | Marks every **open** handoff in the scope `expired` so it stops being offered to an agent. Rows, summaries and provenance are kept and stay visible in the audit log. Unlike the automatic sweep it does **not** spare manual handoffs or ones from another directory — those exemptions are exactly what a leftover backlog is made of, so honouring them would clear nothing. `--older-than-days N` keeps recent batons. Owner-scoped: never touches another user's baton. |+| `purge-project --confirm` | ✅ yes | the one project's data, **plus** any observation stamped into a different project by one of this project's sessions (cascades regardless of the observation's own `project_id`), and it nulls (does not delete) the session reference on any handoff in a different project that this project's sessions authored or accepted | no | Deletes the UUID-namespaced wiki root and raw workstream segments. Refuses with `409` while a managed workstream under the project holds a live run lease; `--force` overrides. Logical delete by default; `--compact` additionally rebuilds the FTS indexes and `VACUUM`s (see below). Without `--confirm` it previews the same counts, including the cross-project ones, before refusing (see below). |+| `purge-session --session-id --confirm` | ✅ yes | the one session's data, **plus** any observation stamped into a different project by this session (cascades regardless of the observation's own `project_id`), and it nulls (does not delete) the session reference on any handoff in a different project that this session authored or accepted | no | Deletes one session by UUID: its row, its observations, the handoffs it **authored**, its `sessions/<id>.md` page and every superseded version, their embeddings, and its auto-improve runs. Strictly scoped: a session that does not belong to the named workspace/project is a `404` and nothing is deleted. Handoffs the session only *accepted* are kept: that text belongs to the session that wrote it. Logical delete by default; `--compact` additionally rebuilds the FTS indexes and `VACUUM`s (see below). Without `--confirm` it previews the same counts, including the cross-project ones, before refusing (see below). |+| `handoffs --expire-all --confirm` | ✅ yes | no (state change only) | no (but nothing is destroyed) | Marks every **open** handoff in the scope `expired` so it stops being offered to an agent. Rows, summaries and provenance are kept and stay visible in the audit log. Unlike the automatic sweep it does **not** spare manual handoffs or ones from another directory. A leftover backlog is made of exactly those, so honouring the exemptions would clear nothing. `--older-than-days N` keeps recent batons. Owner-scoped: never touches another user's baton. || `rename-project --from --to` | ✅ yes | no | yes (rename back) | Column-only update on `projects.name`. The on-disk dir is keyed by `project_id` (UUID), so the rename never moves a file. || `/admin/rename-workspace` | ✅ yes | no | yes (rename back) | Column-only update on `workspaces.name`; refreshes `_meta.md` scope manifests and checkpoints the wiki tree. |-| `/admin/delete-workspace` | ✅ yes | the workspace and every child project, **plus** any observation stamped into a different workspace by one of this workspace's sessions (cascades regardless of the observation's own `workspace_id`), and it nulls (does not delete) the session reference on any handoff in a different workspace that this workspace's sessions authored or accepted | no | Runs `purge_workspace` admission first, deletes SQLite rows in one cascade, removes the UUID-keyed workspace directory and managed-workstream raw segments, reports filesystem partial failures, and dispatches mirror notification after durable work. Logical delete by default; `"compact": true` additionally rebuilds the FTS indexes and `VACUUM`s (see below). `"dry_run": true` previews the same counts, including the cross-workspace ones, without deleting anything — see below. |+| `/admin/delete-workspace` | ✅ yes | the workspace and every child project, **plus** any observation stamped into a different workspace by one of this workspace's sessions (cascades regardless of the observation's own `workspace_id`), and it nulls (does not delete) the session reference on any handoff in a different workspace that this workspace's sessions authored or accepted | no | Runs `purge_workspace` admission first, deletes SQLite rows in one cascade, removes the UUID-keyed workspace directory and managed-workstream raw segments, reports filesystem partial failures, and dispatches mirror notification after durable work. Logical delete by default; `"compact": true` additionally rebuilds the FTS indexes and `VACUUM`s (see below). `"dry_run": true` previews the same counts, including the cross-workspace ones, without deleting anything (see below). || `move-project --confirm` | ✅ yes | source only in the merge case (a `Reject`-policy `purge_project` webhook can still abort the source teardown leaving everything intact) | no | Fresh destination → lossless **true move** (re-stamp `workspace_id`, keep `project_id`, rename the dir): sessions/observations/handoffs + history all survive. Destination with a same-named project → **copy+purge merge**: only latest pages migrate. || `move-session <id> --to --confirm` | ✅ yes | no | yes (move it back) | Re-stamps one session (or every session touching `--from-project`) into another project: `sessions`, `observations`, its `handoffs`, consolidation jobs, auto-improve runs/claims and its `sessions/<id>.md` page, one transaction per session; the page file moves with it (`--pages move`, default) or is retired for regeneration. Without `--confirm` it is a real dry run (rolled back). Refuses with `409` an open session or a pending consolidation job unless `--force`. |-| `repair-backfill-timestamps --project --confirm` | ✅ yes | no | yes, if the operator kept the audit row or the CLI's before/after report (nothing else) | Corrects `sessions.started_at`/`ended_at` for sessions an older `backfill` imported before it carried the transcript's own event time. The CLI reads the operator's local transcripts read-only and posts candidate `(session_id, started_at, ended_at)` tuples to `POST /admin/repair-session-times`, which validates each one against `(workspace, project)` — a candidate outside that scope is `not_found` and untouched — only rewrites a row whose `started_at` postdates the candidate's own end (`not_flattened` otherwise, so a correctly hook-captured session or a re-run is a no-op), refuses negative/inverted/future-dated times, and never assigns an end time to a session still open. Without `--confirm` the server validates and reports inside a rolled-back transaction, so it is a real dry run; a confirmed run writes one `audit_log` row per request with the before/after times. Touches only the two timestamp columns of rows already in scope; `observations` and pages (including the session's own page frontmatter) are untouched. |+| `repair-backfill-timestamps --project --confirm` | ✅ yes | no | yes, if the operator kept the audit row or the CLI's before/after report (nothing else) | Corrects `sessions.started_at`/`ended_at` for sessions an older `backfill` imported before it carried the transcript's own event time. The CLI reads the operator's local transcripts read-only and posts candidate `(session_id, started_at, ended_at)` tuples to `POST /admin/repair-session-times`, which validates each one against `(workspace, project)` (a candidate outside that scope is `not_found` and untouched), only rewrites a row whose `started_at` postdates the candidate's own end (`not_flattened` otherwise, so a correctly hook-captured session or a re-run is a no-op), refuses negative/inverted/future-dated times, and never assigns an end time to a session still open. Without `--confirm` the server validates and reports inside a rolled-back transaction, so it is a real dry run; a confirmed run writes one `audit_log` row per request with the before/after times. Touches only the two timestamp columns of rows already in scope; `observations` and pages (including the session's own page frontmatter) are untouched. || `backup --to` | ✅ yes | no | n/a | Streams a gzipped tarball from the server's online `sqlite3 .backup` plus the wiki tree. Safe alongside the live writer. || `reclaim-ledger-versions` | ✅ yes | superseded pre-#660 ledger page *versions* only | no (the latest page version stays) | Dry-run by default; needs `--confirm` to delete. Online through the writer actor, safe alongside the live writer. Content-gated: only non-latest, non-decay `log.md`/`log-YYYY-MM.md` versions whose body opens with a ledger hook entry are removed; a real page that merely shares the name is untouched. `--compact` additionally rebuilds FTS and `VACUUM`s to reclaim the freed bytes. || `checkpoints` | ✅ yes | no | n/a | Lists recent wiki git checkpoints. Read-only. || `restore-page --path --from` | ✅ yes | overwrites one markdown page version | yes (restore another checkpoint) | Restores one page from wiki git history, reindexes it into SQLite, and writes a post-restore checkpoint. Does not restore DB-only state. |-| `backup-agents --to` / `restore-agents --from <tarball>` | ✅ yes (client-side; never touches the server or its data dir) | no | yes (`restore-agents --apply` keeps timestamped copies of overwritten files) | Agent-config assets, not wiki/db: MCP configs (redacted unless `--include-secrets`), hook configs, instructions, skills, plugins. `restore-agents` is a dry run by default; `--apply` writes to disk and `--force` overwrites existing or differing targets. Non-MCP assets are restored verbatim and may contain secrets — only `--apply` an archive whose source you trust. |+| `backup-agents --to` / `restore-agents --from <tarball>` | ✅ yes (client-side; never touches the server or its data dir) | no | yes (`restore-agents --apply` keeps timestamped copies of overwritten files) | Agent-config assets, not wiki/db: MCP configs (redacted unless `--include-secrets`), hook configs, instructions, skills, plugins. `restore-agents` is a dry run by default; `--apply` writes to disk and `--force` overwrites existing or differing targets. Non-MCP assets are restored verbatim and may contain secrets, so only `--apply` an archive whose source you trust. || `restore --from <tarball>` | ❌ **stop the server first** | overwrites the data dir | no (without prior backup) | Refuses if any sibling `ai-memory` process is alive (sysinfo guard). Stages and verifies the archive before swapping it in, so a failed restore leaves `wiki/` and `db/` as they were. || `reset --confirm` | ❌ **stop the server first** | yes, all data | no | Refuses if any sibling `ai-memory` process is alive (sysinfo guard). || `reindex` | ❌ **stop the server first** | no wiki wipe; requires a clean DB | only with prior DB backup | Rebuilds pages/links/FTS from `wiki/` using `_meta.md` manifests. Refuses if SQLite already has rows so stale DB-only state cannot survive silently. |@@ -60,10 +60,9 @@ regulatory erasure request rather than tidying up:| Present in backups taken before the purge | **yes** | **yes** || Cost | one transaction | rewrites the whole database |-`--compact` rebuilds the affected FTS5 indexes — an ordinary delete leaves the-tokens inside the index segments, which is why a rebuild rather than a-`VACUUM` alone is what clears them — and then `VACUUM`s to release the freed-pages. It needs free disk space of roughly the database's own size and takes+`--compact` rebuilds the affected FTS5 indexes and then `VACUUM`s to release the freed+pages. The rebuild is needed because an ordinary delete leaves the tokens inside+the index segments, and a `VACUUM` alone does not clear them. It needs free disk space of roughly the database's own size and takesminutes on a large store, which is why it is opt-in.**`--compact` is not forensic erasure.** The wiki git repository stores page@@ -76,20 +75,18 @@ guarantee that the content is unrecoverable, because it is not.Without `--confirm`, the CLI first asks the server for a preview(`"dry_run": true` in the request, exactly like `purge-project`'s own field).-`dry_run` always wins over `confirm` — `{"confirm": true, "dry_run": true}`-still only previews — so a preview request can never become destructive by+`dry_run` always wins over `confirm` (`{"confirm": true, "dry_run": true}`+still only previews), so a preview request can never become destructive byaccident.The preview runs the same lookups and counts a confirmed purge uses to decide-what to delete — same 404 for a session outside the named scope — including+what to delete, with the same 404 for a session outside the named scope, includingtwo cross-project counts for what purging this *session* collaterallydeletes or orphans in a *different* project through its own id-(`collateral_observations_deleted`, `collateral_handoffs_denulled` — the same-shape `purge-project`'s preview reports one level up, at project rather than+(`collateral_observations_deleted`, `collateral_handoffs_denulled`, the same shape `purge-project`'s preview reports one level up, at project rather thansession granularity), without ever issuing the `DELETE`. It never runs thedelete and rolls it back. Because nothing is deleted, `removed_paths` in the-reply names the wiki page paths a confirmed purge *would* remove — not paths-already gone — and `files_deleted`/`files_failed` are always empty, since no+reply names the wiki page paths a confirmed purge *would* remove (not paths already gone), and `files_deleted`/`files_failed` are always empty, since nofile is touched; neither the `purged_sessions` tombstone nor the `audit_log`row is written, and neither checkpoint is taken. The reply carries`"dry_run": true`. The CLI prints:@@ -100,16 +97,15 @@ Would purge session from default/my-app: 1063 observations, 0 handoffs, 1 pages,(with a trailing "Plus N observations in other projects via this session" /"Plus N handoffs ..." clause when either cross-project count is non-zero;-note the session id itself is never printed — the caller already has it, and+note the session id itself is never printed: the caller already has it, andthis command exists to make a session stop existing), then still refuses with-the existing "destructive and irreversible" message and a non-zero exit — the-preview is information layered on top of the refusal, never a substitute for-`--confirm`.+the existing "destructive and irreversible" message and a non-zero exit. The preview adds information to the refusal and never+substitutes for `--confirm`.A preview also skips the blocking admission call a confirmed purge makesbefore deleting anything (`admit_purge_session`): nothing was decided yet, sothere is nothing for a `Reject`-policy webhook to act on. This means a `200`-preview is not a guarantee — that same webhook only runs on the confirmed+preview is not a guarantee: that same webhook only runs on the confirmedpath and can still refuse the real purge afterward.If the server is unreachable, times out (a few seconds, auth-token refresh@@ -120,7 +116,7 @@ instead, since the operator asked what would happen and the server has areal answer.A handoff this session only *accepted* (did not author) keeps its row and-its text either way — confirmed or previewed — and loses only its+its text either way, confirmed or previewed, and loses only its`accepted_by_session` pointer (`ON DELETE SET NULL`) once the session row isactually gone; it is never counted in `handoffs_deleted`. Two more places apurged session's id is referenced are neither counted nor previewed today,@@ -128,7 +124,7 @@ as a known follow-up: `agent_messages.from_session_id` /`claimed_by_session` (the cross-project mailbox, V64) and another project's`auto_improve_runs.session_id`, both `ON DELETE SET NULL` and out of scopefor this preview's two `collateral_*` fields, which only cover observations-and handoffs — the same set `purge-project`'s own preview covers, one level+and handoffs: the same set `purge-project`'s own preview covers, one levelup.### The same is true of `purge-project` and `delete-workspace`@@ -138,8 +134,7 @@ Every row above applies unchanged to `ai-memory purge-project --compact` and toproperty of *any* SQLite delete, not of one command: rows go, bytes stay infree pages until the file is rewritten.-This is worth saying explicitly because the help text for those two commands-used to promise "ALL its data", which read as byte-level removal they never+The help text for those two commands used to promise "ALL its data", which read as byte-level removal they neverperformed (#540). Both now describe the same boundary and both accept the sameopt-in.@@ -148,8 +143,8 @@ workstream's `workstream_events` rows leave through the`projects → workstreams → workstream_events` cascade rather than through a`DELETE` against that table, and a cascade does not fire the `AFTER DELETE`trigger that would drop the row from `workstream_events_fts`. Compaction-therefore rebuilds **all three** FTS indexes — `pages_fts`,-`observations_fts` and `workstream_events_fts` — not just the two a session+therefore rebuilds all three FTS indexes (`pages_fts`,+`observations_fts` and `workstream_events_fts`), not just the two a sessionpurge needs. Rebuilding only the indexes a given caller "should" have touchedis what leaves a managed agent's transcript text in the file after an operatorasked for it to be reclaimed.@@ -162,8 +157,8 @@ File cleanup failures still leave the database purge committed and are reportedin `files_failed`; this coordination does not provide crash-atomic rollback.The guard is taken before the purge is submitted to the writer actor, so it also-covers the wait for whatever that single queue is already draining, and — with-`compact: true` — the `VACUUM` that runs after the delete commits. A purge on a+covers the wait for whatever that single queue is already draining, and, with+`compact: true`, the `VACUUM` that runs after the delete commits. A purge on abusy server therefore holds up wiki mutations for longer than the delete itself.The git checkpoints taken before and after the purge sit outside the guard: theybracket it, they do not snapshot it.@@ -173,8 +168,7 @@ bracket it, they do not snapshot it.The session id is never authority on its own. Every statement is filtered on`workspace_id` and `project_id` as well as `session_id`, the session mustbelong to the named scope or the call is a `404` with nothing deleted, and the-derived pages are deleted by **id** rather than by path — two projects can-hold the same `sessions/<uuid>.md`, and deleting by path would take the other+derived pages are deleted by **id** rather than by path, because two projects can hold the same `sessions/<uuid>.md`, and deleting by path would take the otherone with it. `/admin/purge-session` runs the admission chain before any row istouched, so a `failure_policy = reject` webhook can still abort the wholeoperation while the data is intact. After the SQL transaction commits, the@@ -212,7 +206,7 @@ The mutable **project name** (the human-readable `distrobox-gaming`or `.config` you see in `/web/`) never appears in any disk path; thestable **project_id UUID** does. SQLite's `projects.name` column mapsname → id. Two projects can have the exact same `pages.path` (e.g.-both have `decisions/0001.md`) without colliding on disk - the+both have `decisions/0001.md`) without colliding on disk; thenamespaced layout guarantees structural isolation.The git history is rooted at `<wiki_root>` (one repo, all projects@@ -236,7 +230,7 @@ ai-memory purge-project --workspace default --project my-project --confirmai-memory purge-project --workspace default --project my-project --confirm --compact```-Like `purge-session`, this is a logical delete unless `--compact` is given —+Like `purge-session`, this is a logical delete unless `--compact` is given;see [What "deleted" means](#what-deleted-means-purge-session-purge-project-delete-workspace).What happens, in order:@@ -255,7 +249,7 @@ What happens, in order:3. Counts rows that will cascade (`pages`, `sessions`,`observations`, `handoffs`, `page_embeddings`, plus `workstreams`and `managed_runs`).-4. Single `DELETE FROM projects WHERE id = ?` - the V01 + V05+4. Single `DELETE FROM projects WHERE id = ?`: the V01 + V05`ON DELETE CASCADE` foreign keys propagate to every dependenttable in one transaction.5. Best-effort filesystem cleanup removes both the UUID-namespaced wiki root@@ -273,14 +267,14 @@ cleanup failures.#### Preview without `--confirm`Without `--confirm`, the CLI first asks the server for a preview-(`"dry_run": true` in the request). `dry_run` always wins over `confirm` —+(`"dry_run": true` in the request). `dry_run` always wins over `confirm`:`{"confirm": true, "dry_run": true}` still only previews, the same way-`reclaim-ledger-versions` treats its own `dry_run` field — so a preview+`reclaim-ledger-versions` treats its own `dry_run` field, so a previewrequest can never become destructive by accident.The preview runs the same lookups and counts steps 1-3 above use to decide-what a confirmed purge would delete — same 404 on an unknown scope, same-`409` on a live managed-run lease without `--force` — and returns those+what a confirmed purge would delete (same 404 on an unknown scope, same+`409` on a live managed-run lease without `--force`) and returns thosecounts, including the two cross-project ones (an observation deleted, or ahandoff's session reference nulled, in a project other than the one named;see the matrix row above), without ever issuing the `DELETE` in step 4. It@@ -299,19 +293,19 @@ Would purge default/my-project: 3 pages, 1 sessions, 1063 observations, 0 handof(with a trailing "Plus N observations in other projects via their sessions"/ "Plus N handoffs ..." clause when either cross-project count is non-zero),then still refuses with the existing "destructive and irreversible" message-and a non-zero exit — the preview is information layered on top of the-refusal, never a substitute for `--confirm`.+and a non-zero exit. The preview adds information to the refusal and never+substitutes for `--confirm`.A preview also skips the blocking admission call a confirmed purge makesbefore deleting anything (`admit_purge_project`): nothing was decided yet,so there is nothing for a `Reject`-policy or scope-guard webhook to act on.-This means a `200` preview is not a guarantee — that same webhook only runs+This means a `200` preview is not a guarantee: that same webhook only runson the confirmed path and can still refuse the real purge afterward.If the server is unreachable, times out (a few seconds, auth-token refreshincluded), or predates this field (a plain `400`), the CLI falls backsilently to the plain refusal with no preview line, so no existing script's-exit code or error shape changes — only a confirmed purge is ever+exit code or error shape changes; only a confirmed purge is everdestructive. A `404`/`409`/`403` (or any other unexpected status) prints theserver's own error before the refusal instead, since the operator asked whatwould happen and the server has a real answer.@@ -334,7 +328,7 @@ Why this is safe with the server running:it against any other writes.- The on-disk delete touches only the project's UUID-keyed subdir,which no other project shares files with. No race with the- watcher even mid-write - at worst the watcher emits delete+ watcher even mid-write: at worst the watcher emits deleteevents for files we just removed, which it ignores (no DB rowto reindex).@@ -410,7 +404,7 @@ Deletes a workspace row and all child projects/pages/sessions/managedworkstreams through the `workspace_id` cascade. The route is guarded by`force: true` for non-empty workspaces and follows the destructive-operationordering used by project purges. It accepts the same opt-in reclaim as the-other two destructive commands — `{"compact": true}` — and is otherwise a+other two destructive commands (`{"compact": true}`) and is otherwise alogical delete; see[What "deleted" means](#what-deleted-means-purge-session-purge-project-delete-workspace).@@ -422,8 +416,7 @@ logical delete; see`projects_deleted`, `pages_deleted`, `sessions_deleted`,`observations_deleted`, `handoffs_deleted`, `embeddings_deleted`,`workstreams_deleted`, `managed_runs_deleted`, plus the two cross-workspace- counts (`collateral_observations_deleted`, `collateral_handoffs_denulled`- — the same shape `purge-project`'s preview reports one level down, at+ counts (`collateral_observations_deleted`, `collateral_handoffs_denulled`, the same shape `purge-project`'s preview reports one level down, atproject rather than workspace granularity) before issuing the `DELETE`.5. Remove `<wiki_root>/<workspace_id>` and every affected`<data_dir>/raw/workstreams/<workstream_id>` directory from disk. The@@ -445,8 +438,8 @@ Failure modes:#### Preview with `"dry_run": true`-`"dry_run": true` in the request body always wins — `{"force": true,-"dry_run": true}` still only previews — so a preview request can never+`"dry_run": true` in the request body always wins (`{"force": true,+"dry_run": true}` still only previews), so a preview request can neverbecome destructive by accident, the same pattern `purge-project` uses forits own `dry_run` field. The preview runs step 4'scounts (including the two cross-workspace ones) against the same rows a@@ -454,7 +447,7 @@ confirmed delete would remove, using the same `409` for a non-emptyworkspace without `force` and the same `404` for an unknown workspace, andreturns before ever issuing the `DELETE`. Steps 2, 3, 5, 6, and 7 never rununder `dry_run`: no admission call, no wiki directory removal, no mirror-dispatch, no checkpoint — `files_deleted`/`files_failed` are always empty and+dispatch, no checkpoint; `files_deleted`/`files_failed` are always empty and`pre_checkpoint`/`checkpoint` are always absent. The reply carries`"dry_run": true`. There is no CLI subcommand for `delete-workspace` today,so this preview is HTTP-only.@@ -479,7 +472,7 @@ ai-memory move-project --from-workspace default --project my-project \Moves a project into a **different** workspace. Unlike `rename-project`(a same-workspace column update), this crosses the workspace boundary.-The destination decides which of two strategies runs — reported as+The destination decides which of two strategies runs, reported as`moved_via` in the response:**1. Fresh destination → `"true-move"` (lossless, the common case).**@@ -523,14 +516,13 @@ writes/reindexes take the shared side of the same mutation gate and validate the`(workspace_id, project_id)` pair before touching disk, so stale source writesfail without creating orphan files after the move.-This is O(1) (one transaction + one rename), re-embeds nothing, and-**preserves everything** — sessions, observations, handoffs and the full+This is O(1) (one transaction + one rename), re-embeds nothing, and preserves everything: sessions, observations, handoffs and the fullsupersession history all travel with the project.**Live-session guard.** The server refuses (409) to move the project thehook router has published as the *active* project (a live session's nextobservation would carry a now-stale `workspace_id`). Pass `--force` /-`force: true` to override — still safe: the move republishes the active+`force: true` to override. That is still safe: the move republishes the activepointer, and the wiki pair validator plus `(workspace_id, project_id)` inserttrigger (V18) reject stale writes cleanly, so the router re-resolves instead ofcorrupting or creating old-workspace files.@@ -539,8 +531,8 @@ corrupting or creating old-workspace files.(merge).** Two distinct `project_id`s can't be re-stamped into one (itwould collide on `UNIQUE (workspace_id, name)`), so the source's latestpages are copied into the existing destination project via-`Wiki::write_page` (sanitization, link re-resolution, FTS, and — on-deploy — the admission/git-mirror webhooks all fire), source embeddings+`Wiki::write_page` (sanitization, link re-resolution, FTS, and, on+deploy, the admission/git-mirror webhooks all fire), source embeddingsare carried over verbatim, and only then is the source purged(`merged_into_existing: true`, `source_purged: true`).@@ -552,7 +544,7 @@ lease ids, so it does not need this additional guard.Copy-before-purge means any copy failure aborts **before** the purge,leaving the source intact. An unreadable source file is skipped and alsoblocks the purge (`source_purged: false`) so a fixed re-run is safe-(re-running is idempotent — copied pages just supersede). A **live managed+(re-running is idempotent; copied pages just supersede). A **live managedrun** under the source blocks the purge leg the same way: the move returns409 saying how many pages were already copied, and the source stays intactuntil the session ends and the move is re-run.@@ -562,13 +554,13 @@ exists in the destination with a different body, frontmatter, title, tier, orpinned bit, the policy decides (identical pages are always a no-op supersessionat the same path):-- **`block`** (default) — abort the whole move with 409, listing the+- **`block`** (default): abort the whole move with 409, listing theconflicting paths; the source is left intact. The safe default for adestructive op: nothing is overwritten or split silently. The operatorresolves the conflicts or re-runs with an explicit policy.-- **`overwrite`** — the source page supersedes the destination page at the+- **`overwrite`**: the source page supersedes the destination page at thesame path (the destination's prior version becomes history).-- **`duplicate`** — keep both: the source page lands at+- **`duplicate`**: keep both. The source page lands at`<stem>-from-<src_workspace_slug>.md`, then `-2`, `-3`, … onfurther collisions. The `-from-` literal is the `DEDUP_FROM_TOKEN`constant in `crates/ai-memory-mcp/src/admin.rs`; if you ever@@ -590,7 +582,7 @@ capture log) are dropped by the purge, and the moved pages start a freshsupersession chain (the real page history lives in the wiki's gitmirror). The `true-move` path has no such loss.-> **Operational caveat — moving the project the current session writes+> **Operational caveat: moving the project the current session writes> to.** Lifecycle hooks stamp a bounded observation on every supported tool-lifecycle event into the> session's project. If you move that very project mid-session, the next> hook re-creates the source (`scratch`-style) under the old workspace.@@ -604,8 +596,7 @@ Failure modes:- **`from_workspace == to_workspace`** → 422 (use `rename-project`).- **Source project not found** → 404.- **Destination workspace directory already exists** (true-move only)- → 409 with `WikiError::DestinationExists` body — the destination- has on-disk content for the same `(workspace, project)` UUID pair+ → 409 with `WikiError::DestinationExists` body: the destination has on-disk content for the same `(workspace, project)` UUID pairwithout a corresponding DB row; refuse and let the operatorreconcile manually.- **Block-policy same-path conflict** (copy-purge merge only) → 409@@ -754,7 +745,7 @@ Failure modes:**It drains every scope, not just the one you named.** Dependent rows arematched by session id alone, so a session whose observations were scatteredacross projects (pre-`sticky` mid-session routing, for instance) is gathered-whole. That is the point of the command — but it means a move can empty a+whole. That is the point of the command, but it means a move can empty aproject you did not mention, and it is **not cleanly reversible**: moving thesession back later returns every row to a single project, and the originalper-row split is gone.@@ -787,8 +778,7 @@ Before #660 the wiki indexer stored every rewrite of an OKF event ledgersuperseded versions dominate the database (one report: ~95 % of a 45 GB store).This online command deletes exactly that residue: a page version is removed onlywhen it is **not** the latest, is not a retention-decay version, its path matches-the ledger shape, **and** its own body opens with a `## [timestamp]` ledger hook-entry — so a genuine page that merely happens to be named `log-2026-09.md` is+the ledger shape, **and** its own body opens with a `## [timestamp]` ledger hook entry, so a genuine page that merely happens to be named `log-2026-09.md` isnever touched, and no live/latest page is affected. Deletion runs through thesingle writer actor in one transaction; derived rows (embeddings, links,feedback) cascade, and the kept latest version's supersession back-pointer is@@ -837,8 +827,7 @@ unboundedly; over the cap is a 400 before any scope lookup.it (never the caller's belief about it):**- **Scope containment**, exactly like `purge-session`: a `session_id` that- does not belong to `(workspace, project)` — wrong scope or nonexistent — is- reported `skipped: {reason: "not_found"}` and left untouched. The two cases+ does not belong to `(workspace, project)` (wrong scope or nonexistent) is reported `skipped: {reason: "not_found"}` and left untouched. The two casesare never distinguished, so an id existing in a different project is notleaked to the caller.- **A no-op candidate is `"unchanged"`, not counted as repaired.** Checked@@ -846,7 +835,7 @@ it (never the caller's belief about it):**always a no-op regardless of whether the row happens to look flattened.- **The bug's own signature is the gate, not the caller's say-so.** A row isonly rewritten when its current `started_at` sits AFTER the candidate's own- end (or start, when the candidate carries no end) — the actual shape of+ end (or start, when the candidate carries no end), which is the actual shape of"backfill dated this at import time". A row that already sits at or beforethat point is `"not_flattened"` and left untouched: this endpoint repairsthe specific backfill bug, it is not a generic "set session times"@@ -856,35 +845,34 @@ it (never the caller's belief about it):**- **Sane times**: `started_at_us` and `ended_at_us` (when given) must bepositive, and `started_at_us` must not be later than the end the row willactually have once the candidate lands (its own new end, or, when that- stays unwritten, whatever end the row already had) — otherwise+ stays unwritten, whatever end the row already had); otherwise`"invalid_time"` or `"inverted_times"`.- **Never into the future**: either time more than five minutes past "now" is`"future_time"`. Clock-skew margin, not a real correction target.- **Never closes an open session**: when the session's current `ended_at` is- `NULL`, the candidate's `ended_at_us` is silently withheld — `started_at` is- still applied, and the report marks that session `end_kept_open: true`+ `NULL`, the candidate's `ended_at_us` is silently withheld; `started_at` is still applied, and the report marks that session `end_kept_open: true`rather than skipping it outright.**Dry run by default.** Without `confirm: true` the server validates andcomputes the exact would-be write inside a transaction it then rolls back, sothe report (`repaired`, `skipped`, before/after times) is the literal outcome,-not an estimate — same pattern as `move-session`. `--confirm` applies through+not an estimate (same pattern as `move-session`). `--confirm` applies throughthe single `WriterHandle`, one transaction per request (chunk).**What it touches.** Only `sessions.started_at`/`ended_at` of rows already in-the requested scope — never `observations`, pages, or any other table, and+the requested scope, never `observations`, pages, or any other table, andnever a row outside `(workspace, project)`. Session identity (`sessions.id`and its 3-tuple scope) is never written; this is a correction of twotimestamp columns on rows that already exist, not a move or a delete.`observations.created_at` and the `sessions/<id>.md` page's own frontmatter-timestamps still carry the old import-day times after a repair — only the+timestamps still carry the old import-day times after a repair. Only the`sessions` row's two columns are corrected; regenerating the session page(e.g. via a fresh consolidation) is what would bring its frontmatter in line.**Reversibility.** A confirmed batch writes one `audit_log` row (`op ="repair_session_times"`) per request with every repaired session's before/after times in `detail`, and the CLI's human report prints the same old →-new values per session — an operator who kept either can restore the prior+new values per session. An operator who kept either can restore the priorvalues by hand; there is no automatic undo.### `checkpoints`@@ -952,15 +940,15 @@ ai-memory backup --to /tmp/ai-memory-backup.tar.gzWhat happens on the server:-1. SQLite online-backup API copies the live WAL DB to a temp file -- guaranteed consistent snapshot without stopping the writer.+1. SQLite online-backup API copies the live WAL DB to a temp file,+ a guaranteed consistent snapshot without stopping the writer.2. Server tar-gzips the snapshot + the wiki tree + `config.toml`.3. Response body IS the gzipped tarball(`Content-Type: application/gzip`).CLI writes the response body to `--to`. For a homelab userthis is the standard "snapshot before doing something dangerous"-move - `ai-memory backup` first, then proceed.+move: `ai-memory backup` first, then proceed.Restoring a backup follows the inverse:@@ -992,7 +980,7 @@ Order of operations:2. Extract the tarball into a staging directory beside the live data(`<data_dir>/.restore-staging-<stamp>/`), validating every entry.3. Open the staged store so pending migrations run and the SQLite- snapshot is verified — still without touching the live data.+ snapshot is verified, still without touching the live data.4. Swap: rename the live `wiki/` and `db/` (and `config.toml`, when thearchive carries one) aside, rename the staged copies into place, thendelete the previous data. Each move is a same-filesystem rename; if@@ -1007,7 +995,7 @@ copy exists.Failure modes:- **Server still running** → exits with "another ai-memory process is- alive (pid X); stop it before restoring" - same wording as `reset`.+ alive (pid X); stop it before restoring" (same wording as `reset`).- **Data dir not empty + no `--force`** → exits with "data dir notempty; pass `--force` to overwrite".- **Truncated or corrupt tarball, an entry outside the allowed layout, or@@ -1030,13 +1018,13 @@ alive. Removes the contents of `wiki/`, `db/`, and `raw/` under theconfigured data dir. `config.toml` is preserved.Identical sysinfo guard to `restore`. The use case is "wipe and start-over" - typically when changing major version with a breaking+over", typically when changing major version with a breakingmigration, or when bootstrapping a new install on top of an olddata dir.For a docker deploy where the data lives in a host-path bind mount,you can also just `rm -rf <host-path>/*` after stopping the-container - but `ai-memory reset` is the cross-platform path that+container, but `ai-memory reset` is the cross-platform path thatworks whether the data dir is local, bind-mounted, or in a namedvolume.@@ -1083,7 +1071,7 @@ optional typed `identity`, `identity_source`, `canonical_name`, and`legacy_name` fields. Older manifests without thosefields remain valid and rebuild identity-less projects. The manifest is writtenwith the scope's first page, so a project that first appears while the server is-running is rebuildable from that moment on — no restart required. The startup+running is rebuildable from that moment on, with no restart required. The startupbackfill still runs on every boot and repairs a tree written by an older release,or one whose manifests were removed by hand. If `reindex` reports a missing manifest,start the server once against that data directory and let the backfill write@@ -1161,9 +1149,8 @@ click returned 404 because the on-disk file was gone.The shipped band-aid was a `path_still_referenced` check before eachdelete. The proper fix landed in `e7b9a17`: per-project disk roots-make path-collision structurally impossible. Both the band-aid and-the underlying class of bug are gone. Lifecycle ops are now safe-by construction.+make path-collision structurally impossible, so both the band-aid and the+underlying class of bug are gone and lifecycle ops are safe by construction.This is also why `rename-project` is free: the disk path is keyedby surrogate `project_id`, not the mutable name. Rename touches onediff --git a/docs/llm-provider-comparison.md b/docs/llm-provider-comparison.mdindex 43b0f494..6f722524 100644--- a/docs/llm-provider-comparison.md+++ b/docs/llm-provider-comparison.md@@ -12,7 +12,7 @@> | Haiku 4.5 (OpenRouter) | 5/5 | 7.3 s | high | ~$5 | most disciplined hosted on restraint |> | DeepSeek V4 Flash (OpenRouter) | 5/5 | 21.7 s | high | ~$0.40 | slower than GPT-mini, comparable price |> | Sonnet 4.5 (OpenRouter) | 5/5 | 10.8 s | high (after prompt fix) | ~$15 | displaced by Haiku for this task |-> | Kimi-K2.6 (OpenRouter) | hangs | n/a | n/a | n/a | reasoning model — ineligible |+> | Kimi-K2.6 (OpenRouter) | hangs | n/a | n/a | n/a | reasoning model, ineligible |>> † order-of-magnitude pricing per million output tokens. Actual> per-consolidation cost depends on input + output token count.@@ -28,7 +28,7 @@> Haiku, ~2× faster, mild over-classification on trivial> sessions). **Free alternative if you have a local LLM> server** (Ollama / vLLM / llama-swap with a 30B-class-> model): qwen3:32b on Ollama — $0 per consolidation,+> model): qwen3:32b on Ollama, at $0 per consolidation, with> background latency invisible to users. See> [Installation cookbook - LLM provider tiers](install.md#llm-provider-tiers)> for setup. Reproduce the comparison in [`evals/`](../evals/).@@ -37,8 +37,8 @@When the homelab deploy switched ai-memory off the billedOpenAI / OpenRouter providers and onto the locally-hosted Ollama-server, we needed empirical evidence - not a vibes-based claim --that *consolidation quality didn't degrade*. ai-memory's+server, we needed empirical evidence that *consolidation quality+didn't degrade*. ai-memory'sconsolidator turns a session's raw observations into 1–5 wikipages classified as `concept`, `decision`, `gotcha`, or `rule`;small drops in quality compound fast across hundreds of sessions.@@ -77,11 +77,11 @@ exactly as the production hook ingress emits them.### The exact requestPer fixture, the runner calls-[`ai_memory_consolidate::build_batch_request(session_id, &observations)`](../crates/ai-memory-consolidate/src/consolidator.rs)-- the **same** function the live consolidator uses on every+[`ai_memory_consolidate::build_batch_request(session_id, &observations)`](../crates/ai-memory-consolidate/src/consolidator.rs),+the **same** function the live consolidator uses on every`memory_consolidate` invocation. That request is then sentthrough [`ai_memory_llm::complete_structured`](../crates/ai-memory-llm/src/lib.rs)-(also the live path). Apples-to-apples by construction.+(also the live path), so every provider gets an identical request.### The six providers@@ -98,7 +98,7 @@ The home server (`192.168.0.90`) is a Ryzen AI MAX+ 395(Strix Halo / gfx1151), 96 GB unified memory, ROCm-backedOllama with `OLLAMA_KEEP_ALIVE=20m` + `OLLAMA_FLASH_ATTENTION=1`+ `OLLAMA_KV_CACHE_TYPE=q8_0`. Once a model is loaded into-unified memory it stays warm for 20 min - so the first+unified memory it stays warm for 20 min, so the firstrequest pays a 30–60 s cold-load tax and subsequent ones aresub-3 s.@@ -114,15 +114,15 @@ Every provider failed schema validation on every fixture:| 04-low-signal-session | ❌ *response is not valid JSON* | ❌ *integer 1, expected string* || 05-multi-topic-session | ❌ *response is not valid JSON* | ❌ *integer 2, expected string* |-But the *raw responses* told a very different story: both-models did **excellent** consolidation work content-wise. They+The *raw responses*, however, showed that both models did+**excellent** consolidation work content-wise. Theycorrectly identified multiple distinct pages per fixture,extracted faithful summaries, and respected the pathconventions. The failures were **format only**:-- **Kimi** was emitting beautifully formatted markdown- (`### Update 1` / `**path:**` / `**body:**`) - completely- ignoring the request for JSON.+- **Kimi** was emitting well-formatted markdown+ (`### Update 1` / `**path:**` / `**body:**`) and ignoring+ the request for JSON entirely.- **qwen3** was emitting clean JSON in code fences, but with`tier: 1` / `tier: 2` / `tier: 3` (integers) instead of thedocumented string values, and occasionally with invented@@ -149,7 +149,7 @@ pub struct ConsolidatedPageUpdate {`schemars` couldn't produce an enum constraint for `tier`because `Tier` (the actual enum in `ai-memory-core`) didn'thave the `JsonSchema` derive. The generated schema field was-just `{ "type": "string" }` - no `enum` constraint - so models+just `{ "type": "string" }` with no `enum` constraint, so modelswere free to guess. Both Kimi and qwen3 guessed numeric indices.### Bug B - prompt described values, didn't enforce them@@ -158,9 +158,9 @@ The system prompt in[`build_batch_request`](../crates/ai-memory-consolidate/src/consolidator.rs)listed the valid `tier` and `kind` values in prose but neversaid "use these EXACT string values, never an integer, never a-synonym, never code fences". Local instruction-tuned models -+synonym, never code fences". Local instruction-tuned models,especially when there's no `response_format: json_schema`-support to enforce - will drift to whatever feels natural.+support to enforce the schema, drift to whatever feels natural.Compounding this at the time of the run: openai-compat providers(Ollama, OpenRouter passthrough) were using ai-memory's tolerant@@ -209,7 +209,7 @@ Three small changes landed together:pub enum Tier { Working, Episodic, Semantic, Procedural }```-Adds `schemars` as a dep on `ai-memory-core` (acceptable -+Adds `schemars` as a dep on `ai-memory-core` (acceptable, sinceschemars is already a workspace dep used by every type thatcrosses the LLM boundary).@@ -252,8 +252,8 @@ very last `}`. Strings must be JSON strings (with double quotes), not numbersand not bare identifiers.```-Belt-and-suspenders: the schema now *rejects* the bad values,-and the prompt makes it actively hard for the model to produce+The two fixes overlap on purpose: the schema now *rejects* the+bad values, and the prompt makes the model less likely to producethem in the first place.## Run 2 - schema + first prompt fix@@ -273,12 +273,12 @@ fixtures produced:| **Aggregate** | **5/5** | **avg 26 s** | - | **4/5** | **avg 103 s** | - |*qwen3's only failure: invented `kind: "concept"` (not in the-`PageKind` enum - valid values are `decision`/`gotcha`/`rule`/+`PageKind` enum; valid values are `decision`/`gotcha`/`rule`/`fact`). Despite the prompt mentioning the valid set, themodel drifted. **This gets fixed in Run 3 below.**Both models **correctly restrained themselves** on fixture-04 (low-signal-session) and produced a single update - a+04 (low-signal-session) and produced a single update, anon-trivial test the original schema-broken Run 1 couldn'teven reach.@@ -298,7 +298,7 @@ Same prompt, both Anthropic models side-by-side:**Haiku is ~2× faster than Sonnet on every fixture**, hits thesame 5/5 parse rate, and on the gotcha-with-rule fixturecorrectly classified the `audit-ignore-with-revisit-date`-convention as `kind: rule` - which **Sonnet missed**, calling+convention as `kind: rule`, which **Sonnet missed**, callingit a generic `gotcha`. The auto-routing to `_rules/<slug>.md`that the consolidator depends on therefore *only fires underHaiku* for that fixture, not Sonnet.@@ -309,14 +309,14 @@ faithfulness than Sonnet even with the loose prompt:- **Sonnet** invented `Date: 2025-01-23` twice in fixture 5(no date in the source observations); fabricated an entire`## Alternatives considered` section listing Alpine/Scratch/- Debian-slim - none mentioned in the session; added "Better+ Debian-slim, none of them mentioned in the session; added "Betterlong-term solutions" / "When NOT to ignore" filler.- **Haiku** had a couple of invented "Options considered"entries (Alpine, aggressive optimization flags) butotherwise stayed close to the observations.For consolidation, the headroom Sonnet has over Haiku-expressed itself as *more hallucination*, not better+showed up as *more hallucination* rather than betterfidelity.### Kimi-K2.6 (OpenRouter) - INELIGIBLE for this task@@ -350,7 +350,7 @@ instructions before *either* emitting JSON or running out ofbudget with no content. The eval observed 16 minutes of noprogress on fixture 1 before being killed.-This is **not a fixable prompt or schema issue** - it's a+This is **not a fixable prompt or schema issue**. It is aproperty of the model's response style. Run 1 only "worked"on Kimi (in the sense of producing *something*) because theloose prompt let Kimi emit prose markdown, which used `content`@@ -360,7 +360,7 @@ reasoning mode and starves the visible response.**Kimi-K2.6 is not a suitable provider for ai-memory'sconsolidation workload.** It would work for the broader"summarise this for me" use case where formatted prose is-fine - just not for our JSON-schema-validated path.+fine, but not for our JSON-schema-validated path.Other reasoning-mode models (Claude with extended thinking,GPT-o3, Gemini "thinking" variants) would need the same@@ -371,9 +371,9 @@ reasoning consumption in mind.The Run 2 evidence above showed that Sonnet was hallucinatingdates, fabricating "Alternatives considered" tables, and-inventing tutorial sections - content that wasn't in the-observations. Even Haiku slipped occasionally. The fix wasn't-a model swap; it was tightening the **system prompt** to+inventing tutorial sections that weren't in the+observations. Even Haiku slipped occasionally. Instead of+swapping models, the fix tightened the **system prompt** todemand faithfulness explicitly:```text@@ -439,14 +439,14 @@ under `pub const BATCH_SYSTEM_PROMPT`.| 05 multi-topic-session | ✓ | 9,681 | 3 | ✓ | 122,220 | 5 || **Aggregate** | **5/5** | **avg 8 s** | - | **5/5** | **avg 92 s** | - |-**qwen3 went from 4/5 → 5/5** with the tightened prompt - the+**qwen3 went from 4/5 → 5/5** with the tightened prompt: theexplicit field-by-field enumeration of legal `kind` valueseliminated the "concept" drift that broke Run 2.-The tightened-prompt change is the highest-use diff in-the whole investigation. Same models, no infra changes, ~60%-latency reduction, complete elimination of date hallucination-on Sonnet, parse rate parity restored for qwen3.+The tightened prompt had the largest effect of any change in+the investigation. With the same models and no infra changes,+it cut latency ~60%, eliminated date hallucination on Sonnet,+and restored parse rate parity for qwen3.## Run 4 - budget-tier hosted comparison@@ -490,13 +490,13 @@ invented dates, no fabricated tutorial sections.| 05 multi-topic-session | ✓ | 15,543 | 5 | ✓ | 7,616 | 3 || **Aggregate** | **5/5** | **avg 21.7 s** | - | **5/5** | **avg 7.4 s** | - |-DeepSeek V4 Flash passes every reliability bar - 5/5 parse,+DeepSeek V4 Flash passes every reliability bar: 5/5 parse,correct restraint on low-signal, no hallucinated dates (the"2026-08" that appeared in its output was *legitimately in thesource observations*), correct `kind: rule` classification.Notable: fixture 3 took 54 s, suggesting variance under loador extended reasoning. On multi-topic it produced 5 updates-vs the 3 the other models settled on - slightly more+vs the 3 the other models settled on, slightly moreexuberant than Haiku.## Comprehensive ranking - all six providers@@ -521,7 +521,7 @@ amortised cost-per-task; ~$5 (Haiku) = 3; ~$15 (Sonnet) = 1.‡ Sonnet's faithfulness was 2/5 with the loose prompt (inventeddates, fabricated alternatives sections). It recovers to 4-after the tightened prompt - but Haiku achieved that same level+after the tightened prompt, but Haiku achieved that same levelwithout needing the prompt change as much, suggesting Haiku hasbetter defaults for this task.@@ -537,7 +537,7 @@ better defaults for this task.Inexpensive options change the cost from monthly-recurringto negligible.- **Faithfulness**: does the model only write what's in the- observations? Critical for a *memory* wiki - fabrication+ observations? Critical for a *memory* wiki, where fabricationcorrupts the long-term record.- **Restraint**: does the model resist manufacturing pageswhen the session is low-signal? Lack of restraint pollutes@@ -555,43 +555,43 @@ better defaults for this task.For ai-memory's consolidation task specifically:-1. **Haiku 4.5** - **recommended default for most users.**+1. **Haiku 4.5**: **recommended default for most users.**Hosted (always available), 7 s avg latency, restraint +classification top of the field, ~$0.02/run is negligiblefor personal use. The benchmark every other option ismeasured against.-2. **GPT-5.4-mini** - **cheaper hosted alternative.** ~5×+2. **GPT-5.4-mini**: **cheaper hosted alternative.** ~5×cheaper than Haiku, 2× faster (4 s avg). Only weakness ismild over-classification on trivial sessions(manufactures one extra "decisions/" page on a typo-fixsession). If budget matters more than restraint, pickthis.-3. **qwen3:32b on Ollama** - **free alternative for those+3. **qwen3:32b on Ollama**: **free alternative for thosewith a local server.** $0 per consolidation. ~92 slatency is invisible because consolidation is a backgroundjob. Restraint + faithfulness match the top hosted models.Requires Ollama (or compatible OpenAI-compat server) with`qwen3:32b` pulled and enough RAM/VRAM (~20 GB) to keepit warm.-4. **DeepSeek V4 Flash** - **solid but no clear edge.** All+4. **DeepSeek V4 Flash**: **solid but no clear edge.** Allreliability bars met, faithful, restrained, correctly- classifies rules. But GPT-mini matches it on quality and+ classifies rules. GPT-mini matches it on quality andbeats it on speed; Haiku matches it on quality and beatsit on classification consistency. Pick only if yourworkflow is already DeepSeek-leaning.-5. **Sonnet 4.5** - **strictly dominated by Haiku** for+5. **Sonnet 4.5**: **strictly dominated by Haiku** forplain consolidation. 3× the cost for the same parse rateand only marginally different latency. Reserve for tasksthat *specifically* need extended reasoning (cross-pagelint sweeps that compare contradictory claims across manypages, or for sparse-observation sessions where you wantthe model to infer more aggressively).-6. **Kimi-K2.6** - **ineligible.** Reasoning model burns+6. **Kimi-K2.6**: **ineligible.** Reasoning model burns`max_tokens` budget on internal thinking before emittingvisible content. Hangs indefinitely on strict-JSONprompts. Same caveat applies to any other reasoning-modemodel (Claude with extended thinking, GPT-o3, Gemini- "thinking" variants) - turn reasoning off or budget+ "thinking" variants): turn reasoning off or budgettokens with consumption in mind before using them here.## Qualitative read (Run 2)@@ -603,9 +603,9 @@ don't capture:- **Sonnet writes long, comprehensive entries.** A conceptpage on Docker multi-stage builds will get 3 KB of well-organised prose including "When to use" / "When NOT to use"- / "Gotchas" sections - content that *wasn't in the+ / "Gotchas" sections, none of which *was in theobservations*. The model is generating useful tutorial-style- content, not strictly consolidating what happened.+ content instead of strictly consolidating what happened.Sonnet's fixture 05 page invented a `Date: 2025-01-23`field that has no source in the observations.@@ -619,14 +619,13 @@ don't capture:For **wiki consolidation** (faithful long-term memory of*this project*, not a knowledge graph of general bestpractices), **qwen3's restraint is arguably preferable** to-Sonnet's exuberance. The point of the wiki is to record what-happened in the project, not to host re-generated tutorial-content the model already knows.+Sonnet's exuberance. The wiki exists to record what happened+in the project; re-generated tutorial content the model already+knows does not belong there.-That said, when the project memory is genuinely sparse and-the model is asked to surface durable knowledge, Sonnet's-"fill in the obvious" tendency could pay off. Different-tasks → different preferences.+When the project memory is sparse and the model is asked to+surface durable knowledge, though, Sonnet's "fill in the+obvious" tendency could pay off.## Verdict@@ -639,14 +638,14 @@ prompt), the picture is clear:- **Latency**: ~92 s avg end-to-end. Acceptable becauseconsolidation is a background job, not interactive.- **Cost**: **$0 per consolidation** (electricity not modeled).-- **Fidelity**: comparable to or better than the hosted models- - qwen3 was the most faithful provider in Run 2's old-prompt+- **Fidelity**: comparable to or better than the hosted models;+ qwen3 was the most faithful provider in Run 2's old-promptcomparisons.### Best hosted fallback: Claude Haiku 4.5If the homelab is unreachable, or for one-off complex-consolidations, **Haiku 4.5 is the right hosted choice - not+consolidations, **Haiku 4.5 is the right hosted choice, notSonnet 4.5**:- **2× faster** than Sonnet at every fixture.@@ -661,7 +660,7 @@ Sonnet 4.5**:### Sonnet 4.5 - displaced by Haiku for this taskSonnet's reasoning headroom doesn't help consolidation. With-the loose prompt it expressed itself as *more hallucination*+the loose prompt it showed up as *more hallucination*(invented dates, fabricated alternative-considered tables,tutorial-style filler). The tightened prompt brings Sonnet inline, but Haiku gives identical reliability faster and@@ -671,7 +670,7 @@ claims).### Kimi-K2.6 - ineligible-Reasoning model - burns `max_tokens` budget internally before+Reasoning model that burns `max_tokens` budget internally beforeemitting visible content. Run hung for 16+ minutes on fixture 1under the strict-JSON prompt. Direct probe confirmed: `content:null` with the entire token budget consumed by `reasoning`.@@ -688,7 +687,7 @@ mode models if used in this pipeline.| DeepSeek V4 Flash (OpenRouter) | ~$0.005 | ~22 s | cheap but slower than GPT-mini || Haiku 4.5 (OpenRouter) | ~$0.02 | ~7 s | best restraint/classification || Sonnet 4.5 (OpenRouter) | ~$0.06 | ~11 s | 3× cost of Haiku for same task |-| Kimi-K2.6 (OpenRouter) | n/a | ✗ hangs | reasoning model - ineligible |+| Kimi-K2.6 (OpenRouter) | n/a | ✗ hangs | reasoning model, ineligible |\* Rough order of magnitude; ai-memory consolidations landaround 2–3 KB of output with the tightened prompt. Per-run $@@ -713,8 +712,8 @@ Re-run this harness when any of the following changes:- Repo checkout + `cargo` toolchain (Rust 1.95+, as pinned in`rust-toolchain.toml`).-- An OpenRouter API key, exported as `OPENROUTER_API_KEY` -- pays the Kimi + Sonnet legs.+- An OpenRouter API key, exported as `OPENROUTER_API_KEY`, which+ pays for the Kimi + Sonnet legs.- A reachable Ollama with `qwen3:32b` pulled. The default URLin the docs assumes the homelab; substitute your own.@@ -754,7 +753,7 @@ evals/runs/<timestamp>/```The `.raw.txt` files are the most informative artifact when a-parse fails - they show *exactly* what the model said, so you+parse fails because they show *exactly* what the model said, so youcan tell whether the failure was format (model emitted prose),schema (model used integer enums), or substance (modelproduced nothing useful).@@ -788,13 +787,13 @@ back to `Other`.Try to hit one of the four hard cases:-1. **Multi-page extraction** - does the model split a session+1. **Multi-page extraction**: does the model split a sessioninto the right slices?-2. **Restraint** - does it avoid manufacturing pages when+2. **Restraint**: does it avoid manufacturing pages whenthere's nothing durable?-3. **Classification** - does it correctly choose `kind: rule`+3. **Classification**: does it correctly choose `kind: rule`for project rules?-4. **Topic separation** - does it produce separate pages per+4. **Topic separation**: does it produce separate pages perunrelated topic instead of mashing them?## What's NOT in this harness (yet)diff --git a/docs/llm-providers.md b/docs/llm-providers.mdindex 16b60f82..9ce1964f 100644--- a/docs/llm-providers.md+++ b/docs/llm-providers.md@@ -134,7 +134,7 @@ ai-memory llm-test --provider opencode --model claude-sonnet-5-5 --prompt "Reply<a id="openrouter"></a>[OpenRouter](https://openrouter.ai) is used through the generic `openai-compat`-provider — the same wiring as Atlas Cloud, OrcaRouter, Ollama, vLLM, and LM+provider, the same wiring as Atlas Cloud, OrcaRouter, Ollama, vLLM, and LMStudio. There is no dedicated `openrouter` provider name, and setting`AI_MEMORY_LLM_PROVIDER=openrouter` fails at startup with`AI_MEMORY_LLM_PROVIDER=openrouter is not one of anthropic|openai|gemini|openai-compat|...`.@@ -170,7 +170,7 @@ env-file level is safer for consolidation reliability. Turn it offexplicitly rejects the schema-constrained shape.The `docker/.env.production.example` file in the repo ships with an OpenRouter-setup pre-filled (with `moonshotai/kimi-k2.6` as the sample model — see the+setup pre-filled, with `moonshotai/kimi-k2.6` as the sample model (see thegotchas below for why reasoning models are ineligible). Model ids followOpenRouter's `provider/model` convention. There is no built-in default:`AI_MEMORY_LLM_MODEL` is required, as it is for every `openai-compat` endpoint.@@ -178,9 +178,8 @@ OpenRouter's `provider/model` convention. There is no built-in default:### Choosing a modelFor LLM selection guidance, see-[`llm-provider-comparison.md`](llm-provider-comparison.md) — the project-maintains its own A/B testing there on consolidation quality, latency, and-cost. That comparison uses English consolidation fixtures and covers the+[`llm-provider-comparison.md`](llm-provider-comparison.md), where the project+keeps its own A/B tests of consolidation quality, latency, and cost. That comparison uses English consolidation fixtures and covers therecommended default (`anthropic/claude-haiku-4.5`), the cheaper alternative(`openai/gpt-5.4-mini`), and the reasoning-model ineligibility note; theOpenRouter subsection here defers to it rather than duplicating rankings.@@ -199,13 +198,13 @@ overrides them per operator. `AI_MEMORY_LLM_REASONING_EFFORT` is honoured onthis path: OpenRouter hosts receive `reasoning: { effort, exclude: true }`.OpenRouter's LLM/completions API is what ai-memory uses above. It does **not**-reliably expose an OpenAI-compatible `/v1/embeddings` endpoint — historically it-has not — so do not assume an OpenRouter base URL works for the embedder. If a+reliably expose an OpenAI-compatible `/v1/embeddings` endpoint (historically it+has not), so do not assume an OpenRouter base URL works for the embedder. If agiven deployment of OpenRouter does offer an embeddings endpoint, verify itanswers the standard `/v1/embeddings` shape (`curl` the endpoint directly)before relying on it. When it does, configure the embedder through the-openai-compat path — not the openai path, which has an OpenAI-specific key-precedence chain:+openai-compat path rather than the openai path, which has an OpenAI-specific+key precedence chain:```bashexport AI_MEMORY_EMBEDDING_PROVIDER=openai-compat@@ -224,21 +223,21 @@ avoids hosted egress; for non-English content, a multilingual hosted model(`baai/bge-m3`, `intfloat/multilingual-e5-large`, or similar) served by anyprovider that exposes a real `/v1/embeddings` endpoint is the practical choice.The two endpoints are still independent, so setting `AI_MEMORY_LLM_BASE_URL`-alone does not redirect embeddings — set `AI_MEMORY_EMBEDDING_BASE_URL` too.+alone does not redirect embeddings; set `AI_MEMORY_EMBEDDING_BASE_URL` too.> [!TIP]> **`openai-compat` sends `X-Request-Id` on every chat attempt.** Each HTTP-> attempt of one logical operation — including the strict-to-tolerant-> fallback — carries the same operation id (a 36-character UUID v7) in the+> attempt of one logical operation, including the strict-to-tolerant+> fallback, carries the same operation id (a 36-character UUID v7) in the> `X-Request-Id` header, so a gateway that records it (for example as> `req=<id>`) can correlate every attempt of the same operation and forward-> it to the engine (vLLM). The id is generated fresh by the caller of the-> operation — the consolidation invocation or the auto-improve review — and+> it to the engine (vLLM). The caller of the operation (the consolidation+> invocation or the auto-improve review) generates the id fresh, and it> is never the agent's session id, so a gateway never sees two operations> of one session, or a crash-resumed run, as one. Crash re-entry is exactly> one new operation: a process restart or a queue re-claim mints a new id> for the calls it makes. The official `openai` provider and `opencode` do-> not send this header — `opencode` keeps its own `x-opencode-session`+> not send this header; `opencode` keeps its own `x-opencode-session`> contract. Because ai-memory owns the header on the `openai-compat` path, a> static `x-request-id` entry in `AI_MEMORY_LLM_HEADERS` is refused at> startup for that provider; the dynamic value must not be shadowed or@@ -248,8 +247,7 @@ alone does not redirect embeddings — set `AI_MEMORY_EMBEDDING_BASE_URL` too.- **Bind address vs. port publish.** When running inside a container, theprocess-level bind (`--bind 0.0.0.0:49374` or similar) does not decide- who can reach the port — that is decided by the container's publish- spec. `-p 127.0.0.1:49374:49374` restricts to loopback on the host;+ who can reach the port; the container's publish spec does. `-p 127.0.0.1:49374:49374` restricts to loopback on the host;`-p 49374:49374` publishes on every host interface. If the port isever reachable beyond loopback, generate a bearer token first:```bash@@ -260,12 +258,12 @@ alone does not redirect embeddings — set `AI_MEMORY_EMBEDDING_BASE_URL` too.The server logs a loud startup warning about non-loopback exposurewithout a token; treat it as blocking. `AI_MEMORY_ALLOWED_HOSTS`guards against DNS-rebinding. TLS termination is expected to sit in- front of the process — see [`docs/https-via-proxy.md`](https-via-proxy.md).+ front of the process; see [`docs/https-via-proxy.md`](https-via-proxy.md).- **Secret hygiene.** The env file that holds `LLM_API_KEY` (and anyprovider-specific key you set) should be `chmod 600` and outside anydirectory a version-control tool sees. If you back up`~/.config/ai-memory/` (see [`docs/backup.md`](backup.md)), exclude- the env file — the sample script and mirror `.gitignore` shipped+ the env file. The sample script and mirror `.gitignore` shippedthere already exclude `*.env` by default.- **Cheap models can drift.** LLM consolidation writes durable wikipages, so a model that occasionally fabricates a `kind: decision`@@ -283,8 +281,8 @@ alone does not redirect embeddings — set `AI_MEMORY_EMBEDDING_BASE_URL` too.ending in `:free` on OpenRouter is served from a pool shared acrossall users of the free tier, not the caller's paid budget. When thatpool is exhausted, requests fail with an upstream-shared-pool- rate-limit error. Fine for evaluation, unreliable for production;- prefer a model listed with multiple upstream providers on its+ rate-limit error. They are fine for evaluation but unreliable for+ production; prefer a model listed with multiple upstream providers on itsOpenRouter page.- **Reasoning-mode models are ineligible for consolidation.**Consolidation and lint use a strict-JSON output contract; reasoning@@ -311,7 +309,7 @@ non-default sampling parameters. `llm-test` sends the same representative 0.2value as the normal pipeline before the provider applies that compatibilityrule.-**⚠️ Unofficial and against Anthropic's usage policies — use at your own risk;+**⚠️ Unofficial and against Anthropic's usage policies. Use at your own risk;it may get your account rate-limited or banned. See[the warning in `docs/install.md`](install.md#anthropic-via-claude-subscription-oauth).**@@ -340,7 +338,7 @@ also set `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN` on the server.> and rejects others (e.g. `gpt-5-mini`) with a deterministic 400, so do not> override the model here.> - `copilot`: a mini-class id such as `gpt-5-mini` may work, but Copilot's-> accepted model set is unverified — check before relying on it, and fall back+> accepted model set is unverified. Check before relying on it, and fall back> to the default if the endpoint rejects your choice.> [!TIP]@@ -406,15 +404,15 @@ hybrid paths apply the same bounded page-authority adjustment after candidategeneration; embeddings improve relevance recall but do not decide which sourceis canonical.-Asymmetric embedding models — ones trained with a different instruction for-queries than for the text being indexed — need that instruction added to the+Asymmetric embedding models, trained with a different instruction for+queries than for the text being indexed, need that instruction added to thetext itself; the OpenAI-compatible `/v1/embeddings` wire format has no fieldfor it. `AI_MEMORY_EMBEDDING_QUERY_PREFIX` and`AI_MEMORY_EMBEDDING_DOCUMENT_PREFIX` (only applied by the `openai` and`openai-compat` embedders) are prepended to query and document textrespectively, before the existing truncation, so a long body is stilltruncated to the same overall input cap with the prefix included. Both are-empty by default — no behaviour change when unset — and are not trimmed, so+empty by default (no behaviour change when unset) and are not trimmed, soa publisher's trailing space is preserved exactly. For example, NVIDIA's[`nvidia/Nemotron-3-Embed-1B-BF16`](https://huggingface.co/nvidia/Nemotron-3-Embed-1B-BF16)(2048-dim, served locally through vLLM/`openai-compat`) specifies@@ -432,20 +430,20 @@ embedding_document_prefix = "passage: "Base E5 models (`intfloat/e5-base-v2`, `e5-large-v2`, multilingual E5, …)use the same `"query: "` / `"passage: "` convention. Instruction-tuned E5variants and Qwen3-Embedding instead need a task-instruction string on the-**query side only** — their documents are embedded plain, with no document-prefix — but the two use **different exact spacing**, confirmed against+**query side only** (their documents are embedded plain, with no document+prefix), and the two use **different exact spacing**, confirmed againsteach model card:- `intfloat/e5-mistral-7b-instruct`:- `embedding_query_prefix = "Instruct: {task description}\nQuery: "` — a+ `embedding_query_prefix = "Instruct: {task description}\nQuery: "`, with atrailing space after `Query:`.- `Qwen/Qwen3-Embedding-0.6B` (and the other Qwen3-Embedding sizes):- `embedding_query_prefix = "Instruct: {task description}\nQuery:"` — **no**+ `embedding_query_prefix = "Instruct: {task description}\nQuery:"`, with **no**trailing space; the query text follows the colon directly.Fill in your own task description for `{task description}`, leave`embedding_document_prefix` unset for both, and don't copy one model's-exact string for the other — the trailing-space difference is+exact string for the other. The trailing-space difference ispublisher-specified, not a typo.Changing `embedding_query_prefix` alone never requires re-embedding: only@@ -454,14 +452,14 @@ Changing `embedding_query_prefix` alone never requires re-embedding: only`{provider, model, dim}` triple for that page's vectors), so a documentprefix change makes `memory_query` stop matching the old vectors and thenext `ai-memory embed` (scheduled or manual) pass re-embed them-automatically — no `--force` needed. `--force` remains useful to+automatically, without `--force`. `--force` remains useful tore-embed everything immediately rather than waiting for scheduledbackfill, or to force a re-embed for a reason the triple alone doesn'tcapture (e.g. touching up the vLLM server's tokenizer or quantization).`AI_MEMORY_EMBEDDING_PROVIDER=copilot` reuses the same Copilot OAuth login asthe `copilot` LLM provider (`ai-memory auth login copilot` or-`COPILOT_GITHUB_TOKEN`/`GITHUB_COPILOT_API_TOKEN`) — no separate API key.+`COPILOT_GITHUB_TOKEN`/`GITHUB_COPILOT_API_TOKEN`), with no separate API key.It defaults to model `text-embedding-3-small`, dim 1536, and calls Copilot's`/embeddings` endpoint following the same OpenAI-compatible contract Copilotdocuments for chat. That endpoint's exact shape is not covered by a live@@ -471,7 +469,7 @@ before relying on it in production.`AI_MEMORY_EMBEDDING_PROVIDER=local` needs no key and no server at all:sentence embeddings run in-process (pure-Rust `all-MiniLM-L6-v2`,384-dim), with the model fetched once into `<data_dir>/models/` under-pinned checksums — see [`docs/local-embeddings.md`](local-embeddings.md).+pinned checksums; see [`docs/local-embeddings.md`](local-embeddings.md).See [`docs/install.md#llm-provider-tiers`](install.md#llm-provider-tiers)for env vars and Ollama/OpenRouter/Atlas Cloud/OrcaRouter/Cheaper Inference/API Route/FutureInfradiff --git a/docs/local-embeddings.md b/docs/local-embeddings.mdindex d11641fe..3c9de46a 100644--- a/docs/local-embeddings.md+++ b/docs/local-embeddings.md@@ -1,17 +1,17 @@# Local embeddings*2.0 item 5.* `AI_MEMORY_EMBEDDING_PROVIDER=local` runs sentence-embeddings **in-process** — no API key, no external server, no GPU-required. Pure-Rust BERT inference (candle) with-`all-MiniLM-L6-v2` (384-dim), the sentence-transformers workhorse the+embeddings in-process, with no API key, external server, or GPU+required. It uses pure-Rust BERT inference (candle) with+`all-MiniLM-L6-v2` (384-dim), the sentence-transformers model thecomparable memory servers ship by default.**As of 2.0 this is the default**: an install with no-`embedding_provider` configured gets local embeddings automatically —-best-effort. The model downloads in the background on the first start-(hybrid search enables on the next restart), existing pages are-backfilled automatically, and a host that cannot fetch the model (or a-slim build without the feature) simply keeps the FTS-only behaviour+`embedding_provider` configured gets local embeddings automatically, on a+best-effort basis. The model downloads in the background on the first start+(hybrid search enables on the next restart) and existing pages are+backfilled automatically. A host that cannot fetch the model (or a+slim build without the feature) keeps the FTS-only behaviourwith a warning. Opt out with `embedding_provider = "none"`; anexplicitly configured provider is never overridden.@@ -23,15 +23,15 @@ embedding_provider = "local" # explicit: hard-fails if unavailable## Why: semantic recall without data egress-Search is hybrid: FTS5 (lexical), entities, graph, and — when an-embedder is configured — vectors. The vector stream is what lets-*"how do we deploy"* find the page that says *"release procedure"*:-paraphrase recall, no shared keywords required. Before this provider,+Search is hybrid: FTS5 (lexical), entities, graph, and, when an+embedder is configured, vectors. The vector stream lets+*"how do we deploy"* find the page that says *"release procedure"*+(paraphrase recall, with no shared keywords). Before this provider,enabling it cost one of two things:- **an API key** (OpenAI / Voyage / Google): per-call spend, and every- page body and every search query leaves your machine. For a system- whose job is recording everything you do, that is not a small ask;+ page body and every search query leaves your machine, which is a lot+ to ask of a system that records everything you do;- **a self-hosted engine** (Ollama / LM Studio via `openai-compat`):keyless, but another server to run, warm, and keep on the samenetwork as ai-memory.@@ -41,12 +41,12 @@ enabling it cost one of two things:- you run the zero-LLM path and want better recall without handing aprovider your memory;- the install is offline or air-gapped (drop the model files in- manually — see below);+ manually, as described below);- a homelab/team server where "one binary, one volume" is the wholeoperational story and adding an Ollama sidecar just for embeddingsis not worth it;- you want reproducible retrieval: same model files (checksum-pinned),- same vectors, forever — no provider-side model deprecations.+ same vectors, forever, with no provider-side model deprecations.Stick with a hosted or self-hosted provider when you already run onehappily, want a larger/multilingual model, or want embedding compute@@ -54,19 +54,19 @@ off the memory server's CPU.### Why not ONNX?-ONNX is a model format plus a native runtime (`onnxruntime`) — one-*mechanism* for local inference, and the one the comparable servers-use. We ship the same model through **candle** (pure Rust) instead:-identical capability, but no native C++ library to build, license, and-debug across every release target (Windows, macOS, the sandboxed nix-build). If a future model genuinely requires an ONNX-only runtime, the+ONNX is a model format plus a native runtime (`onnxruntime`). It is one+way to run local inference, and the one the comparable servers+use. We ship the same model through candle (pure Rust) instead. The+capability is identical, and there is no native C++ library to build,+license, and debug across every release target (Windows, macOS, the+sandboxed nix build). If a future model requires an ONNX-only runtime, the`Embedder` trait is where it would slot in.## The model filesThe binary does not bundle the model (~87 MB). On the first start with`local` configured, the server fetches three files into-`<data_dir>/models/all-MiniLM-L6-v2/` — each verified against a sha256+`<data_dir>/models/all-MiniLM-L6-v2/`. Each is verified against a sha256pinned in the source, so a drifted or tampered upstream file failsloudly instead of silently changing every vector:@@ -86,14 +86,14 @@ is Apache-2.0.Nothing is forced. `(provider, model, dim)` is stored on everyembedding row, and hybrid search ignores vectors whose triple does not-match the configured embedder — so local vectors sit beside any+match the configured embedder. Local vectors therefore sit beside anyprovider vectors you already have, and switching back is a configchange. `ai-memory embed --force` re-embeds a project under thecurrent provider when you want one consistent set.Existing installs keep their configured provider; `local` is opt-in.-Fresh-install defaults are decided by benchmark numbers, not vibes —-see `docs/benchmarks/` for the zero-LLM vs local-embeddings+Fresh-install defaults are decided by benchmark numbers.+`docs/benchmarks/` has the zero-LLM vs local-embeddingsLongMemEval rows, reproducible via:```bash@@ -107,6 +107,6 @@ cargo run --release -p ai-memory-eval -- retrieval --embeddings local- The `local-embeddings` cargo feature (default on) carries the MLdependency tree; a slim build can disable it and keep every otherprovider.-- Tokenization truncates at 512 tokens — the model's positional limit;- page bodies beyond that contribute their head, same contract as the+- Tokenization truncates at 512 tokens, the model's positional limit.+ Longer page bodies contribute only their head, the same contract as thehosted embedders.diff --git a/docs/macos.md b/docs/macos.mdindex a82c567a..dc462aa5 100644--- a/docs/macos.md+++ b/docs/macos.md@@ -7,28 +7,28 @@ and `ai-memory-macos-x86_64.tar.gz` (Intel) binaries.On macOS the **native binary** is the recommended way to run ai-memory. Threenative installs exist:-- **[Scenario D — menu bar app](#scenario-d-menu-bar-app)** — self-contained+- **[Scenario D: menu bar app](#scenario-d-menu-bar-app)**: a self-contained`.app` that bundles the binary, starts the LaunchAgent, and opens `/web`,- status, and config. The GUI path if you are building from source.-- **[Scenario A — prebuilt tarball](#scenario-a-prebuilt-release-binary-recommended-no-toolchain)** —+ status, and config. This is the GUI path if you are building from source.+- **[Scenario A: prebuilt tarball](#scenario-a-prebuilt-release-binary-recommended-no-toolchain)**:no Rust toolchain; run `serve` in a terminal or install the LaunchAgent byhand.-- **[Scenario B — source build](#scenario-b-source-build)** — developing+- **[Scenario B: source build](#scenario-b-source-build)**: for developingai-memory itself.It binds the server on `127.0.0.1:49374`, and both the MCP endpoint and the-lifecycle hooks talk to that loopback address — which the native agent can+lifecycle hooks talk to that loopback address, which the native agent canreach and which is already in the default Host-header allowlist. The Dockerwrapper ([Scenario C](#scenario-c-docker-wrapper)) is also supported when youprefer a containerised server.Unlike Windows there is only one "path world" on macOS: POSIX paths and POSIX-`.sh` hooks throughout. There is no WSL-vs-native split to get wrong.+`.sh` hooks throughout, with no WSL-vs-native split.## Rule Of ThumbRun `install-mcp` / `install-hooks` from the same shell that launches Claude-Code, Codex, Cursor, Gemini CLI, or another agent — on macOS that is just your+Code, Codex, Cursor, Gemini CLI, or another agent. On macOS that is yournormal Terminal.- The agent runs as a native macOS process, so its config must point at a@@ -36,11 +36,11 @@ normal Terminal.`install-mcp` / `install-hooks` commands render `http://127.0.0.1:49374`,which works from the host agent.- Hooks are rendered for one of two platforms:- - `posix-native` — a direct `ai-memory hook --event …` call. The default for+ - `posix-native`: a direct `ai-memory hook --event …` call. The default fornative macOS/Linux Claude Code installs (cargo / release binary) and theDocker wrapper's checksum-verified host client; it uses the local eventspool + OIDC-token fallback and enforces capture policy v1.- - `posix` — `sh` runs the bundled `.sh` script. This is an explicit+ - `posix`: `sh` runs the bundled `.sh` script. This is an explicitcompatibility fallback for the Docker wrapper.Set `AI_MEMORY_HOOK_PLATFORM` before wiring hooks to override the default.@@ -73,7 +73,7 @@ tar -xzf ai-memory-macos-aarch64.tar.gz```> **The server from step 3 must stay running for every other command.**-> `ai-memory init` only creates the data dir — it does **not** start a+> `ai-memory init` only creates the data dir; it does **not** start a> server. `bootstrap`, `install-hooks`, `install-mcp`, and `status` are all> clients that talk to the running server over HTTP, so running them while> nothing is serving fails with `Connection refused (os error 61)` /@@ -103,7 +103,7 @@ discovery canonicalises the running binary's path before walking up tothe sibling `hooks/` directory([#546](https://github.com/akitaonrails/ai-memory/issues/546), fixed inv1.39.0). **On v1.38.x or older**, the walk did not resolve through a-symlink — running `install-hooks` via `/usr/local/bin/ai-memory` sent+symlink: running `install-hooks` via `/usr/local/bin/ai-memory` sentdiscovery to the wrong parent directories, failing outright on a cleanmachine:@@ -113,9 +113,8 @@ Error: could not locate hooks directory. Tried: ["/…/hooks/claude-code","…/Library/Application Support/ai-memory/hooks/claude-code"]```-— or, worse, silently wiring a stale hooks cache from-`~/Library/Application Support/ai-memory` on a machine with an earlier-install. If you are on an older release, run `install-hooks` via the+On a machine with an earlier install it could instead silently wire a stale+hooks cache from `~/Library/Application Support/ai-memory`, which is worse. If you are on an older release, run `install-hooks` via theextracted `./ai-memory` path (or upgrade).Notes:@@ -158,7 +157,7 @@ automatically (no `--source` needed from the repo root):If you symlink the built binary onto `PATH` for convenience (e.g.`ln -sf "$(pwd)/target/release/ai-memory" ~/.local/bin/ai-memory`), do it-*after* the `install-hooks` call above, not before — see the `install-hooks`+*after* the `install-hooks` call above, not before. See the `install-hooks`symlink caution in Scenario A([#546](https://github.com/akitaonrails/ai-memory/issues/546)); it applieshere too and is the exact layout that bug was filed against.@@ -174,7 +173,7 @@ This assumes the `ai-memory` thin-client wrapper is already on `PATH`; if`ai-memory --version` doesn't resolve yet, install it first via the[README Docker quick-start](../README.md#docker) (downloads a small shellscript to `~/.local/bin/ai-memory`). On a stock macOS Terminal `~/.local/bin`-is **not** on `PATH` by default — add+is **not** on `PATH` by default; add`export PATH="$HOME/.local/bin:$PATH"` to `~/.zshrc` if `which ai-memory`comes up empty after installing the wrapper.@@ -213,7 +212,7 @@ open "companions/ai-memory-macos/dist/AI Memory.app"Drag `AI Memory.app` to `/Applications` so the LaunchAgent path stays stableacross rebuilds. The menu extra has no Dock icon.-1. **Install & Start Server** — runs bundled `ai-memory init` if+1. **Install & Start Server** runs bundled `ai-memory init` if`~/Library/Application Support/ai-memory/config.toml` is missing, renders`packaging/launchd/com.github.akitaonrails.ai-memory.plist`, and bootstrapsthe same `com.github.akitaonrails.ai-memory` label as the hand-installed@@ -246,7 +245,7 @@ Notarization and a Homebrew cask are not part of this companion yet.Scenarios A–C leave the server in the foreground: close that terminal andcapture stops. Scenario D already installs this LaunchAgent from **Install &Start Server**. The macOS counterpart of a systemd user unit is a-**LaunchAgent** — a plist in `~/Library/LaunchAgents/` that the per-user+**LaunchAgent**: a plist in `~/Library/LaunchAgents/` that the per-userlaunchd domain starts at login and restarts on failure. The repo ships one at`packaging/launchd/com.github.akitaonrails.ai-memory.plist`, and the macOSrelease tarballs include it.@@ -298,8 +297,8 @@ tail -f ~/Library/Logs/ai-memory/stderr.log| `systemctl --user status ai-memory` | `launchctl print gui/$(id -u)/<label>` || `systemctl --user restart ai-memory` | `launchctl kickstart -k gui/$(id -u)/<label>` || `journalctl --user -u ai-memory -f` | `tail -f ~/Library/Logs/ai-memory/stderr.log` |-| `loginctl enable-linger $USER` | no equivalent — a LaunchAgent stops at logout |-| `EnvironmentFile=` | no equivalent — see the token note below |+| `loginctl enable-linger $USER` | no equivalent; a LaunchAgent stops at logout |+| `EnvironmentFile=` | no equivalent; see the token note below |`<label>` is `com.github.akitaonrails.ai-memory`. After editing the plist,`bootout` then `bootstrap` again; `kickstart -k` only restarts the process and@@ -307,7 +306,7 @@ does not re-read the definition.### If you configure a bearer token-`AI_MEMORY_AUTH_TOKEN` is read from the process environment only — it is not a+`AI_MEMORY_AUTH_TOKEN` is read from the process environment only. It is not a`config.toml` key, and launchd has no `EnvironmentFile`. A single-user loopbacksetup needs no token at all. If you do set one, add it to your rendered plistand tighten the file, because `~/Library/LaunchAgents` is not private:@@ -342,8 +341,8 @@ Nothing rotates the two log files; they grow without bound. Add a> the reply came from the agent rather than a foreground server left over on the> same port; `~/Library/Application Support/ai-memory` resolved and logged as> the data dir with no `--data-dir` passed; `405` from `GET /mcp` on the bound-> port; `KeepAlive` — the served process was `SIGKILL`ed and a replacement was-> answering about a second later, with `runs` incrementing; and a clean+> port; `KeepAlive` (the served process was `SIGKILL`ed and a replacement was+> answering about a second later, with `runs` incrementing); and a clean> `launchctl bootout`. Start-at-login was configured but not independently> exercised, since that needs a logout. `ThrottleInterval` is left at its 10s> default, so a crash within 10s of startup is respawned after that delay rather@@ -389,7 +388,7 @@ wrapper's `posix` shell-script path does not. Re-run `install-hooks --agent- **`install-hooks` wires the wrong (or no) `hooks/` bundle even though thetarball was extracted whole:** if the binary is reached through a symlink(e.g. you put it on `PATH` before running `install-hooks`), macOS discovery- does not resolve the symlink and searches the wrong parent directories —+ does not resolve the symlink and searches the wrong parent directories;see [#546](https://github.com/akitaonrails/ai-memory/issues/546). On aclean machine this fails outright with `Error: could not locate hooksdirectory. Tried: [...]`; if a hooks cache from an earlier install already@@ -410,7 +409,7 @@ wrapper's `posix` shell-script path does not. Re-run `install-hooks --agent- **`Error: binding 127.0.0.1:49374` / `Address already in use` (the serverexits immediately and the menu extra stays red):** another process alreadyholds the port, for example OpenCode v2's background service (reported in- #1044 to default to 49374). Move one side — start+ #1044 to default to 49374). Move one side: startai-memory elsewhere (`bind = "127.0.0.1:<free-port>"` in`~/Library/Application Support/ai-memory/config.toml`, then update the app'sserver URL in Settings to match), or move the other servicediff --git a/docs/managed-workstreams.md b/docs/managed-workstreams.mdindex 2c046a7c..7ec4620c 100644--- a/docs/managed-workstreams.md+++ b/docs/managed-workstreams.md@@ -7,32 +7,31 @@ keep their existing ai-memory behavior. There is no global mode toggle and no`switch` command: using `run` selects the current workstream and transparentlycreates or resumes the correct native session for the requested harness.-**`ai-memory run` is the preferred way to start a harness — "if in doubt, run-with ai-memory."** Beyond session continuity, the first time it launches a given-harness it **auto-installs that harness's ai-memory hooks and MCP** if they are+`ai-memory run` is the preferred way to start a harness: if in doubt, run+with ai-memory. Besides session continuity, the first time it launches a given+harness it auto-installs that harness's ai-memory hooks and MCP if they arenot already wired, so capture and recall work without a separate `install-hooks`/ `install-mcp` step (a common footgun: `ai-memory run kimi` used to capturenothing if the Kimi hooks were never installed). Auto-wire is idempotent andone-time per harness, binary version and install location (a second config home,such as another `CLAUDE_CONFIG_DIR`, gets its own first launch; `ai-memory-uninstall` of hooks or MCP clears that record, so the next launch wires again),-preserves-unrelated user config, runs-before the harness starts so it picks up the fresh hooks, and is best-effort —-if an install fails it warns and still launches. Harnesses without installer+uninstall` of hooks or MCP clears that record, so the next launch wires again).+It preserves unrelated user config, runs before the harness starts so it picks+up the fresh hooks, and is best-effort: if an install fails it warns and still+launches. Harnesses without installersupport (Crush) are skipped; Pi wires hooks but has no MCP client to write. Turnit off with `ai-memory run --no-autowire`, `AI_MEMORY_RUN_AUTOWIRE=false`, or`run_autowire = false` in config; manual `install-hooks` / `install-mcp` remainavailable for harnesses you never launch through `run`.-The launcher resolves its executable name through `PATH` directly — it does+The launcher resolves its executable name through `PATH` directly. It doesnot go through an interactive shell, so a `claude` defined only as a shell`alias` in `.bashrc`/`.zshrc` is invisible to it. If you switch Claudeaccounts by alias, put a same-named script or shim earlier on `PATH` instead(or pass `--executable PATH`, which also resolves a bare name through`PATH`), so the resolved `claude` process actually is the one you meant.-**Named launch profiles.** Persist repeated per-account environment overrides+Named launch profiles persist repeated per-account environment overridesin the same `config.toml` the client loads:```toml@@ -65,7 +64,7 @@ ai-memory run --profile work omp --profile omp-work**Multiple Claude accounts (e.g. Corporate and Personal).** Any harness namestarting with `claude` is accepted (`claude-corp`, `claude-personal`, ...)-and always selects the Claude harness — the exact spelling never changes+and always selects the Claude harness. The exact spelling never changesthe agent kind, session store, or transcript import.Combine that wildcard with `--executable` to launch the right account'sbinary while keeping each account's managed workstream distinguishable in@@ -141,7 +140,7 @@ ai-memory run [--workspace NAME] [--project NAME]The default is the most recently selected workstream for the current repositoryand worktree, creating one named `default` on first use. `--new NAME` starts anindependent line of work; `--workstream NAME` returns to one. These are optional-branching controls, not harness-switch controls.+branching controls; they do not switch harnesses.List the workstreams available to those selectors without launching a harness:@@ -168,27 +167,27 @@ prints. The rename is metadata only. Names are unique per checkout, so adestination another workstream already holds is refused rather than merged,and the destination is validated exactly like a `--new` name. Because theledger, linked harnesses, and managed runs all key on the workstream id rather-than its name, nothing else moves — including which workstream a bare-`ai-memory run` resumes, and the listing order, both of which stay put because+than its name, nothing else moves. That includes which workstream a bare+`ai-memory run` resumes and the listing order, both of which stay put becausea rename deliberately does not touch `selected_at` or `updated_at`. A run thatis already live keeps displaying the name it launched with until it exits.## Do you need this?-Probably not at first — hooks alone already carry most continuity.+Probably not at first. Hooks alone already carry most continuity.-- **Skip it** when a handoff is all you want: you quit Claude Code+- Skip it when a handoff is all you want: you quit Claude Codemid-task, open Codex in the same directory, and the next sessionstarts with "where you left off, what failed, what's open". Thatworks with nothing but `install-hooks`; no `ai-memory run` involved.-- **Use it** when you want the harness's own native resume (`claude- --resume` / the picker) to survive a harness SWITCH — the managed- ledger records the visible event stream portably, so `ai-memory+- Use it when you want the harness's own native resume (`claude+ --resume` / the picker) to survive a switch to another harness. The+ managed ledger records the visible event stream portably, so `ai-memorycontinue` can reopen the same workstream in a different agent with- the exact tool-call history, not just a summary.+ the exact tool-call history instead of a summary.If you never switch harnesses mid-workstream, the default path is-simpler and loses you nothing.+simpler and you lose nothing by staying on it.## Project-first launcher@@ -243,7 +242,7 @@ ai-memory continue --workspace workThe checkout is chosen entirely on the client, from the `linked_at` stamp thatevery successful managed prepare writes to `client-projects.json`. The server-is never asked which directory to use — it does not expose host paths, and a+is never asked which directory to use: it does not expose host paths, and alink can only be trusted after this host revalidates it.Before launching, the newest link is rechecked twice: the recorded path must@@ -348,10 +347,10 @@ adapter to the pool, so shared V1/V2 storage never duplicates a candidate.OpenCode 2 sessions run inside a shared background service, so its plugincannot see a managed run's environment the way in-process plugins do. Managed`run opencode2` legs launch with the correct resume selectors, capture through-hooks, and import the beta transcript — all verified live — but the+hooks, and import the beta transcript (all verified live), but theledger-delta acknowledgement (`context_delivered`) does not fire, because the-accept path requires the run id on the session-start hook. The failure mode is-redelivery, never loss: a later leg into another harness may receive the range+accept path requires the run id on the session-start hook. When this fails the+range is redelivered, never lost: a later leg into another harness may receive the rangeagain. Until the beta offers per-invocation plugin context, cross-harnesscontinuity into opencode2 arrives through the ordinary handoff loop ratherthan the ledger delta.@@ -423,7 +422,7 @@ resume, continue, session, or fork selector.not seen. Crush, which has no SessionStart hook, receives the same boundedpacket through a temporary `options.global_context_paths` entry. Kimi Codefires SessionStart but discards its stdout, so the kimi adapter's- SessionStart hook only captures the event — it neither fetches nor links.+ SessionStart hook only captures the event; it neither fetches nor links.The UserPromptSubmit hook issues the `/handoff` GET with the native`session_id` in the query; the server links the session and renders thepacket atomically, and Kimi Code injects the hook's stdout as a user@@ -513,8 +512,8 @@ active run.## Degraded offline launches-When the ai-memory server is unreachable — a remote homelab down for-maintenance, a VPN that is not up — `ai-memory run` does not abort. It probes+When the ai-memory server is unreachable (a remote homelab down for+maintenance, a VPN that is not up), `ai-memory run` does not abort. It probesthe server first (any HTTP answer counts as reachable, so an older buildwithout `/healthz` still passes), prints one loud warning naming the serverURL and what the degraded run means, and launches the harness anyway:@@ -524,16 +523,16 @@ URL and what the degraded run means, and launches the harness anyway:Nothing that needs the server runs: no prepare, lease, link, heartbeat,context fetch, status check, finish, or import.- **Still works**: the harness's ai-memory lifecycle hooks (if installed) keep- capturing — events spool locally and drain automatically when the server+ capturing. Events spool locally and drain automatically when the serverreturns. An existing MCP registration degrades to no-recall for the session- rather than blocking it (the same principle as `docs/mcp-install.md`'s- optional-mode entries: an unreachable memory server costs you recall, not- the session).+ instead of blocking it (the same principle as `docs/mcp-install.md`'s+ optional-mode entries: an unreachable memory server costs you recall, but+ the session still runs).- **Sessions**: because no lease exists there is no mutual exclusion againstanother launcher in the same checkout, so a degraded launch never adopts orresumes a session implicitly. An explicit native session selector- (`claude --resume <id>`, `codex continue`, …) still resumes — you named the- session — and everything else starts a fresh session.+ (`claude --resume <id>`, `codex continue`, …) still resumes, because you named+ the session; everything else starts a fresh session.- **Auto-wire**: the first-launch hook install still happens (it is local andidempotent, and capture must spool offline), but no MCP entry is registeredfor the now-unreachable server and no completion sentinel is written, so the@@ -552,7 +551,7 @@ failed drain passes (8 by default), 7 days of age, or the 10,000-file spoolcap. For a planned outage set `AI_MEMORY_HOOK_SPOOL_MAX_ATTEMPTS=0` to disableonly the attempt-count drops (see `docs/install.md`).-If the server dies *during* a run — after the lease was acquired — the exit+If the server dies *during* a run, after the lease was acquired, the exitcode is still preserved: the unimported transcript is reported as a warningwith the exact `ai-memory finalize-session` command that repairs the recordonce the server is back, and the orphaned lease expires on its own within 90@@ -781,7 +780,7 @@ opt-in real-harness acceptance pass.Recent Codex releases run sessions through a shared background app-serverdaemon (`codex agents` lists it). The daemon keeps the environment it started-with, and the lifecycle hooks it launches inherit that environment — including+with, and the lifecycle hooks it launches inherit that environment, includingthe `AI_MEMORY_RUN_ID` of whichever managed run auto-started it. When a latermanaged Codex SessionStart reports that finished id, ai-memory ignores it asauthority and searches only the request's already-resolved repository, exact@@ -801,8 +800,8 @@ ai-memory run codex --no-daemon`--no-daemon` makes that one session run without the shared background servereven if one is already running; it is available on Codex's interactive and-`resume` commands (checked on Codex 0.156). It remains a useful isolation-switch, not a requirement for normal workstream continuity.+`resume` commands (checked on Codex 0.156). It remains useful for isolation,+but normal workstream continuity does not require it.## Installation and recovery@@ -832,9 +831,10 @@ is a one-way hash of the working directory, so discovery always reads`state.json`'s current `cwd` field or legacy `workDir` alias and never parsesthe bucket name. Conflicting aliases or a persisted id that disagrees with thesession directory are rejected. Event ids derive-from the SHA-256 of the raw wire.jsonl line, so two byte-identical lines —-only possible with identical content in the same millisecond, because Kimi-Code stamps each record with `time` — collapse into a single ledger event.+from the SHA-256 of the raw wire.jsonl line, so two byte-identical lines+collapse into a single ledger event. That can only happen with identical+content in the same millisecond, because Kimi Code stamps each record with+`time`.The incremental cursor stores both the complete-record byte offset and aSHA-256 of that imported prefix. Normal appends resume at the saved offset;if Kimi rewrites `wire.jsonl` in place, ai-memory resets to the beginning and@@ -903,8 +903,8 @@ Antigravity keeps one SQLite database per conversation atfile name and no scan is needed to locate one. The workspace a conversation wasopened on comes from `trajectory_metadata_blob`, a protobuf message whose firstfield holds a nested message whose first field is the workspace `file://` URI;-only those two fields are read. A database that does not carry them — an older-or newer `agy` — is skipped rather than failing the listing. Note the recorded+only those two fields are read. A database that does not carry them (from an+older or newer `agy`) is skipped instead of failing the listing. Note the recordedworkspace is the directory `agy` was launched from, not a checkout root, so aconversation started one level up is not offered inside a subdirectory.@@ -970,14 +970,14 @@ the conflict remains and concurrent writers are still rejected.### Lease recovery-A launcher that dies without releasing its lease — killed, its terminal-closed, or a sandbox such as ai-jail torn down — leaves the workstream held+A launcher that dies without releasing its lease (killed, its terminal+closed, or a sandbox such as ai-jail torn down) leaves the workstream helduntil that lease lapses. An interactive relaunch (stdin and stderr areterminals) no longer fails on that: the conflict reports the lease's expiry, soai-memory says who holds it and waits for it to lapse (at most one lease,~90 seconds; `Ctrl+C` aborts), then starts normally. If the holder renews thelease while you wait, it is a launcher that is still running, and you get an-error instead — stop it, or pass `--new <name>` for a separate workstream. The+error instead. Stop it, or pass `--new <name>` for a separate workstream. Theserver's busy check stays the only arbiter: the waiting launcher never forcesanother run off. Non-interactive launches (scripts, hooks, CI) keep the shortretry window and fail fast rather than hanging. Terminal@@ -996,7 +996,7 @@ ai-memory run codex --force-unlockThe replacement is atomic and limited to the same durable authenticatedoperator; in single-user or otherwise unattributed operation, both runs must beunattributed. A different operator's active run is still refused. The command-expires the managed lease only — it does not signal or kill a native process.+expires the managed lease only; it does not signal or kill a native process.If the previous launcher is actually alive, its later heartbeats and finish arerejected, and its final transcript tail may not be imported. Use`--force-unlock` only after verifying that launcher has stopped. Older servers@@ -1068,8 +1068,8 @@ content, system/developer prompt records, and hidden reasoning are not copied. Tserver sanitizer runs before both the SQLite FTS ledger and immutable files under`<data_dir>/raw/workstreams/<workstream-id>/segments/` are written.-The ledger is an operational continuity substrate, not a replacement for the-markdown wiki. Durable decisions, rules, procedures, and project facts still+The ledger carries operational continuity and does not replace the markdown+wiki. Durable decisions, rules, procedures, and project facts stillbelong in wiki pages through consolidation or explicit durable writes.## Project and directory renames@@ -1172,28 +1172,28 @@ process, falling back to matching the agent's own screen output againstper-agent manifests.`ai-memory run` sits awkwardly between the two. The foreground process is the-wrapper and the agent is its child — one process group whose leader is-`ai-memory` — so process detection does not find the agent. The pane resolves+wrapper and the agent is its child (one process group whose leader is+`ai-memory`), so process detection does not find the agent. The pane resolvesonly once the harness paints a title Herdr recognizes, which can be well afterlaunch and may never happen for a harness whose output matches no manifest.Until then Herdr's agents pane shows nothing for that pane.-ai-memory does not try to fix this from the inside, deliberately. Herdr's hint+ai-memory deliberately does not try to fix this from the inside. Herdr's hintfor wrapper commands, `HERDR_AGENT`, is scoped to the pane's foreground-process, and a process cannot amend its own environment after exec — so the+process, and a process cannot amend its own environment after exec, so thewrapper has no way to describe itself to Herdr once it is already running.Setting the variable on the agent it spawns would put it somewhere Herdr doesnot look for it.Two things work today.-**Name the agent on the command**, where Herdr does look:+Name the agent on the command, where Herdr does look:```bashHERDR_AGENT=codex ai-memory run codex```-**Or install Herdr's own agent integration**, which is the better answer:+Or install Herdr's own agent integration, which is the better option:```bashherdr integration install codex@@ -1201,8 +1201,8 @@ herdr integration install claude```An installed integration reports agent identity and lifecycle state over-Herdr's socket and is authoritative regardless of process detection — so the-wrapper stops mattering entirely. It also upgrades what Herdr can show: real+Herdr's socket and is authoritative regardless of process detection, so the+wrapper no longer matters. It also upgrades what Herdr can show: real`idle` / `working` / `blocked` signals instead of inferring from the screen,which cannot reliably see `blocked` at all.diff --git a/docs/marker-file.md b/docs/marker-file.mdindex 7c31abce..5bb36bc4 100644--- a/docs/marker-file.md+++ b/docs/marker-file.md@@ -12,12 +12,12 @@ without one uses `project = basename($cwd)`. That works for a solo developer in`~/projects/<repo>` but breaks downfor the cases this marker file is built for:-- **Multi-client consultancies** with `~/projects/<client>/<repo>` —+- **Multi-client consultancies** with `~/projects/<client>/<repo>`:every client should land in a dedicated workspace, not "default".- **Work / personal / open-source separation** for solo developerswho want isolation by life context.- **Mono-repos** where you'd like all packages under one project- (instead of basename-of-each-package buckets) — or each package+ (instead of basename-of-each-package buckets), or each packageunder its own project, your call.The marker file lets you declare these mappings without forking@@ -265,7 +265,7 @@ falsy (`false` / `0` / `no` / `off`, quoted or bare). A marker that sets only`[profile]` keys is a settings boundary, like one with `[briefing]` keys.`default_global` and `inject_on_session_start` accept a truthy value-(`true` / `1` / `yes` / `on`, quoted or bare — section-style keys are+(`true` / `1` / `yes` / `on`, quoted or bare; section-style keys areparsed leniently); anything else behaves as absent. `max_chars` is aplain integer.@@ -276,7 +276,7 @@ after the brief (see `docs/cross-project-profile.md`): the profile's entriesare delivered as defaults the agent applies when the user and therepository's rules file say nothing. A hard rule that must hold in thisrepository whatever the defaults say still belongs in the agent's own rules-file (`CLAUDE.md` / `AGENTS.md`), which takes precedence over memory — see the+file (`CLAUDE.md` / `AGENTS.md`), which takes precedence over memory. See the"Rules, memory and the profile" guidance in `docs/usage.md`. Other `_global`pages stay reachable on demand through `memory_query`, which unions them.@@ -295,7 +295,7 @@ others on a shared instance.## Allowlist mode: the marker as an opt-in-By default this file is optional — a repository without one is still captured,+By default this file is optional: a repository without one is still captured,and the marker only *narrows* what is taken. An install can invert that:```bash@@ -303,8 +303,8 @@ ai-memory install-hooks --apply --capture-mode allowlist```Under allowlist mode the presence of a `.ai-memory.toml` **is** the opt-in. A-repository without one emits no lifecycle event at all — prompts, tool calls-and session boundaries alike — dropped in the hook process before anything+repository without one emits no lifecycle event at all. Prompts, tool calls+and session boundaries alike are dropped in the hook process before anythingreaches the local spool or the wire. No extra key is needed: an existing markeralready opts its repository in, whatever else it configures.@@ -317,7 +317,7 @@ The mode is stored per install rather than per agent, and a later bare`install-hooks --apply` (including an upgrade refresh) leaves it in place.It is enforced both by native `ai-memory hook` commands and by the generated-TypeScript integrations (`pi`, `omp`, `opencode`, `opencode2`, `openclaw`) —+TypeScript integrations (`pi`, `omp`, `opencode`, `opencode2`, `openclaw`);each bakes the selected mode in and carries the same marker-presence gatebefore it ever POSTs. Only the raw script-fallback paths (the`AI_MEMORY_HOOK_PLATFORM` override, the Docker host wrapper, and@@ -459,9 +459,9 @@ out of capture:ignore_paths = ["private/**", "~/personal-notes/**"]```-A repository that keeps its decision records in the tree — an ADR directory,+A repository that keeps its decision records in the tree (an ADR directory,a [Keep the Why](https://github.com/oliver-zehentleitner/keep-the-why)-`context/` tree — belongs here too: `ignore_paths = ["docs/adr/**"]` or+`context/` tree) belongs here too: `ignore_paths = ["docs/adr/**"]` or`["context/**"]`. The repo owns that record; without the exclusion an agent'sread of it is captured and consolidation compiles it into wiki pages that donot follow the repo, so the copy is stale the moment the record is superseded@@ -600,7 +600,7 @@ Stop/assistant-message capture is disabled by default and never persisted; it isavailable only through the explicit double opt-in described in the install guide(`install-hooks --capture-assistant` on the client plus `capture_assistant` onthe server), where the excerpt is sanitized on both sides and capped. It is not-gated by this marker file — assistant text is not path-attributable, so a+gated by this marker file: assistant text is not path-attributable, so a`.ai-memory.toml` cannot narrow it. The metadata header is closed; thePostToolUse response/error excerpt remains the existing bounded content capture.Capture exclusions are evaluated only where paths have a proven schema, so they@@ -666,8 +666,8 @@ This means it works even when the worktree directory lives **outside**the main repo tree (some tools keep worktrees in a separate directory,so the worktree has no `.ai-memory.toml` ancestor of its own) and evenwhen the server runs in a container that cannot see the host checkout.-Put the marker anywhere on the walk-up path from the worktree — commonly-a single `~/.ai-memory.toml` — to select the strategy.+Put the marker anywhere on the walk-up path from the worktree (commonly+a single `~/.ai-memory.toml`) to select the strategy.### Repository identity@@ -685,9 +685,9 @@ with each event. The first rung that yields one wins:4. the folder name.Only rungs 1 and 3 change routing. A declared `project` routes by name as it-always has — a statement outranks the remote, so a fork whose marker names-its own project is never filed under the repository it forked from — and a-bare folder name routes exactly as before. What routes by identity is an+always has, because a statement outranks the remote: a fork whose marker names+its own project is never filed under the repository it forked from. A bare+folder name routes exactly as before. What routes by identity is anundeclared checkout with a remote, or a checkout with an explicit`identity`:@@ -721,7 +721,7 @@ repository path without the host, with `/` written as `-``https://gitlab.com/acme/group/api.git` → `acme-group-api`), so everyworktree and clone agrees on the name. Only the name changes: captures stillroute by the full identity (`github.com/acme/api`), and the style rides along-only with a remote identity — a declared `project` or `identity` keeps its+only with a remote identity. A declared `project` or `identity` keeps itsown name.- **Existing projects keep their UUID.** Reads by the canonical path name or@@ -731,8 +731,8 @@ own name.every other dependent row remain attached to the same UUID. The v2 basenameremains readable through v3.- **Another forge is never merged in.** When the path name is already held by- a different repository — typically the same path on another forge- (`gitlab.com/acme/api` after `github.com/acme/api`) — the newcomer falls+ a different repository (typically the same path on another forge,+ `gitlab.com/acme/api` after `github.com/acme/api`), the newcomer fallsback to the name it would get without the style.- Local marker aliases and operator-home identity/path routes keep theirdocumented precedence over the default and remain available for migration or@@ -794,14 +794,14 @@ ai-memory install-hooks --apply --agent claude-code --project-strategy repo-root```Every session for that install then resolves its project from the main git-repo root — so an agent that runs `mkdir sub && cd sub` and stays there no+repo root, so an agent that runs `mkdir sub && cd sub` and stays there nolonger forks the rest of the session into a phantom project named `sub`.This is **install-time config**, written into the agent's hook command (and-the generated OpenCode / OMP / Pi / OpenClaw plugins) — the same status as the+the generated OpenCode / OMP / Pi / OpenClaw plugins), with the same status as the`AI_MEMORY_AUTH_TOKEN` / `AI_MEMORY_HOOK_URL` it sits beside, *not* a user-setruntime override (which was deliberately rejected in #16). The flag accepts-`basename` (the new-install default — bakes nothing) or `repo-root`. A later+`basename` (the new-install default, which bakes nothing) or `repo-root`. A later`install-hooks --apply` without the flag preserves the value already baked intoai-memory's hooks; pass `--project-strategy basename` explicitly to remove it.@@ -842,7 +842,7 @@ Two guarantees hold in **both** modes:name while honoring a declared one. A client older than v1.27 sends noprovenance, and its overrides stay authoritative.- **Broad anchors never stick.** A session rooted at `/` or at `$HOME` is not- a meaningful anchor, so it never captures events beneath it — otherwise one+ a meaningful anchor, so it never captures events beneath it. Otherwise onestray session started in `$HOME` would fold every project into a singlebucket.@@ -876,14 +876,14 @@ Both entry points, as of v1.20:- **Lifecycle hooks** forward the marker's fields to the server on everyevent, so session captures land in the declared scope.- **Client CLI commands** resolve `(workspace, project)` locally before- calling the server — `run`, `bootstrap`, `search`, `read-page`,+ calling the server: `run`, `bootstrap`, `search`, `read-page`,`write-page`, `lint`, `curator`, `embed`, `pending-writes`,`forget-sweep`, `auto-improve`, `purge-project`, `rename-project`,`move-project` and `move-session --from-project` (source side), and friends.Before v1.20 only the hooks read it. A checkout declaring`workspace = "acme"` therefore had its captures land in `acme` while every-CLI command resolved into `default` — the same repository split across two+CLI command resolved into `default`: the same repository split across twoscopes, with `ai-memory run`'s managed workstream on the wrong side of thesplit.@@ -908,7 +908,7 @@ ai-memory: scope acme/api (workspace + project from /Users/dev/projects/acme/.ai`AI_MEMORY_IGNORE_MARKER=1` skips rung 2 for one invocation, restoring thepre-v1.20 resolution without editing or leaving the marker's tree. It-applies to **client commands only** — the lifecycle hooks still forward the+applies to **client commands only**. The lifecycle hooks still forward themarker's fields on every event, so an invocation run with it set resolvesinto a different scope than the session captures around it. Use it forone-off reads, not as a way to relocate a repository's memory.@@ -919,21 +919,21 @@ hook events that arrive without a usable one.## What the marker file does NOT do-- ❌ No glob patterns. Walk-up by literal ancestry only.-- ❌ No merge of ancestor markers. Closest wins. (`server` is the one key+- No glob patterns. Walk-up by literal ancestry only.+- No merge of ancestor markers. Closest wins. (`server` is the one keyinherited from the nearest marker that declares it; see above.)-- ❌ No automatic migration of `default`-workspace projects.-- ❌ No automatic repo-root collapsing. Worktrees and subdirectories only+- No automatic migration of `default`-workspace projects.+- No automatic repo-root collapsing. Worktrees and subdirectories onlyshare a project when `project_strategy = "repo-root"` is explicitly set- (per marker, or baked install-wide — see above).-- ❌ No URL or token in the marker. `server = "<name>"` selects a server+ (per marker, or baked install-wide; see above).+- No URL or token in the marker. `server = "<name>"` selects a serverprofile registered locally with `ai-memory server add`; it cannot introduce anew destination or carry a credential. Otherwise use the existing env vars(`AI_MEMORY_AUTH_TOKEN`, `AI_MEMORY_HOOK_URL`). (A repo-root*default* can still be baked into an install without a marker via`install-hooks --project-strategy repo-root`, but that is install-timeconfig, not a runtime override the user sets in their shell.)-- ❌ No reach outside the trust boundary. The walk stops at `$HOME`; a+- No reach outside the trust boundary. The walk stops at `$HOME`; acheckout outside it stops at that checkout's root and needs a marker insidethe checkout. A non-git directory outside `$HOME` needs a marker in itsexact cwd.@@ -943,7 +943,7 @@ hook events that arrive without a usable one.**My marker isn't being picked up.** Walk through:1. File is named exactly `.ai-memory.toml` (note the leading dot).-2. File is in an **ancestor** of the cwd — not a sibling, not a+2. File is in an **ancestor** of the cwd, not a sibling or adescendant.3. There isn't a closer marker overriding it. Run`find ~/projects -maxdepth 5 -name '.ai-memory.toml'` to see alldiff --git a/docs/mcp-install.md b/docs/mcp-install.mdindex 44ad1139..fddc1b27 100644--- a/docs/mcp-install.md+++ b/docs/mcp-install.md@@ -10,11 +10,11 @@ It shows direct MCP writes, queries and handoffs without a native hook adapter.> **Transport is stateless by default.** Since v0.1.2 the HTTP transport> answers each request independently (plain JSON, no `Mcp-Session-Id`-> required), so any client that points a remote URL at `/mcp` — including-> OpenCode `type: "remote"` and plain `curl` — works without an+> required), so any client that points a remote URL at `/mcp`, including+> OpenCode `type: "remote"` and plain `curl`, works without an> `mcp-remote` stdio shim (issue #3). The `mcp-remote` bridge is still> needed for **Claude Desktop** specifically, because its config only-> supports stdio servers — not because of session state. If you run a+> supports stdio servers; session state has nothing to do with it. If you run a> client that *requires* MCP session continuity or server-initiated SSE> streams, start the server with `ai-memory serve --transport http> --http-stateful` to restore rmcp's session mode.@@ -297,7 +297,7 @@ nothing is pending.**Status:** ✅ MCP supported (workspace-default). ❌ No lifecycle hooks(Copilot's agent mode does not expose `PreToolUse` / `PostToolUse` /`SessionStart` yet, so ai-memory's automatic capture is not active in-VS Code — call `memory_query`, `memory_write_page`, etc. from chat).+VS Code; call `memory_query`, `memory_write_page`, etc. from chat).**Config file:**- Workspace (recommended): `.vscode/mcp.json` in the repo root. Matches@@ -362,13 +362,13 @@ Aliases: `copilot`, `github-copilot`.auto-reload `.vscode/mcp.json` while the window is focused on anothertab.- Copilot Enterprise behaves the same as Copilot Individual/Business- for MCP — your org may restrict which MCP servers Copilot is allowed+ for MCP. Your org may restrict which MCP servers Copilot is allowedto call; check **Settings → Copilot → MCP servers** if the servershows as blocked.- Lifecycle hooks aren't possible until VS Code Copilot adds an agenthook surface. Until then, the auto-handoff flow that other agentsenjoy (SessionStart auto-fetches a "where you left off" block) does- not run here — ask the agent to call `memory_handoff_accept`+ not run here. Ask the agent to call `memory_handoff_accept`manually if you want it.- Sources:<https://code.visualstudio.com/docs/copilot/customization/mcp-servers>,@@ -778,12 +778,12 @@ which merges:Lifecycle capture is separate and script-free: `ai-memory install-hooks--agent zero --apply` merges exec-form entries (the native `ai-memory hook`-command + args, JSON payload on stdin — no shell) into+command + args, JSON payload on stdin, no shell) into`~/.config/zero/hooks.json`, covering `sessionStart`/`sessionEnd`/`beforeTool`/`afterTool` plus `specialistStart`/`specialistStop` (mapped toai-memory's subagent events). Zero discards `sessionStart` hook stdout, socapture and session-end handoff *creation* work, but handoff *injection*-does not — ask Zero to call `memory_handoff_accept` at the start of a+does not. Ask Zero to call `memory_handoff_accept` at the start of aresumed session.Zero runs hook commands inside its execution sandbox. The default policy@@ -989,16 +989,16 @@ available.Real Devin hook payloads may omit `session_id` and `cwd`; the installed hooksfill both in:-- **cwd** — the payload's `cwd` wins when present, then the+- **cwd**: the payload's `cwd` wins when present, then the`DEVIN_PROJECT_DIR` environment variable (when Devin's launcher providesit), then the hook process working directory.-- **session id** — when the payload has none, the hook mints one at+- **session id**: when the payload has none, the hook mints one at`SessionStart`, stores it in a single per-host slot(`<data-dir>/hook-state/devin-session-id`), reuses it for every laterevent, and clears it at `SessionEnd`. Set `AI_MEMORY_SESSION_ID` in thehook environment to pin an externally managed run id instead. Because theslot is per host+agent, two Devin sessions running *concurrently* on the- same machine share it — the newest `SessionStart` wins and earlier+ same machine share it: the newest `SessionStart` wins and earliersessions' remaining events are attributed to it (same graceful-degradationstance as the single-slot `/handoff` fallback). A payload that does carryits own `session_id` always wins over both.@@ -1036,14 +1036,14 @@ which merges:`install-mcp` appends the `?flavor=moonshot` query itself (idempotently, sore-runs don't duplicate it). The Moonshot API validates tool parameterschemas against a restricted dialect ("moonshot flavored json schema") that-rejects root-level `anyOf`/`oneOf`/`allOf` combinators — including the-`anyOf` on `memory_read_page` — and fails the whole session with a 400 at+rejects root-level `anyOf`/`oneOf`/`allOf` combinators (including the+`anyOf` on `memory_read_page`) and fails the whole session with a 400 at`tools/list`. The ai-memory server answers requests carrying this flavorwith flat schemas; every other client keeps receiving the upstream schemasunchanged.> **Do not register ai-memory with Kimi's own `mcp add`.** Kimi Code's-> documented command —+> documented command,>> ```bash> kimi mcp add --transport http ai-memory http://127.0.0.1:49374/mcp@@ -1051,7 +1051,7 @@ unchanged.>> writes the plain URL, with no `?flavor=moonshot`. The server then serves> the upstream schemas, Moonshot rejects `memory_read_page`'s root-level-> `anyOf`, and **every model turn fails with a 400** — including turns that+> `anyOf`, and **every model turn fails with a 400**, including turns that> use no tools at all, because tool schemas ship with each request. Use> `ai-memory install-mcp --client kimi-code --apply` instead, which writes> the flavored URL for you.@@ -1068,7 +1068,7 @@ unchanged.> ```>> That serves the restricted dialect on every `tools/list` regardless of the-> `?flavor=` marker, so any strict client that skips the marker is covered —+> `?flavor=` marker, so it covers any strict client that skips the marker,> not just Kimi. A request's marker can only raise the dialect further, never> lower it. Reported in #474.@@ -1082,10 +1082,10 @@ ai-memory install-hooks --agent kimi-code --apply \--server-url "http://homelab:49374" --auth-token "$TOKEN"```-The installed entries cover 10 events — `SessionStart`, `SessionEnd`,+The installed entries cover 10 events (`SessionStart`, `SessionEnd`,`UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`(Kimi Code fires `PostToolUse` on successful calls only), `Stop`,-`SubagentStart`, `SubagentStop`, and `PreCompact` — with a Kimi Code-specific+`SubagentStart`, `SubagentStop`, and `PreCompact`) with a Kimi Code-specificscript bundle /native `ai-memory hook --event … --agent kimi-code` commands (native is thedefault for local installs; the staged scripts under@@ -1377,7 +1377,7 @@ Some model APIs validate MCP tool parameter schemas against a narrower dialectthan JSON Schema and reject the whole `tools/list` with a 400. ai-memory canserve a relaxed dialect per request, via a `?flavor=` query on the MCP URL, orserver-wide via config for clients that cannot carry one. Runtime argument-validation is identical in every dialect — only the advertised schema changes.+validation is identical in every dialect; only the advertised schema changes.| Marker | Config key | What it changes | Who needs it || --- | --- | --- | --- |@@ -1385,10 +1385,10 @@ validation is identical in every dialect — only the advertised schema changes.| `?flavor=bedrock` | `strip_root_combinators` | Drops root-level `anyOf`/`oneOf`/`allOf` | Kiro CLI (Bedrock); appended by `install-mcp` || `?flavor=gemini` (alias `vertex`) | `gemini_safe_schemas` | Drops root-level `anyOf`/`oneOf`/`allOf`, plus nullable unions collapsed to a single `type` + `nullable: true` | Clients that forward schemas verbatim to Gemini/Vertex, e.g. OpenCode on a Vertex model |-Moonshot's validator never resolves `$ref` — any reference, at the root or+Moonshot's validator never resolves `$ref`: any reference, at the root ornested, fails the request with "detected infinite recursion without termination-condition" — while inline combinators such as the nullable union on-`Option<T>` arguments pass. Codex forwards MCP input schemas into Responses+condition". Inline combinators such as the nullable union on+`Option<T>` arguments do pass. Codex forwards MCP input schemas into Responses`tools.function.parameters` verbatim, so it needs the Moonshot marker eventhough it is not Kimi Code. `?flavor=bedrock` and `?flavor=gemini` keep`$defs`/`$ref` pairs, which their upstreams resolve.@@ -1429,7 +1429,7 @@ Unable to submit request because `ai-memory_memory_auto_improve` functionDeclaraWhen using any_of, it must be the only field set.```-The dialect collapses it to `"type": "integer"` plus `nullable: true` — the same+The dialect collapses it to `"type": "integer"` plus `nullable: true`, the samenormalization Gemini CLI performs client-side, which is why Gemini CLI andAntigravity CLI work on Vertex without any marker and do not need this. Reachfor it when a pass-through client fails at `tools/list` with that error.diff --git a/docs/okf.md b/docs/okf.mdindex 09abb51b..3e0da10d 100644--- a/docs/okf.md+++ b/docs/okf.md@@ -3,7 +3,7 @@## What this buys youYour memory is portable beyond ai-memory. Hand a project bundle to a-teammate who runs a *different* OKF-aware tool — or no tool at all —+teammate who runs a *different* OKF-aware tool, or no tool at all,and they read your decisions, gotchas and procedures as ordinarymarkdown with standard metadata:@@ -14,9 +14,9 @@ ai-memory export-okf --project myproject -o myproject-bundle.tar.gzThe receiving side unpacks a directory of `.md` files where every pagedeclares its `type`, provenance (`generated`, `sources`) and freshness(`stale_after`) in the vocabulary Google's Open Knowledge Format-standardized — greppable, Obsidian-openable, importable by anything-OKF-aware. Nothing is held hostage: the export is a validated copy of-the files ai-memory already lives on.+standardized. The files are greppable, open in Obsidian, and import into+anything OKF-aware. Nothing is locked in: the export is a validated copy of+the files ai-memory already stores its memory in.The rest of this page is the design: how conformance is enforced andhow existing stores migrate.@@ -26,7 +26,7 @@ how existing stores migrate.ai-memory's wiki is natively an **Open Knowledge Format** bundle from2.0 on: every page a consumer reads off disk is a conformant OKFconcept file, and a project's wiki directory is a conformant bundle.-"Native" means the wiki files *are* the OKF files — no export step+"Native" means the wiki files *are* the OKF files, so no export stepforks the truth (an `export --okf` / `import --okf` pair still existsfor moving bundles across tools).@@ -44,7 +44,7 @@ families. Summary of what conformance requires:index.md frontmatter allowed) and lists the directory;- reserved names `index.md` / `log.md` follow spec structure whenpresent;-- consumers MUST tolerate unknown keys — all ai-memory extension+- consumers MUST tolerate unknown keys, so all ai-memory extensionfields are spec-safe as-is.## Field mapping@@ -52,12 +52,12 @@ families. Summary of what conformance requires:| OKF key | ai-memory source ||---|---|| `type` (required) | derived from path family + existing frontmatter: `sessions/` → `Session Summary`, `_rules/` → `Rule`, `gotchas/` → `Gotcha`, `decisions/` → `Decision`, `procedures/` → `Procedure`, `concepts/` → `Concept`, `notes/` → `Note`, `runbooks/` → `Runbook`, `_slots/` → `Invariant`/`State` (from `slot_kind`), `_lint/` → `Lint Report`, `_pending/` → `Pending Note`; `kind:` frontmatter (`fact`/`note`/`procedure`/`decision`) wins over the path default when present |-| `title` | not written by `conform_frontmatter` on the general write path — only an explicit `title:` frontmatter value survives there. `export-okf` backfills a missing/empty `title` at export time from `derive_title` (H1 heading, else path stem); the on-disk wiki file is never touched |-| `description` | `conform_frontmatter` fills it from `summary` at write time, when present. `export-okf` additionally falls back to `abstract` when `summary` is absent, but only in the exported copy — a page with neither at write time still has no `description` until it is exported |+| `title` | not written by `conform_frontmatter` on the general write path; only an explicit `title:` frontmatter value survives there. `export-okf` backfills a missing/empty `title` at export time from `derive_title` (H1 heading, else path stem); the on-disk wiki file is never touched |+| `description` | `conform_frontmatter` fills it from `summary` at write time, when present. `export-okf` additionally falls back to `abstract` when `summary` is absent, but only in the exported copy, so a page with neither at write time still has no `description` until it is exported || `tags` | already written || `generated.by` | actor convention: `process:ai-memory/<version>` for the zero-LLM consolidator and system writers; `<provider-model>` (e.g. `openai-compat/qwen3:32b`) for LLM-written pages; `human:<user>` for wiki edits attributed via the watcher || `generated.at` | the page version's `updated_at` |-| `sources` | session provenance: pages already stamped with `session_id`/`agent` get `[{resource: "ai-memory://session/<uuid>", author: "process:<agent>"}]` — the `process:<id>` actor form (§5.1), since a per-harness semantic version isn't honestly derivable |+| `sources` | session provenance: pages already stamped with `session_id`/`agent` get `[{resource: "ai-memory://session/<uuid>", author: "process:<agent>"}]`, the `process:<id>` actor form (§5.1), since a per-harness semantic version can't be reliably derived || `stale_after` | existing `expires_at` (TTL), when present: an RFC 3339 value verbatim, a bare `YYYY-MM-DD` as the end of that day in UTC (`2026-10-01T23:59:59.999999Z`), since OKF timestamps carry an explicit offset || `status` | `deprecated` when TTL-expired but retained; otherwise omitted (spec default `stable`) |@@ -70,13 +70,13 @@ Extension fields kept verbatim (unknown keys are conformant): `tier`,One **project scope directory = one bundle**: the portable unit ofknowledge is a project. Each project dir gets a generated `index.md`(frontmatter `okf_version: "0.2"`, body = directory listing). The-existing `_meta.md` scope manifest is unchanged — it is ai-memory's-identity record; `index.md` is the OKF-facing description. Nothing in+existing `_meta.md` scope manifest is unchanged: it is ai-memory's+identity record, and `index.md` is the OKF-facing description. Nothing inthe current tree writes `index.md`, so that reserved name is free.`log.md` is not adopted: git is the log.The hooks *do* write a raw per-month event ledger at the project root-(`log-YYYY-MM.md` — `## [ts] event | title` lines, no frontmatter). It+(`log-YYYY-MM.md`: `## [ts] event | title` lines, no frontmatter). Itis capture, not a concept file, so the export drops it exactly as itdrops `log.md`, and the conformance gate never sees it (#748). Theexclusion is content-gated, the same way the migration scan's is@@ -100,7 +100,7 @@ Order is fixed; each step gates the next:1. **Proactive backup, first, always.** The migration compresses theentire data dir (wiki, SQLite DB, manifests) to- `~/ai-memory-backup-pre-2.0-<date>.tar.gz` — outside the data dir —+ `~/ai-memory-backup-pre-2.0-<date>.tar.gz` (outside the data dir),verifies the archive is listable and size-sane, and **aborts if thebackup cannot be written or verified**. The archive path is recordedin the wiki meta manifest.@@ -112,7 +112,7 @@ Order is fixed; each step gates the next:3. **Generation marker**: the migration ships as a `WikiMigration`(tracked in the `wiki_migrations` table), and the runner now refusesto open a wiki whose table records a migration this binary does not- know (`NewerWikiFormat`) — the downgrade guard mirroring the DB+ know (`NewerWikiFormat`). This is the downgrade guard mirroring the DBschema-ahead rule. Scope `_meta.md` manifests get their `type` only;they are identity records, not concept pages.4. **Idempotent**: a re-run migrates zero pages.@@ -146,7 +146,7 @@ so any later rewrite of an affected page (a restore, a hand edit, a## Reconcile-delete safety net (opt-in, #929)The watcher's 30s reconcile pass only ever reindexes create/modify events by-default — a page whose file disappears from disk stays indexed until+default: a page whose file disappears from disk stays indexed until`ai-memory delete-page` removes it explicitly. `[maintenance]reconcile_tombstones_deleted_pages` (default `false`) opts into a backgroundsafety net that closes that gap, designed to be safe even though it adds an@@ -155,18 +155,18 @@ automatic mutation to a background loop:- A page's file must be observed missing on **two consecutive** reconcilepasses (not one) before anything happens, and the check is re-verifiedagainst the live filesystem immediately before acting.-- Only pages the walk could ever have returned are eligible — `bootstrap.md`,+- Only pages the walk could ever have returned are eligible. `bootstrap.md`,`_meta.md`, and `_pending/` sidecars are never candidates, and a projectwhose walk hit `NotFound` (a vanished subdirectory, a whole projectdirectory gone mid-pass) contributes no "missing" evidence for that pass.`sessions/*.md` pages are excluded too, for an unrelated reason: asame-workspace `move-session` re-home can leave a correct DB row with nofile at its new scope (a separate, pre-existing bug in `move-session`'s- file relocation — tracked as a follow-up, not fixed here). This mechanism+ file relocation, tracked as a follow-up and not fixed here). This mechanismis meant for OKF-imported content pages only.- A circuit breaker refuses to act on a whole scope when more than `max(3,50%)` of its candidate pages look missing in one pass, OR when a- non-partial walk finds nothing at all in a scope that has candidates — the+ non-partial walk finds nothing at all in a scope that has candidates. Thelatter catches the "directory exists but came back empty" mount-failuresignature for scopes too small to ever trip the percentage math. Eithershape is far more likely a walk/mount problem (an unmounted volume, a git@@ -174,16 +174,16 @@ automatic mutation to a background loop:- The action itself is a soft tombstone (`is_latest = 0` + `superseded_at`),the same row shape decay eviction already uses, and is picked up by theexact same aged-tombstone hard-delete sweep decay eviction uses- (`hard_delete_after_days`, tier/pin-agnostic) — it is NOT exempt from that+ (`hard_delete_after_days`, tier/pin-agnostic); it is NOT exempt from thatsweep. The precise guarantee: **a reconcile tombstone is never itselfdestroyed while its chain has no successor; if the file returns, the newversion re-links to the tombstoned chain instead of starting fresh, sonothing is orphaned for the 180-day sweep to destroy.** Concretely, a freshwrite at a tombstoned path (`upsert_page_in_tx`) supersedes the tombstonedrow via `supersedes` and clears its `superseded_at`, turning it into an- ordinary, protected supersession-chain member — the same mechanism that+ ordinary, protected supersession-chain member. That is the same mechanism thatalready keeps normal edit history off that sweep. It also never dispatches- the BLOCKING admission gate (nothing gets to refuse it — this is a+ the BLOCKING admission gate (nothing gets to refuse it, because this is abackground safety net reacting to an already-vanished file, not auser-initiated delete) and never touches the filesystem (there is nothingto write; the file is already gone); it DOES fire-and-forget any@@ -211,7 +211,7 @@ automatic mutation to a background loop:native, so unpacking a bundle's concept files into a project's wikidirectory and letting the watcher (or `reindex`) ingest them IS theimport path. Overwriting an already-imported concept file gets its new- version embedded the same way a brand-new file does — no manual+ version embedded the same way a brand-new file does, with no manual`ai-memory embed` needed. Deleting one does not remove it from the index bydefault: the watcher only reconciles create/modify events, so a deletedconcept file needs an explicit `ai-memory delete-page` unless the opt-indiff --git a/docs/prior-art-implementation-findings.md b/docs/prior-art-implementation-findings.mdindex 3fc296b6..15c988f6 100644--- a/docs/prior-art-implementation-findings.md+++ b/docs/prior-art-implementation-findings.md@@ -14,11 +14,11 @@ durability, opt-in LLM consolidation, structured JSON outputs, typedhandoffs, versioned supersession, per-project UUID isolation, and anagentmemory-style retention formula.-The remaining high-value improvements were not a rewrite. They were-mostly lifecycle and retrieval layers on top of the solid base: small+The remaining high-value improvements did not need a rewrite. They were+mostly lifecycle and retrieval layers on top of the existing base: smalleditable memory slots, scheduled maintenance, first-class graph/linkretrieval, bounded raw/verbatim fallback recall, diagnostics, and real-retrieval checks. The most important caution remains keeping the current+retrieval checks. The main caution is still to keep the currentsubstrate simple. Do not copy agentmemory's sidecar surface, cognee'smulti-store orchestration, basic-memory's manual write-note workflow, orMemPalace's verbatim-everything storage model.@@ -205,9 +205,9 @@ enough for the expected corpus size.### P1: Add Bounded Raw/Verbatim Fallback Recall-MemPalace's strongest useful idea is not its storage stack. It is the-evidence that raw text recall can recover details that compiled summaries-drop. ai-memory reserves `raw/`; the implemented fallback searches the+The most useful thing in MemPalace is the evidence that raw text recall+can recover details that compiled summaries drop; its storage stack is not+worth taking. ai-memory reserves `raw/`; the implemented fallback searches thedurable `observations` table through `observations_fts`.Recommended shape:@@ -219,8 +219,8 @@ Recommended shape:| retention budget | Prevent MemPalace-style bloat. || privacy boundary | Use the same sanitizer before raw text becomes durable/searchable. |-This gives ai-memory the best of both philosophies: compile first, but-keep a bounded escape hatch for exact details.+This lets ai-memory compile first while keeping a bounded escape hatch+for exact details.### P1: Add Diagnostics And Safe Heal Paths@@ -259,8 +259,8 @@ Recommended benchmark matrix:| FTS5 + entity + vector + graph RRF | Current embedding-enabled hybrid path. || compiled wiki + raw fallback | Current MemPalace-inspired miss path. |-Borrow MemPalace's transparency, not its headline-chasing. Public claims-should have tests or should not be claims.+Borrow MemPalace's transparency about benchmarks and skip its+headline-chasing. Public claims should be backed by tests or not made.### P2: Consider Feedback/Reinforcement Beyond Access Countsdiff --git a/docs/research-2026-landscape.md b/docs/research-2026-landscape.mdindex b9bcfb0f..02c1a30b 100644--- a/docs/research-2026-landscape.md+++ b/docs/research-2026-landscape.md@@ -4,7 +4,7 @@> `research-basic-memory.md`, `research-cognee.md`,> `research-karpathy-llm-wiki.md`, and the `issues-*.md` tracker mining).> Same lens as then: what the competition does, what is worth borrowing,-> what to deliberately avoid. Analysis only - no implementation decisions+> what to deliberately avoid. This is analysis only: no implementation decisions> are made here, and none of the recommendations below imply drastic> change. Sources at the end; every load-bearing claim was checked against> a live page in September 2026, not remembered.@@ -15,8 +15,8 @@ On June 12, 2026, Google Cloud published the **Open Knowledge Format(OKF) v0.1**: organizational knowledge as a plain directory of markdownfiles with YAML frontmatter, one concept per file, a single requiredfrontmatter field (`type`), no SDK, no runtime, vendor-neutral. It is an-explicit formalization of Karpathy's "LLM wiki" - the same gist our-project was built from - and it is already an ecosystem signal: new+explicit formalization of Karpathy's "LLM wiki" (the same gist our+project was built from), and it is already an ecosystem signal: newmemory servers advertise themselves as "OKF-backed", and the format ispositioned as the interop layer that makes agent memory portable acrosstools.@@ -31,13 +31,13 @@ The second validation came from an unexpected direction: **Letta**agents post-trained for iterative file search perform well againstspecialized memory systems (74.0% on LOCOMO with plain files). Whateverone thinks of the framing, the leaders of the "memory OS" camp conceding-ground to file-first memory supports the substrate we chose - files as-source of truth, derived indexes for retrieval - which is *both* halves+ground to file-first memory supports the substrate we chose: files as+source of truth and derived indexes for retrieval, *both* halvesrather than either alone.## 2. How the original research subjects evolved-**agentmemory (rohitg00)** - actively maintained and maturing along the+**agentmemory (rohitg00)** is actively maintained and maturing along thetrajectory the May report predicted. Notable since then: a real-workloadbenchmark ("coding-agent-life-v1", 635 requests / 888K tokens / 35 hours,R@5 = 0.967 for the hybrid retriever), `AGENT_ID` multi-agent isolation@@ -46,17 +46,17 @@ premium model is configured for compression. Still on the iii-engine +JSON-in-KV substrate the May report identified as its structuralconstraint. The 53-tool surface did not shrink.-**basic-memory** - alive, same positioning (structured markdown both+**basic-memory** is alive, with the same positioning (structured markdown bothhumans and LLMs edit; local files). No architectural surprises. Itsniche overlaps most with OKF, which may absorb its differentiation.-**cognee** - has moved decisively into content-led growth ("best memory+**cognee** has moved into content-led growth ("best memoryframework" listicles on its own blog rank for every comparison query)and now advertises 14 retrieval modes and the broadest integrationmatrix. Technically still the triple-store (relational + vector + graph)ECL pipeline the May report described; still heavy for a homelab.-**mempalace** - the cautionary tale of the year. ~47K stars within two+**mempalace** is the cautionary tale of the year. It reached ~47K stars within twoweeks of its April 2026 launch on the strength of a claimed 96.6% R@5 onLongMemEval; then an independent audit (its issue #29, corroborated by`mcp-memory-service`'s issue #27 analysis and a critical-analysis paper,@@ -80,11 +80,11 @@ The market has consolidated into recognizable camps:| User-modeling / theory-of-mind | **Honcho** (Plastic Labs) | Memory as a *reasoning* problem: derive what each "peer" knows/believes about another over time; model the human, not the project (see below) || **File-first wiki memory** | **us**, basic-memory, OKF, Letta's filesystem result, mempalace (nominally) | Markdown source of truth, derived indexes, human-editable || File-first wiki (LLM-leaning) | **memU**, **EverOS** | Markdown source of truth + derived vector/SQLite(+LanceDB) indexes, but LLM-required for the capture/distill flow; skill-distillation and offline consolidation (see below) |-| Self-hosted coding-agent store | **Engram** | Single Go binary, SQLite+FTS5, MCP, project scope, session-summary handoffs — a structured-row sibling captured via agent MCP calls, not lifecycle hooks (see below) |-| Governed multi-agent / fleet memory | **Caura** | Shared fleet memory with visibility scopes, trust tiers, audit, governance on Postgres+pgvector — org-scale, not project-scale (see below) |+| Self-hosted coding-agent store | **Engram** | Single Go binary, SQLite+FTS5, MCP, project scope, session-summary handoffs; a structured-row sibling captured via agent MCP calls, not lifecycle hooks (see below) |+| Governed multi-agent / fleet memory | **Caura** | Shared fleet memory with visibility scopes, trust tiers, audit, governance on Postgres+pgvector; org-scale, not project-scale (see below) || Shared memory server (proxy fan-in) | **TencentDB Agent Memory** | One proxy in front of many harnesses distilling Chat Memory / Skill / Wiki / CodeGraph; proxy interception, not MCP/hooks (see below) |-| Code intelligence | **DeusData/codebase-memory-mcp** (~42K stars) | Index the *codebase* (162 languages, tree-sitter → SQLite graph, static C binary) rather than the *session* - adjacent, not competing: it remembers what the code is, not what you did (see `research-codebase-memory-mcp.md`) |-| Agent-harness OS | **ECC** (~247K stars), plus the skills/agents-pack ecosystem | Install a whole plan→test→implement→review→**remember**→improve loop into the agent; memory is one thin pillar ("optimize the context window, persist everything else"), deliberately kept as *context, not policy* - adjacent, not competing (see `research-ecc.md`) |+| Code intelligence | **DeusData/codebase-memory-mcp** (~42K stars) | Index the *codebase* (162 languages, tree-sitter → SQLite graph, static C binary) rather than the *session*. Adjacent, not competing: it remembers what the code is, not what you did (see `research-codebase-memory-mcp.md`) |+| Agent-harness OS | **ECC** (~247K stars), plus the skills/agents-pack ecosystem | Install a whole plan→test→implement→review→**remember**→improve loop into the agent; memory is one thin pillar ("optimize the context window, persist everything else"), deliberately kept as *context, not policy*. Adjacent, not competing (see `research-ecc.md`) |**Closest architectural sibling: `doobidoo/mcp-memory-service`** (1.9Kstars, 3.2K commits, active through August 2026). It is what we would be@@ -96,14 +96,14 @@ derivation" over typed edges), a **typed knowledge graph**(`causes` / `fixes` / `contradicts` edges), multi-backend sync(local-first with optional Cloudflare replication), and inter-agentmessaging implemented as tagged memories on the shared pool. Its issue-tracker repeats patterns from our own history - v11.10.0 fixed+tracker repeats patterns from our own history: v11.10.0 fixedconsolidation time horizons that *silently ignored their configuredwindow*, the same class of quiet-lifecycle bug our `#526`/`#528` workaddressed with observable outcomes. Published honest numbers: 80.4% R@5on LongMemEval turn-level, 86.0% session-level. **Where we now stand-(2.4):** its consolidation set — type-dependent TTL (365/180/90/30),+(2.4):** its consolidation set is type-dependent TTL (365/180/90/30),extractive compression, DBSCAN adaptive-eps clustering, access/connection-boosts, and 0.4–0.75-band contradiction detection — is the direct+boosts, and 0.4–0.75-band contradiction detection. That set is the directgrounding for the 2.4 memory-aging program([`design-memory-aging.md`](design-memory-aging.md)), which now ships eachat parity but **zero-LLM by default, reversible** (supersede-not-delete +@@ -116,45 +116,45 @@ zero-LLM default path and evicts nothing on upgrade.**Platform development: Claude Code native "auto memory"** shippeddefault-on (v2.1.59): the agent keeps its own `MEMORY.md` plus topicfiles per project, loading the first 200 lines each session. Its-documented limits are precisely our differentiators - machine-local+documented limits are our differentiators: machine-localwith **no sync**, single-agent (nothing carries to Codex/Cursor/others),repo-scoped, no search beyond reading files, no capture of toollifecycle, no team story. Two readings, both true: the basic solouse case ("remember my project between sessions on this laptop") isbeing absorbed by the platforms; and the platforms are training usersto *expect* persistent memory, which makes the cross-machine,-cross-agent, multi-user version - what v1.39.0 hardened - the durable+cross-agent, multi-user version (what v1.39.0 hardened) the durablevalue. Native memory is the funnel, not the competitor.**Best-funded new entrant: `vectorize-io/hindsight`** (~23.5K stars,MIT, a company behind it, a preprint paper arXiv:2512.12818, and aLongMemEval claim of 91.4%). It is the most serious competitor in this-series, and it is useful precisely because it *agrees with our core+series, and it is useful because it *agrees with our corebet from the opposite substrate*: Hindsight is Postgres/pgvector-primary-and LLM-required, yet its top memory tier is **"mental models" - living+and LLM-required, yet its top memory tier is **"mental models": livingmarkdown pages of settled knowledge that a background processcontinuously rewrites as the bank learns**, which an agent "boots" frominstead of rediscovering context each session. That is our `wiki/` +auto-improve loop under another name, arrived at independently and backed-by a paper - the strongest external validation of pages-over-facts in+by a paper. It is the strongest external validation of pages-over-facts inthis whole research series. Two more things to carry forward: itsconsolidation is **belief-strength, not binary supersession** (evidence-backed observations with quotes + a proof count; new evidencestrengthens/weakens/extends rather than replaces), a richer model thanours; and its **"bank" = strict per-(user|agent|project) isolation, nocross-bank leakage** is the deliberate *opposite* of our shared-within-a--project invariant (#16) - and the natural prior art for issue #708+project invariant (#16), and the natural prior art for issue #708(per-project authorization) and #709 (project identity), where the designshould layer a bank-like boundary *above* sharing rather than replacingit. Read skeptically where it earns it: the "independently reproduced"LongMemEval number is from the *co-developing* labs (two of seven authorsare Virginia Tech Sanghani faculty; the Post is a named collaborator), it-is a preprint, and it reports accuracy rather than the R@5 others quote --still the most credible benchmark claim here (a paper with per-category+is a preprint, and it reports accuracy rather than the R@5 others quote.+It is still the most credible benchmark claim here (a paper with per-categorysub-scores, gains concentrated where structured temporal memory shouldhelp), and a reminder the serious players now publish numbers. **Where we-now stand (2.4):** the two ideas flagged to carry forward — belief-strength-over binary supersession, and the background rewrite loop — now ship, as+now stand (2.4):** the two ideas flagged to carry forward (belief-strength+over binary supersession, and the background rewrite loop) now ship, asopt-in layers over the zero-LLM core, per[`design-hindsight-borrowings.md`](design-hindsight-borrowings.md) §3 and[`design-memory-aging.md`](design-memory-aging.md) B1–B4. Belief-strength is@@ -163,8 +163,8 @@ live `contradicts`, capped) exposed inertly in `explain`/`status` andfoldable into ranking behind a **default-0.0, R2-gated** weight; the"dream" pass is an idle-scheduled, cancel-on-activity, surprisal-first LLMrewrite of cold clusters that is **off by default and never deletes a-source**. We designed *against* Hindsight's own documented failure —-belief *entrenchment* (raw proof-count pins a wrong page) — with+source**. We designed *against* Hindsight's own documented failure,+belief *entrenchment* (raw proof-count pins a wrong page), withbreadth-not-count weighting, a confidence cap, and supersession alwayswinning over evidence. Honest caveat: no R2 delta has been run, so this isparity of *mechanism*, not a measured accuracy win. Full analysis in@@ -176,24 +176,24 @@ papers incl. **VikingMem** at VLDB 2026, arXiv:2605.29640). Positioned as a"self-evolving context database" that unifies memory + RAG + skills. It isLLM-**required** (a VLM for extraction/compilation plus an embedding model)over a vector store fronted by a `viking://` virtual filesystem, so it sits-in the opposite corner from our zero-LLM, file-first default — and, like+in the opposite corner from our zero-LLM, file-first default. LikeHindsight, it validates our substrate from there: memory isdocument/directory-scoped, not atomic facts, and a background pass(*commit session → extract → compare candidates for create/merge/skip*, andoptional VikingBot "compile" into wikis/KGs) is our consolidation +-auto-improve loop under other names. Two ideas are genuinely worth carrying+auto-improve loop under other names. Two ideas are worth carryingforward. First, **progressive-disclosure tiers**: every memory is loadableat **L0 (one-sentence abstract, for relevance checks)**, **L1 (overview, for-planning)**, or **L2 (full original, read only when needed)** — the reported+planning)**, or **L2 (full original, read only when needed)**. The reported34-91% input-token reduction (LoCoMo) is almost entirely this deferral, andit maps directly onto work we already have (V61 abstract embeddings, the-session brief) rather than a new architecture — and 2.4's **extractive+session brief) rather than a new architecture. 2.4's **extractivetier-down** (A2, [`design-memory-aging.md`](design-memory-aging.md)) nowpersists exactly this shape for cold episodic pages: an L0 abstract, an L1summary, and an L2 keep-token set, with the full prose one supersession-restore away. Second, **directory-scopedretrieval** (a "TrieHI" prefix-tree vector index that narrows a query to a-path subtree before ranking) — a cheaper cousin of our per-project scoping,+path subtree before ranking), a cheaper cousin of our per-project scoping,one level down at the `_rules/` / `norms/` path prefix. Read the numberswith the same skepticism the rest of this report earns: the LoCoMo lifts(24->82%, 33->83%, 57->80%) are **in-house** (Volcengine) against@@ -210,7 +210,7 @@ repo, ~$2.6-3M seed from Susa/Browder/SF1.vc plus angels incl. Jeff Dean,Cloudflare's CTO, and Logan Kilpatrick; founder Dhravya Shah). Positioned as"context infrastructure for AI agents": a **hosted memory API** (the paid`api.supermemory.ai`) with an MIT self-hostable local binary as the on-ramp.-This is the entrant our own docs most **mislabeled** - it is *not* a Mem0-style+This is the entrant our own docs most **mislabeled**: it is *not* a Mem0-styleatomic fact extractor. It is a **hybrid**: every ingested item ischunked+embedded for RAG **and** run through an LLM "dreaming" pass thatextracts atomic facts into a **temporal vector-graph** (Updates / Extends /@@ -221,9 +221,9 @@ turn, so even the "LLM-per-turn" half of the old label is wrong (that mode isopt-in). Like the others it validates our bets from the opposite corner: thebatch "dream" pass is our consolidation ("compile, not retrieve") under anothername, and supersede-don't-delete is our page-supersession chain. Where it-genuinely leads is **ingestion breadth** - managed connectors (Drive, Gmail,+leads is **ingestion breadth**: managed connectors (Drive, Gmail,Notion, OneDrive, S3, GitHub, web crawler), multimodal PDF/image/audio, and-metadata + `containerTag` query filters, plus a first-class user profile - but+metadata + `containerTag` query filters, plus a first-class user profile. Butevery one of those is **cloud-only and LLM-required**; the self-hosted binary(embedded graph store, local `bge-base` embeddings, offline) explicitly "lacksconnectors and the proprietary extraction models." It sits opposite us on every@@ -234,19 +234,19 @@ also not really in our lane: it is a general **memory-API for apps and userpersonalization** whose coding-agent plugins (Claude Code, Cursor, Codex,OpenCode) capture by **turn-batch polling**, not OS lifecycle hooks, with nocross-harness handoff, multi-user page-sharing, or per-project 3-tuple isolation-model - the coding-agent-continuity primitives are exactly what we build and it+model. Those coding-agent-continuity primitives are exactly what we build and itdoes not. Read the numbers with the standard skepticism: "95% LongMemEval_s atRecall@15 with aggregation, ~720 tokens, sub-300ms p50, first on LoCoMo" are all-**vendor self-reported** - though their **MemoryBench** harness and the+**vendor self-reported**, though their **MemoryBench** harness and theaccuracy / latency / context-tokens "MemScore" triple are open and worthborrowing (see R8). Per the research-doc convention, Supermemory has nostandalone deep-dive; this section is its record.**Solo-built Supermemory-style hosted API: `liquidlm.com`** (**LiquidLM**,-closed-source cloud SaaS, no funding — a single independent maker, Carlos Souza).+closed-source cloud SaaS, no funding, built by a single independent maker, Carlos Souza).Its own tagline is "persistent AI agent memory and RAG as a service." It is the-same *camp* as Supermemory — a proprietary hosted memory API with entity/-relationship extraction, temporal metadata, and an MCP surface on top — but a+same *camp* as Supermemory (a proprietary hosted memory API with entity/+relationship extraction, temporal metadata, and an MCP surface on top), but asmaller, indie, individual-priced take on it (Free / $20 Pro / $200 Ultra,usage-based by ingestion volume). You ingest files/notes/links/media into cloud**"Vaults"**; it extracts entities, relationships, timestamps, and **staleness/@@ -254,13 +254,13 @@ usage-based by ingestion volume). You ingest files/notes/links/media into cloudgrounded, cited chat. It is on **every axis we deliberately chose against**: the**vault is an opaque hosted store** (no git, no markdown, no self-host, nothing to`grep`/diff), **LLM is intrinsic and not optional** (Gemini-class extraction/-embeddings — no zero-LLM mode), and the memory engine is **closed-source** (the+embeddings, no zero-LLM mode), and the memory engine is **closed-source** (theonly open artifact is the MIT npm client `@liquidlm/cli`, v0.1.5 published-2026-09-17; the GitHub `cli` repo is archived and empty). Where it is genuinely+2026-09-17; the GitHub `cli` repo is archived and empty). Where it isinteresting is **breadth of ingestion and a clean MCP tool surface**: heavymultimodal capture (video/audio/image/PDF/Office, auto-transcription, a`yt-dlp`-fetch-locally pattern), a GitHub repo-sync connector, and eight native-MCP tools worth studying by name — `put/get/list/search_knowledge`,+MCP tools worth studying by name: `put/get/list/search_knowledge`,`list_entities`, `get_related`, **`follow_references`** (walk the citation graph),**`pin_knowledge`** (standing context surfaced *before* search), and`forget_knowledge`. Tested harnesses: Claude Code, ChatGPT, Codex CLI, OpenCode@@ -268,7 +268,7 @@ over a hosted MCP endpoint (OAuth or scoped PAT). **No retrieval benchmarks** arpublished (only ROI marketing). It is **not in our lane and a weak migrationtarget either way**: it captures by *explicit upload/sync* into a general "secondbrain," where we capture *automatically via lifecycle hooks* compiled into-per-project coding pages you own — different job, different buyer. Two ideas are+per-project coding pages you own. It is a different job for a different buyer. Two ideas areworth borrowing conceptually (never the substrate): the explicit **`pin_knowledge`= "seen before they search"** contract over our existing `pinned` pages, and**`follow_references`/`get_related` as first-class graph-walk MCP tools** over the@@ -279,7 +279,7 @@ LiquidLM has no standalone deep-dive; this section is its record.Five projects flagged in issue #810, each researched from its own repo/README(and, where the name could mislead, the LICENSE and the metadata endpoint) rather-than from a name search — the failure mode this series has been burned by before.+than from a name search, a failure mode that has burned this series before.None displaces the camp taxonomy; they slot into it, and two are close enough tobe honest migration conversations.@@ -297,7 +297,7 @@ choices that define our substrate: capture is **agent-driven** (the agent callscapture automatically), and **SQLite is the source of truth** (git-syncscompressed chunks, not a hand-editable git-markdown wiki you can `grep`/diff).It is a fact-row/structured-store sibling in the mold of mcp-memory-service, but-Go and MCP-capture rather than hook-capture — the honest "closest self-hosted+Go and MCP-capture rather than hook-capture, which makes it the "closest self-hostedcoding-agent store" newcomer. **No retrieval benchmark is published.** Per theresearch-doc convention, Engram has no standalone deep-dive; this section is itsrecord.@@ -307,11 +307,11 @@ Apache-2.0, Python 3.12+, commit 2026-09-09, release v1.3.1). Architecturally thclosest of the five to our bet: a **local-first memory runtime** with **canonicalMarkdown as the source of truth** ("readable, editable, diffable, andGit-versioned") over derived **SQLite + LanceDB** indexes, direct file edits-cascading through watchers — the same files-as-truth + derived-index split we+cascading through watchers. That is the same files-as-truth + derived-index split wechose. It adds dual first-class tracks (a user `episodes/profile` and an agent`cases/skills`), an editable **Knowledge Wiki** with taxonomy + CRUD APIs, and-**offline memory evolution** that merges episode clusters and refines profiles —-our consolidation/auto-improve loop under other names. It validates the substrate,+**offline memory evolution** that merges episode clusters and refines profiles,+which is our consolidation/auto-improve loop under other names. It validates the substrate,but from the LLM-leaning corner: the minimal tier still **requires an LLM for thecore flow** (embedding/reranking optional, OpenRouter the default; a zero-LLMdemo exists but is not the operating default), it is a Python stack rather than a@@ -322,17 +322,17 @@ standalone deep-dive; this section is its record.**LLM-wiki with skill distillation: `NevaMind-AI/memU`** (~14.4K stars,Apache-2.0, Python, commit 2026-09-21; last tagged release v1.5.1 from 2026-03-23,so releases lag active code). Positioned as a **shared LLM wiki across sessions,-agents and devices** whose signature is **automatic skill distillation** —-converting agent session history into reusable **Markdown** workflows — plus+agents and devices** whose signature is **automatic skill distillation**+(converting agent session history into reusable **Markdown** workflows), plusscheduled memorization and standing retrieval-instruction injection into hostinstruction files. Storage is SQLite (default) or Postgres+pgvector withbrute-force-cosine or pgvector search and pluggable embedding providers(OpenAI/Jina/Voyage/Doubao/OpenRouter); the core logic is advertised at ~500 LOC.It is **file-first-adjacent** (Markdown output) but **LLM-leaning**: the hostagent does the judgment/synthesis (the MemoryService itself makes no LLM calls, so-the *product* still depends on a provider), there is **no MCP** — it ships as+the *product* still depends on a provider), there is **no MCP** (it ships assidecar binaries that patch host instruction files, with adapters for-Cursor/Claude Code/Codex/OpenClaw/Hermes/WorkBuddy — and a managed cloud exists at+Cursor/Claude Code/Codex/OpenClaw/Hermes/WorkBuddy), and a managed cloud exists atmemu.so. **No named benchmark** (no LoCoMo/LongMemEval figure) is in the README.Its skill-distillation-into-Markdown is the idea worth noting against ourexperience pass. Per the research-doc convention, memU has no standalone@@ -340,19 +340,19 @@ deep-dive; this section is its record.**Governed fleet memory (different buyer): `caura-ai/caura`** (~0.5K stars,Apache-2.0 core + managed platform at caura.ai, Python/FastAPI, commit-2026-09-22, release backend-v3.17.2). Caura is a genuinely new camp for this+2026-09-22, release backend-v3.17.2). Caura is a new camp for thisreport: **governed shared memory for multi-agent fleets**. On **PostgreSQL 16 +pgvector** (Redis optional) it layers row-level multi-tenant isolation, threevisibility scopes (`scope_agent`/`scope_team`/`scope_org`), **four trust tiers**governing cross-fleet read/write/delete, a full **audit trail** ("every write,delete, and transition logged"), automatic PII flagging, an auto-extracted-knowledge graph, and contradiction detection with supersession — a native MCP+knowledge graph, and contradiction detection with supersession, plus a native MCPsurface at `/mcp` (12 tools) for Claude Desktop/Code, Cursor, Windsurf. Itsbenchmark claims are **self-reported** and, per its own README, single-agentproxies for a fleet product it says those benchmarks "can't measure": **LoCoMo77.6% accuracy / 96.6% token savings** and **LongMemEval 92.2% accuracy / 79.2%token savings** (with a "23 ms p50 · 27 ms p95" latency figure and a stated-production deployment of "300+ AI agents" at eToro — vendor-reported, not+production deployment of "300+ AI agents" at eToro; vendor-reported, notindependently verified). It sits opposite us on substrate (opaque Postgres, LLMextraction, hosted-leaning) and orthogonal on goal: **org-scale fleet governance**rather than one project's git-backed wiki. Its **trust-tier governance is a real@@ -362,12 +362,12 @@ convention, Caura has no standalone deep-dive; this section is its record.**Proxy fan-in memory server (misleading name): `TencentCloud/TencentDB-Agent-Memory`** (~27.2K stars, MIT, Node/TypeScript, commit 2026-09-22, release-v2.0.1). Despite the "TencentDB" name it **requires no Tencent database product**-— storage is **SQLite by default** (an experimental, off-by-default MongoDB-backend exists) — so the name-search trap here would be to file it as a managed+v2.0.1). Despite the "TencentDB" name it **requires no Tencent database product**:+storage is **SQLite by default** (an experimental, off-by-default MongoDB+backend exists), so the name-search trap here would be to file it as a managedcloud DB feature; it is not. It is a **team-level memory hub** that distills-conversations, documents and code into four reusable assets — **Chat Memory,-Skill, Wiki, CodeGraph** — and its distinctive mechanism is a **proxy fan-in**: a+conversations, documents and code into four reusable assets (**Chat Memory,+Skill, Wiki, CodeGraph**), and its distinctive mechanism is a **proxy fan-in**: athree-service deployment (Memory Core + Memory Hub + Proxy) where agents pointtheir API **base URL** at the proxy ("One Proxy, unchanged protocol, zero-codeintegration"), so capture is **proxy interception, not MCP or OS lifecycle@@ -384,16 +384,16 @@ Honcho is the archetype of a **new camp** this report had no bucket for:**user-modeling / theory-of-mind memory**. Its unit of memory is a **"peer"**(any entity that "persists but changes over time — users, agents, objects") andits differentiator is treating memory as **"a reasoning problem, not a retrieval-problem"** — it models *what one peer knows and believes about another* over+problem"**: it models *what one peer knows and believes about another* overtime. The substrate is the opposite of ours on every axis we chose:**PostgreSQL is the source of truth** (Postgres FTS/GIN + HNSW vectors, Redis-cache, pluggable LanceDB/Turbopuffer — **no git, no markdown, nothing to `grep`+cache, pluggable LanceDB/Turbopuffer; **no git, no markdown, nothing to `grep`or diff**), it is **LLM-required** (a **Deriver** does one structured-output LLMcall per message batch; a scheduled **Dreamer** runs surprisal-prioritized-"dream-time" consolidation into premise→conclusion reasoning trees — no zero-LLM+"dream-time" consolidation into premise→conclusion reasoning trees, with no zero-LLMpath), and it runs as a **multi-service stack** (FastAPI API + async worker +Postgres + Redis), cloud-leaning with a self-hostable core. Its flagship is the-**Dialectic endpoint** (`peer.chat()`): a natural-language *oracle* — you ask a+**Dialectic endpoint** (`peer.chat()`): a natural-language *oracle*: you ask aquestion about a peer and a synchronous tool-using agent (`search_memory`,`grep_messages`, `get_reasoning_chain`, temporal search, five reasoning tiers)synthesizes an answer rather than returning raw hits. Benchmarks are strong but@@ -401,42 +401,42 @@ synthesizes an answer rather than returning raw hits. Benchmarks are strong but4.5) / 92.6% (Gemini 3 Pro), LoCoMo 89.9%, "median 5% of context tokens used."It now ships coding-agent front-ends too (Claude Code/Codex/Cursor/OpenCodeplugins + an **MCP server** with exactly three tools: `honcho_search`,-`honcho_chat`, `honcho_remember`), so it **collides with us on the shelf** — but-the thing remembered is fundamentally different: **Honcho remembers the *user*;+`honcho_chat`, `honcho_remember`), so it **collides with us on the shelf**, but+the thing remembered is different: **Honcho remembers the *user*;ai-memory remembers the *project*.** A coding team wanting cross-harness projectcontinuity would not switch to it (opaque DB, LLM-mandatory, user-centric,multi-service), and an app builder wanting end-user personalization would not use-us — **adjacent, not a migration target either way**. Two ideas are worth+us. It is **adjacent, not a migration target either way**. Two ideas are worthcarrying forward as *optional LLM layers over* our zero-LLM core, neverrequirements: the **dialectic/oracle query** (ask-a-question → synthesizedanswer, which maps onto our retrieval as an opt-in LLM step) and the**reasoning-tier ladder** (minimal→max reasoning per query as a cleancost/quality knob). **Both now ship on 2.4** as opt-in, off-by-default LLMlayers (`memory_query answer=true` #782; `reasoning: {minimal..max}` #783),-and the Dreamer's *scheduling shape* — surprisal-first ordering, idle-trigger, cancel-on-activity — is the grounding for 2.4's opt-in "dream"+and the Dreamer's *scheduling shape* (surprisal-first ordering, idle+trigger, cancel-on-activity) is the grounding for 2.4's opt-in "dream"consolidation pass (#816, [`design-memory-aging.md`](design-memory-aging.md)B3/B4), which stays off by default and never deletes a source. Deliberately**reject** the rest as off-mission: LLM-mandatoryingestion, opaque-Postgres-as-truth, the Postgres+Redis+worker operational-weight, and the heavy theory-of-mind engine itself — a coding agent needs project+weight, and the heavy theory-of-mind engine itself. A coding agent needs projectfacts, decisions, and conventions, not a psychological model of the developer(the lightweight "standing user preferences" slice we already have via globalscope is enough). Positioning note: preempt the inevitable "but Honcho scores 90%on LongMemEval" by clarifying those are *user-recall* benchmarks on chat-transcripts, not *coding-project* recall — a different task we are not competing+transcripts, not *coding-project* recall, a different task we are not competingon. Per the research-doc convention, Honcho has no standalone deep-dive; thissection is its record.### Popularity and maintenance signal (as of 2026-09-18)-None of the tracked competitors is stale or abandoned — every repo below had a+None of the tracked competitors is stale or abandoned: every repo below had acommit within the last ~10 days and grades **ACTIVE**. Star counts are GitHub'sraw figures (approximate; the biggest few were sanity-checked against priorresearch). This is a healthy, crowded, fast-moving field: "we picked a deadspace" is not a claim we can make, and none of these can be dismissed as-unmaintained. (The five issue-#810 new-entrant rows — TencentDB Agent Memory,-memU, EverOS, Engram, Caura — were verified against the GitHub metadata endpoint+unmaintained. (The five issue-#810 new-entrant rows, TencentDB Agent Memory,+memU, EverOS, Engram and Caura, were verified against the GitHub metadata endpointon 2026-09-22.)| Project | Stars (~) | Last commit | Latest release | Status |@@ -460,47 +460,47 @@ on 2026-09-22.)| Caura | 0.5k | 2026-09-22 | backend-v3.17.2 (2026-09-19) | ACTIVE || LiquidLM | n/a (closed) | n/a (engine closed) | `@liquidlm/cli` 0.1.5 (2026-09-17) | ACTIVE (young, pre-1.0, solo) |-Reading it honestly: raw stars track **funding and app-developer reach**, not-coding-agent fitness — the leaders (Mem0, OpenViking, the KG/cloud entrants) are+Raw stars track **funding and app-developer reach**, not+coding-agent fitness. The leaders (Mem0, OpenViking, the KG/cloud entrants) arethe app-personalization and hosted-context players, a different buyer from ours(see §5 and [`competitive-parity.md`](competitive-parity.md)). Our truearchitectural siblings sit lower on the star curve (basic-memory ~4.0k,mcp-memory-service ~2.0k) precisely because the self-hosted, file-first,-coding-continuity niche is smaller and less VC-amplified — that is the segment we+coding-continuity niche is smaller and less VC-amplified. That is the segment welead, not the whole chart. Two mild flags: Letta ships commits actively but itslast *tagged* release is from May 2026 (formal releases lag the code), andLangMem/Honcho publish no GitHub *releases* (PyPI/tag-only versioning); and-LiquidLM is **closed-source**, so it has no repo signal at all — its only public,+LiquidLM is **closed-source**, so it has no repo signal at all; its only public,open artifact is the MIT npm client `@liquidlm/cli` (v0.1.5, 2026-09-17), which iswhat dates it as active but young.## 4. Research developments worth knowing- **"Rethinking How to Remember: Beyond Atomic Facts in Lifelong LLM- Agent Memory" (TriMem, arXiv:2605.19952)** - argues atomic-fact stores+ Agent Memory" (TriMem, arXiv:2605.19952)** argues that atomic-fact storeslose the relational/causal context agents need, proposes adocument/page/narrative hierarchy, and shows it outperformingfact-baselines on retrieval and multi-step reasoning. This is direct- academic support for pages-over-facts - the bet that separates us from+ academic support for pages-over-facts, the bet that separates us fromthe Mem0 camp. Its "narrative" layer (temporal storylines connectingevents) is the one level we only partially have (sessions andhandoffs are narrative-ish; nothing stitches them across weeks).-- **"From Storage to Experience" survey (arXiv:2605.06716)** - frames+- **"From Storage to Experience" survey (arXiv:2605.06716)** framesthe field's evolution as Storage (preserve trajectories) → Reflection(refine them) → Experience (abstract *across* trajectories, proactive).We are solidly through Storage and Reflection (capture, consolidation,- curator, lint, feedback-driven salience). The frontier it names -- cross-trajectory abstraction - is where our auto-improve is a- beginning, not an answer.-- **LongMemEval-V2 (arXiv:2605.12493)** - the benchmark generation has+ curator, lint, feedback-driven salience). The frontier it names,+ cross-trajectory abstraction, is where our auto-improve is only a+ beginning.+- **LongMemEval-V2 (arXiv:2605.12493)**: the benchmark generation hasmoved from "recall the fact" to "behave like an experienced colleague"over long horizons, and finds every evaluated system far from it. Twoimplications: our product framing matches where evaluation is going,and the eval-harness recommendation from the May research (#8 in- `research-agentmemory.md`, never implemented) is now more pressing -+ `research-agentmemory.md`, never implemented) is now more pressing:the field publishes audited numbers and we publish none.- **Bi-temporal validity (Zep paper, arXiv:2501.13956, now mainstream- via Graphiti)** - the one *specific* mechanism from the graph camp+ via Graphiti)** is the one *specific* mechanism from the graph campworth studying: every fact/edge carries event-time andingestion-time, so "what did we believe on June 1" and "what was trueon June 1" are both answerable, and corrections are supersessions@@ -509,14 +509,14 @@ what dates it as active but young.- Also active, lower relevance for us: MIRIX (multi-agent memoryspecialization), MemOS/EverMemOS (scheduling memory like an OS),A-TMA (state-aware memory failure taxonomy), sleep-time compute- (Letta: consolidate between sessions, not during) - the last is- something we already do by shape (session-end consolidation jobs,+ (Letta: consolidate between sessions, not during). We already do the last+ by shape (session-end consolidation jobs,scheduled maintenance) without the branding.## 5. What this means for ai-memory - analysis and recommendations> Companion audit: [`competitive-parity.md`](competitive-parity.md) turns this-> "what to borrow" lens around and asks the harder one - in the goals where we+> "what to borrow" lens around and asks the harder one: in the goals where we> *overlap* a competitor, are we actually better or did we copy without> improving, and is ai-memory worth migrating *to*? It is the self-critical> record behind this section's recommendations.@@ -524,72 +524,72 @@ what dates it as active but young.The May research led us to build: versioned supersession, retentionformulas, hybrid RRF retrieval, opt-in LLM consolidation, handoffs as aprotocol, single self-contained binary, typed scope isolation. Every one-of those choices looks *better* in September than it did in May - the+of those choices looks *better* in September than it did in May. Thesubstrate competitors struggled (mempalace's metaphor, agentmemory'sKV), the file-first camp got standardized, and pages-over-facts got apaper. Nothing in this pass argues for re-architecture. Therecommendations are additive and ranked:-**R1 - OKF conformance (small, high leverage).** Map our frontmatter+**R1: OKF conformance (small, high leverage).** Map our frontmatterconventions onto OKF v0.1 (`type` field plus its small vocabulary) and-add an OKF export - possibly just documentation plus a thin+add an OKF export, possibly just documentation plus a thin`ai-memory export --okf` view of `wiki/`. Being the *server-grade*-implementation of the format Google standardized is a positioning gift:+implementation of the format Google standardized helps our positioning:interop with every OKF-aware consumer, at conventions-mapping cost.Evaluate whether native conformance (wiki pages *are* OKF files) beatsan export step; the closer to native, the stronger the story.-**R2 - Reproducible eval harness against LongMemEval-V2 (medium).** The+**R2: Reproducible eval harness against LongMemEval-V2 (medium).** Theoldest open recommendation, now with a sharper reason: benchmark claimsare being audited (mempalace) and honest numbers are being published(mcp-memory-service). We cannot say where we stand, and "experienced-colleague over long horizons" is literally our pitch. Harness in-repo,+colleague over long horizons" is our pitch. Harness in-repo,runnable on demand like `writer_throughput`, numbers in docs with the-run command - never a marketing claim without the harness. Hindsight+run command, and never a marketing claim without the harness. Hindsight(`research-hindsight.md`) sharpens this further: a funded competitor nowships a *paper* with per-category LongMemEval sub-scores (91.4%), so thebar is no longer "publish a number" but "publish a harness and a metric-someone else can re-run" - fix the split and the metric (theirs is+someone else can re-run". Fix the split and the metric (theirs isaccuracy, agentmemory/mcp-memory-service quote R@5; pick one and stateit) so our result is comparable, not just present. **Now load-bearing on-2.4:** the two aging features that can move quality — belief-strength folded-into ranking (#815) and the LLM "dream" pass (#816) — ship **off by default+2.4:** the two aging features that can move quality, belief-strength folded+into ranking (#815) and the LLM "dream" pass (#816), ship **off by defaultand gated on this harness before they may default on**; no R2 delta has beenrun yet, so both remain opt-in and unproven (see[`design-memory-aging.md`](design-memory-aging.md) R2 acceptance).-**R3 - Typed relation edges (small-medium).** `causes` / `fixes` /+**R3: Typed relation edges (small-medium).** `causes` / `fixes` /`contradicts` on our existing `links`/`entities` model, from thedoobidoo playbook. Cheap because the tables exist; valuable because`contradicts` feeds the lint pass we already run, and `fixes` makesbug-page chains retrievable as chains.-**R4 - Temporal validity on entities/links (medium, evaluate first).**+**R4: Temporal validity on entities/links (medium, evaluate first).**Bi-temporal-lite: `valid_from` / `superseded_at` on entity-page links so"what was the database choice in June" is answerable. Pages alreadysupersede; this extends the same idea one level down. Worth a design-doc before any code - the Graphiti paper is the reference.+doc before any code; the Graphiti paper is the reference.-**R5 - Cross-session abstraction pass (medium-large, the "Experience"+**R5: Cross-session abstraction pass (medium-large, the "Experience"gap).** A periodic consolidation that reads *across* recent sessions-per project and rewrites pattern/preference pages - the cross-trajectory+per project and rewrites pattern/preference pages: the cross-trajectoryabstraction both the survey and TriMem's narrative layer point at.auto-improve is the natural host; today it is per-session-triggered.Hindsight's **mental-model tier + reflect loop** (`research-hindsight.md`)-is the shipped reference implementation for exactly this - a background+is the shipped reference implementation for exactly this (a backgroundjob that rewrites standing-answer pages across accumulated evidence, that-an agent boots from - and it is worth reading before designing ours. Its+an agent boots from), and it is worth reading before designing ours. Itsconsolidation-as-belief-strength (evidence count + quotes, strengthen/weaken/extend) also points at how R3/R4 could carry *confidence*, notjust supersession order.-**R6 - Local embeddings via ONNX (medium; already reserved).**+**R6: Local embeddings via ONNX (medium; already reserved).**`models/` has been reserved for exactly this since M9.5 planning.Competitors ship all-MiniLM locally by default; it removes the providerdependency from vector search and makes hybrid retrieval a zero-configdefault rather than an opt-in. The `ort` crate is the known path.-**R7 - Progressive-disclosure retrieval/brief tiers (medium; evaluate+**R7: Progressive-disclosure retrieval/brief tiers (medium; evaluatefirst, design doc before code).** From OpenViking's L0/L1/L2 model, whosereported 34-91% input-token cut is almost entirely deferring full content.We already have the pieces: `memory_query` returns ~24-word snippets (an@@ -599,7 +599,7 @@ embeddings + the session brief exist. The gap is an explicit **L1leads with per-page abstracts and expands to full bodies only on demandinstead of loading core-page bodies up front (`render_session_brief`today spends its whole char budget on L2). This is a token-efficiency-win on the exact hot path — every opted-in session start — with no new+win on the exact hot path (every opted-in session start) with no newstorage: reuse the abstract already embedded at V61. Worth a design docthat decides where the L1 overview comes from (frontmatter summary,first-paragraph extraction, or the existing abstract) before any code;@@ -610,37 +610,37 @@ summary + L2 keep-token shape for cold episodic pages([`design-memory-aging.md`](design-memory-aging.md)); the remaining R7 workis the *tiered on-start brief* that leads with abstracts, still a designdoc before code. Directory-scoped retrieval-(OpenViking's TrieHI) is the lower-priority half — a path-prefix filter-on `memory_query` within a project — worth noting but not scheduling+(OpenViking's TrieHI) is the lower-priority half: a path-prefix filter+on `memory_query` within a project, worth noting but not schedulinguntil R7's tiering lands.-**R8 - Queryable metadata/tag filters + a published eval triple (small-+**R8: Queryable metadata/tag filters + a published eval triple (small-medium; from Supermemory).** Two borrowable ideas from the entrant that leadson ergonomics. First, **structured metadata/tag filtering on `memory_query`**:we already key every row by the `(workspace, project, path)` 3-tuple, butSupermemory's `containerTags` + arbitrary metadata filters let a caller narrowrecall by attributes (kind, tier, author, tag) *before* ranking. A bounded,-optional filter argument on `memory_query` - composing with FTS5/RRF, not-replacing it - closes a real query-ergonomics gap at low cost; most of the+optional filter argument on `memory_query`, composing with FTS5/RRF rather than+replacing it, closes a real query-ergonomics gap at low cost; most of theplumbing (page frontmatter, kinds/tiers, `_slots`) already exists. Second,**publish an accuracy / latency / context-tokens triple** from the in-repo`recall_eval.rs`, mirroring Supermemory's open **MemScore / MemoryBench**philosophy: honest engineering discipline and the right answer to a field now-competing on self-reported single numbers - it composes with R2 (the+competing on self-reported single numbers. It composes with R2 (thereproducible-harness recommendation) rather than competing. A per-project orper-user **"profile" page** auto-surfaced on start (Supermemory's standingprofile) is a lighter third idea that maps onto our durable pages + the session-brief - worth noting, below the two above. Deliberately *not* borrowed from this-camp: managed cloud connectors and LLM-required extraction in the **core** - if+brief, worth noting but ranked below the two above. Deliberately *not* borrowed from this+camp: managed cloud connectors and LLM-required extraction in the **core**. Ifconnectors ever land they belong in the companion importer as opt-in, outsidethe trusted boundary, so the file-first / zero-LLM model is preserved (the sameline drawn for multimodal/PDF import: OCR/transcribe to markdown pages, never an-opaque store). On the other two axes the verdict is blunt: **security - nothing-to borrow** (Supermemory is weaker on every axis we chose - opaque store,+opaque store). On the other two axes: **security, nothing+to borrow** (Supermemory is weaker on every axis we chose: opaque store,cloud-first, LLM-required, `containerTag` isolation vs our 3-tuple + invariant-#16 - so this pass is confirmation of our posture, not a source of borrowings;+#16, so this pass is confirmation of our posture, not a source of borrowings;the only security-relevant note is defensive: any future importer connector must-cross the existing sanitizer boundary), and **performance - only f16/+cross the existing sanitizer boundary), and **performance, only f16/half-precision embedding storage is worth *evaluating*** (a stored-format changewith a real recall-vs-size tradeoff, gated on `recall_eval.rs`), while their"sub-300ms p50" is a publish-a-number contract, not a change we need. Ranked, the@@ -649,11 +649,11 @@ worth doing because it de-risks measuring anything else; f16 is evaluate-only;the rest is hold-or-reject. No implementation is scheduled here.**Deliberately not recommended:** joining the memory-OS camp (agent-self-editing its memory - token-expensive, and Letta itself is hedging);+self-editing its memory is token-expensive, and Letta itself is hedging);adopting a graph database (bi-temporal-lite on SQLite covers the usefulpart); spatial/metaphor architectures (mempalace); publishing anybenchmark number before R2 exists; chasing agentmemory's tool-count-(the May conclusion stands - a sharp small surface is the advantage).+(the May conclusion stands: a sharp small surface is the advantage).## 6. Sources@@ -685,7 +685,7 @@ benchmark number before R2 exists; chasing agentmemory's tool-countstars); supermemory.ai/docs (how-it-works, graph-memory, self-hosting,connectors, filtering); github.com/supermemoryai/{memorybench,opencode-supermemory, supermemory-mcp}; supermemory.ai/blog (memory-engine,- supermemory-vs-mem0 - vendor self-reported benchmarks); DeepWiki+ supermemory-vs-mem0; vendor self-reported benchmarks); DeepWikicode-derived architecture; TechCrunch/Dataconomy 2025-10 (seed funding,founder). Hosted backend is closed-source, so its storage internals,latency, and benchmark numbers are vendor claims, not primary-verifiable.@@ -702,30 +702,30 @@ benchmark number before R2 exists; chasing agentmemory's tool-counthermes-agent.nousresearch.com Honcho integration. Benchmarks arevendor-reported and not independently reproduced. Analyzed inline in §3per the no-standalone-doc convention.-- LiquidLM: liquidlm.com (+ /about, /docs, /docs/assistants, /docs/mcp — Vaults,+- LiquidLM: liquidlm.com (+ /about, /docs, /docs/assistants, /docs/mcp: Vaults,MCP tool surface, per-harness support with test dates), github.com/liquidlm(org: an archived empty `cli` repo + a homebrew tap, no engine source), and thenpm registry metadata for `@liquidlm/cli` (MIT, v0.1.5 published 2026-09-17).Solo maker (Carlos Souza), closed-source cloud engine, no benchmarks; thebackend internals, model, and any numbers are undisclosed/vendor framing.Analyzed inline in §3 per the no-standalone-doc convention.-- Engram (issue #810): github.com/Gentleman-Programming/engram (README —+- Engram (issue #810): github.com/Gentleman-Programming/engram (README:SQLite+FTS5, Go single binary, MCP stdio, operating contract /`mem_session_summary`, git-sync, Engram Cloud; MIT) and the GitHub metadataendpoint (~6.8K stars, commit 2026-09-22, release v2.0.0). No benchmarkpublished. Analyzed inline in §3 per the no-standalone-doc convention.-- EverOS (issue #810): github.com/EverMind-AI/EverOS (README — Markdown source+- EverOS (issue #810): github.com/EverMind-AI/EverOS (README: Markdown sourceof truth + SQLite/LanceDB indexes, user/agent tracks, Knowledge Wiki, offlineconsolidation, minimal-tier LLM-required, OpenRouter default; Apache-2.0) andthe metadata endpoint (~13.1K stars, commit 2026-09-09, release v1.3.1). Nobenchmark published. Analyzed inline in §3 per the no-standalone-doc convention.-- memU (issue #810): github.com/NevaMind-AI/memU (README — shared LLM wiki,+- memU (issue #810): github.com/NevaMind-AI/memU (README: shared LLM wiki,Markdown skill distillation, SQLite/Postgres+pgvector, host-instruction-filesidecars, no MCP; LICENSE.txt = Apache-2.0) and the metadata endpoint (~14.4Kstars, commit 2026-09-21, release v1.5.1 2026-03-23 so releases lag); managedcloud at memu.so. No named benchmark. Analyzed inline in §3 per theno-standalone-doc convention.-- Caura (issue #810): github.com/caura-ai/caura (README — governed multi-agent+- Caura (issue #810): github.com/caura-ai/caura (README: governed multi-agentfleet memory on Postgres+pgvector, visibility scopes, four trust tiers, audit,PII flagging, KG, MCP `/mcp`; Apache-2.0) + managed caura.ai, and the metadataendpoint (~0.5K stars, commit 2026-09-22, release backend-v3.17.2). Benchmarks@@ -733,7 +733,7 @@ benchmark number before R2 exists; chasing agentmemory's tool-countREADME-stated and vendor self-reported, not independently verified. Analyzedinline in §3 per the no-standalone-doc convention.- TencentDB Agent Memory (issue #810): github.com/TencentCloud/TencentDB-Agent-- Memory (README — Chat Memory/Skill/Wiki/CodeGraph assets, proxy fan-in base-URL+ Memory (README: Chat Memory/Skill/Wiki/CodeGraph assets, proxy fan-in base-URLinterception, Node/TS, SQLite default + experimental MongoDB, harness list;LICENSE = MIT despite the GitHub NOASSERTION detection) and the metadataendpoint (~27.2K stars, commit 2026-09-22, release v2.0.1). PersonaMemdiff --git a/docs/research-agentmemory.md b/docs/research-agentmemory.mdindex cc4d1da1..6e7f2ec7 100644--- a/docs/research-agentmemory.md+++ b/docs/research-agentmemory.md@@ -1,38 +1,38 @@# agentmemory - Research Report-> **Follow-up:** the September 2026 landscape refresh — how this project-> evolved, what the field looks like now, and what we concluded — is in+> **Follow-up:** the September 2026 landscape refresh (how this project+> evolved, what the field looks like now, and what we concluded) is in> [`research-2026-landscape.md`](research-2026-landscape.md).> Source project: `rohitg00/agentmemory` (TypeScript, MCP server built on `iii-engine`).-> This repo builds on that earlier TypeScript project: keep the *ideas*, replace-> the *substrate*.+> This repo builds on that earlier TypeScript project, keeping its *ideas* and+> replacing its *substrate*.## 1. Purpose & Scope-agentmemory is **persistent memory infrastructure for AI coding agents**. The core pitch: an agent silently captures what you do during a coding session (tool calls, prompts, decisions, errors), compresses those raw observations into searchable memory, and re-injects relevant context into the *next* session so the user never has to re-explain architecture, preferences, or past bugs. README pitches a tagline ("Your coding agent remembers everything. No more re-explaining.") with claimed retrieval R@5 of 95.2% on LongMemEval-S vs. 86.2% BM25-only fallback, and ~1,900 tokens/session vs. ~22K for raw CLAUDE.md.+agentmemory is **persistent memory infrastructure for AI coding agents**. An agent silently captures what you do during a coding session (tool calls, prompts, decisions, errors), compresses those raw observations into searchable memory, and re-injects relevant context into the *next* session so the user never has to re-explain architecture, preferences, or past bugs. README pitches a tagline ("Your coding agent remembers everything. No more re-explaining.") with claimed retrieval R@5 of 95.2% on LongMemEval-S vs. 86.2% BM25-only fallback, and ~1,900 tokens/session vs. ~22K for raw CLAUDE.md.-The author explicitly frames it as the *implementation* of Karpathy's "LLM Wiki" pattern, extended with confidence scoring, lifecycle, knowledge graph, and hybrid search - the project page touts a viral gist with 1200+ stars that articulated the design.+The author explicitly frames it as the *implementation* of Karpathy's "LLM Wiki" pattern, extended with confidence scoring, lifecycle, knowledge graph, and hybrid search; the project page points to a viral gist with 1200+ stars that articulated the design.Caveat about `DESIGN.md`: that file in agentmemory is a Lamborghini-inspired *visual* design system for the marketing site, not architecture. The real architecture docs are in `AGENTS.md` and `README.md`.-`ROADMAP.md` confirms the trajectory: Q2 2026 "Depth" (multimodal), Q3 "Breadth" (more agents, OpenSSF), Q4 "Trust" (SSO/RBAC), Q1 2027 v1.0 freeze. Candidate item for Q1 2027: *"Reference implementation in a second language (Rust or Go)"* - directly relevant to this project.+`ROADMAP.md` confirms the trajectory: Q2 2026 "Depth" (multimodal), Q3 "Breadth" (more agents, OpenSSF), Q4 "Trust" (SSO/RBAC), Q1 2027 v1.0 freeze. Candidate item for Q1 2027: *"Reference implementation in a second language (Rust or Go)"*, which is directly relevant to this project.## 2. Architecture- **Stack**: TypeScript (ESM, Node ≥ 20), packaged as `@agentmemory/agentmemory`. Build via `tsdown`.-- **Not a standalone server**. Everything is built on top of **iii-engine**, a separately-installed Rust binary that runs on `ws://localhost:49134` and provides Worker/Function/Trigger primitives (`AGENTS.md:5`). The Node process registers functions; the engine routes them. This is the project's central architectural bet.+- **Not a standalone server**. Everything runs on top of **iii-engine**, a separately-installed Rust binary that runs on `ws://localhost:49134` and provides Worker/Function/Trigger primitives (`AGENTS.md:5`). The Node process registers functions; the engine routes them. This is the project's central architectural bet.- **Storage**: a single **file-based SQLite KV store**, owned by iii-engine's StateModule, not by the Node process. From `iii-config.yaml:11-16`:```yaml- name: iii-stateconfig:adapter: { name: kv, config: { store_method: file_based, file_path: ./data/state_store.db } }```- The Node code only sees a tiny shim (`src/state/kv.ts:6-46`) wrapping five RPCs (`state::get/set/list/update/delete`). No direct SQLite, no Postgres, no Qdrant, no graph DB - *all* memory types are stored as JSON values under namespaced "scopes" (e.g. `mem:memories`, `mem:semantic`, `mem:graph:nodes`).+ The Node code only sees a tiny shim (`src/state/kv.ts:6-46`) wrapping five RPCs (`state::get/set/list/update/delete`). There is no direct SQLite, Postgres, Qdrant, or graph DB; *all* memory types are stored as JSON values under namespaced "scopes" (e.g. `mem:memories`, `mem:semantic`, `mem:graph:nodes`).- **Indices** live in-process: BM25 (`src/state/search-index.ts`), an in-RAM vector index with cosine similarity (`src/state/vector-index.ts`), and persisted snapshots written back into KV via `IndexPersistence` (`src/state/index-persistence.ts`). Hybrid search uses RRF-style fusion of BM25 + vector + graph (`src/state/hybrid-search.ts`).-- **Surfaces**: REST API on `:3111` (124 endpoints - `src/triggers/api.ts`), MCP server on stdio via `npx @agentmemory/mcp` (`src/mcp/server.ts`, ~62KB, with 53 tools in `src/mcp/tools-registry.ts`), live WebSocket stream on `:3112`, and a real-time viewer HTML on `:3113`.-- **KV scope catalogue**: `src/state/schema.ts:3-50` lists ~40 scopes (sessions, observations per-session, memories, summaries, semantic, procedural, graph:nodes/edges, insights, lessons, crystals, sketches, sentinels, actions, leases, routines, signals, checkpoints, mesh, slots, retention, accessLog, audit, imageRefs, etc.). The breadth is striking - but it's all one SQLite file.+- **Surfaces**: REST API on `:3111` (124 endpoints, `src/triggers/api.ts`), MCP server on stdio via `npx @agentmemory/mcp` (`src/mcp/server.ts`, ~62KB, with 53 tools in `src/mcp/tools-registry.ts`), live WebSocket stream on `:3112`, and a real-time viewer HTML on `:3113`.+- **KV scope catalogue**: `src/state/schema.ts:3-50` lists ~40 scopes (sessions, observations per-session, memories, summaries, semantic, procedural, graph:nodes/edges, insights, lessons, crystals, sketches, sentinels, actions, leases, routines, signals, checkpoints, mesh, slots, retention, accessLog, audit, imageRefs, etc.). That is a wide catalogue, but it all lives in one SQLite file.## 3. Memory Model@@ -42,59 +42,59 @@ export type ConsolidationTier = "working" | "episodic" | "semantic" | "procedura```- **Raw observation** (`RawObservation`, `types.ts:29-42`): captured by hooks on every tool call.-- **Compressed observation** (`types.ts:44-62`): structured XML output from an LLM (`mem::compress`) with `type`, `title`, `facts`, `narrative`, `concepts`, `files`, `importance` 1–10. *Critically* this LLM compression is OFF by default (`src/index.ts:245-253`, issue #138). Default path uses **synthetic** compression (`src/functions/compress-synthetic.ts`) - zero LLM calls - to keep token bills sane. Set `AGENTMEMORY_AUTO_COMPRESS=true` to opt in.-- **Memory** (`types.ts:81-101`): consolidated long-term entry with `type` (pattern/preference/architecture/bug/workflow/fact), `strength`, `version`, `supersedes`, `isLatest`. Versioned in place - old memory `isLatest=false`, new one keeps `parentId`/`supersedes` chain (`src/functions/consolidate.ts:159-191`).+- **Compressed observation** (`types.ts:44-62`): structured XML output from an LLM (`mem::compress`) with `type`, `title`, `facts`, `narrative`, `concepts`, `files`, `importance` 1–10. This LLM compression is OFF by default (`src/index.ts:245-253`, issue #138). The default path uses **synthetic** compression (`src/functions/compress-synthetic.ts`), with zero LLM calls, to keep token bills down. Set `AGENTMEMORY_AUTO_COMPRESS=true` to opt in.+- **Memory** (`types.ts:81-101`): consolidated long-term entry with `type` (pattern/preference/architecture/bug/workflow/fact), `strength`, `version`, `supersedes`, `isLatest`. Versioned in place: the old memory gets `isLatest=false`, and the new one keeps `parentId`/`supersedes` chain (`src/functions/consolidate.ts:159-191`).- **SemanticMemory** (`types.ts:435-446`): individual *facts* with confidence + access counts.- **ProceduralMemory** (`types.ts:448-462`): named procedures with steps + trigger condition.- **Lesson / Insight / Crystal**: a higher tier of distillation. Crystals (`crystallize.ts`) summarize chains of completed Actions into narrative + key outcomes + lessons; Lessons feed Reflect which produces Insights from concept clusters.-- **MemorySlot** (`types.ts:222-232`, `functions/slots.ts:13-83`): pinned editable text blocks (persona, user_preferences, project_context, guidance, pending_items, etc.) - Karpathy-wiki-style human-editable section. Always injected into context via `src/functions/context.ts:43-61`.+- **MemorySlot** (`types.ts:222-232`, `functions/slots.ts:13-83`): pinned editable text blocks (persona, user_preferences, project_context, guidance, pending_items, etc.), a Karpathy-wiki-style human-editable section. Always injected into context via `src/functions/context.ts:43-61`.**Automatic operations (no manual writes needed)**:-- `mem::observe` runs from `PostToolUse` hook on every tool call - privacy-stripped, dedup'd, optionally LLM-compressed, indexed, streamed live (`functions/observe.ts:42-280`).+- `mem::observe` runs from `PostToolUse` hook on every tool call: privacy-stripped, dedup'd, optionally LLM-compressed, indexed, streamed live (`functions/observe.ts:42-280`).- `setInterval` timers in `src/index.ts:491-531`: auto-forget every 1h, lesson decay every 24h, insight decay every 24h, consolidation pipeline every 2h.- `mem::auto-forget` (`functions/auto-forget.ts`): deletes TTL-expired memories, soft-deletes contradiction pairs (Jaccard similarity > 0.9), purges 180-day-old observations with importance ≤ 2.-- `mem::retention-score` (`functions/retention.ts:80-94`): retention = `salience * exp(-λ·Δt) + reinforcementBoost(accessLog, σ)`. Below the "cold" threshold (0.15), entries become evictable. The reinforcement boost (`computeReinforcementBoost`) sums `1/daysSinceAccess` - classic spaced-repetition.+- `mem::retention-score` (`functions/retention.ts:80-94`): retention = `salience * exp(-λ·Δt) + reinforcementBoost(accessLog, σ)`. Below the "cold" threshold (0.15), entries become evictable. The reinforcement boost (`computeReinforcementBoost`) sums `1/daysSinceAccess`, a classic spaced-repetition scheme.## 4. Reorganization / Consolidation (the Karpathy bit)-This is the most interesting part. The consolidation pipeline runs on a 2h cron (`src/index.ts:523-531`) when `CONSOLIDATION_ENABLED=true`. `functions/consolidation-pipeline.ts:50-269` orchestrates four tiers:+The consolidation pipeline runs on a 2h cron (`src/index.ts:523-531`) when `CONSOLIDATION_ENABLED=true`. `functions/consolidation-pipeline.ts:50-269` orchestrates four tiers:1. **Semantic tier**: takes the 20 most recent `SessionSummary` items, asks the LLM to extract `<fact confidence="x">…</fact>` items. Existing facts (matched case-insensitively) get `accessCount++` and `confidence = max(old, new)`; new ones become `SemanticMemory` rows (`consolidation-pipeline.ts:91-122`).2. **Reflect tier**: `mem::reflect` (`functions/reflect.ts`) walks the knowledge graph, builds concept clusters via BFS-by-degree (`buildGraphClusters`, falls back to Jaccard clustering at line 106 if no graph), feeds each cluster's facts + lessons + crystals to the LLM with the `REFLECT_SYSTEM` prompt, expects `<insight>` XML back. Existing insights (fingerprinted on content) get `reinforcements++` and `confidence += 0.1*(1-confidence)` (reflect.ts:26-35); new ones are stored with `decayRate=0.05/week`.3. **Procedural tier**: finds Memory rows of type `pattern` with `frequency >= 2`, extracts named `<procedure>` blocks with steps.4. **Decay tier**: applies geometric decay `strength *= 0.9^decayPeriods` after a configurable inactivity window (`applyDecay` at consolidation-pipeline.ts:21-43).-Separately, `mem::consolidate` (`functions/consolidate.ts:65-225`) groups observations by concept, picks the top-N most important per concept, and for each cluster either *creates* a Memory or *evolves* an existing one. Evolution = mark old `isLatest=false`, write a new row pointing at it via `supersedes` and `parentId` (lines 161-189). The old memory isn't deleted - it remains versioned-but-shadowed, with `isLatest` filtering at read time.+Separately, `mem::consolidate` (`functions/consolidate.ts:65-225`) groups observations by concept, picks the top-N most important per concept, and for each cluster either *creates* a Memory or *evolves* an existing one. Evolution = mark old `isLatest=false`, write a new row pointing at it via `supersedes` and `parentId` (lines 161-189). The old memory isn't deleted; it remains versioned-but-shadowed, with `isLatest` filtering at read time.`mem::insight-decay-sweep` (`functions/reflect.ts:425-476`) runs weekly: `newConfidence = confidence - decayRate * weeksSince`. Below 0.1 with zero reinforcements, soft-deleted.-This is genuinely Karpathy-wiki-shaped: **memories aren't append-only - they get rewritten in place via versioned supersession, and unused entries quietly fade.**+This matches the Karpathy wiki pattern: **memories get rewritten in place via versioned supersession instead of only appended, and unused entries fade.**## 5. Agent IntegrationThree surfaces, depending on what the host supports:-- **Hooks (Claude Code, Codex)**: 12 hook scripts in `src/hooks/` - standalone Node scripts that read JSON from stdin and POST to `/agentmemory/observe` over HTTP with a 3s timeout. `plugin/hooks/hooks.json` registers all 12 (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, PreCompact, SubagentStart/Stop, Notification, TaskCompleted, Stop, SessionEnd). Codex gets a 6-hook subset (`README.md:419`).-- **MCP tools**: 53 tools in `src/mcp/tools-registry.ts` - `memory_recall`, `memory_smart_search`, `memory_save`, `memory_sessions`, `memory_consolidate`, `memory_action_create`, `memory_lease`, `memory_signal_send`, `memory_crystallize`, etc. Only 8 are visible by default (`AGENTMEMORY_TOOLS=all` exposes the rest, AGENTS.md:114).-- **Skills** (slash commands): `plugin/skills/{recall,remember,handoff,recap,forget,session-history,commit-context,commit-history}/SKILL.md` - each is a markdown file with frontmatter the host parses.+- **Hooks (Claude Code, Codex)**: 12 hook scripts in `src/hooks/`, standalone Node scripts that read JSON from stdin and POST to `/agentmemory/observe` over HTTP with a 3s timeout. `plugin/hooks/hooks.json` registers all 12 (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, PreCompact, SubagentStart/Stop, Notification, TaskCompleted, Stop, SessionEnd). Codex gets a 6-hook subset (`README.md:419`).+- **MCP tools**: 53 tools in `src/mcp/tools-registry.ts`: `memory_recall`, `memory_smart_search`, `memory_save`, `memory_sessions`, `memory_consolidate`, `memory_action_create`, `memory_lease`, `memory_signal_send`, `memory_crystallize`, etc. Only 8 are visible by default (`AGENTMEMORY_TOOLS=all` exposes the rest, AGENTS.md:114).+- **Skills** (slash commands): `plugin/skills/{recall,remember,handoff,recap,forget,session-history,commit-context,commit-history}/SKILL.md`; each is a markdown file with frontmatter the host parses.- **System-prompt injection**: pre-tool-use and session-start hooks can write up to 4000 chars of memory context to stdout, which Claude Code prepends to the next turn. **Off by default** (`AGENTMEMORY_INJECT_CONTEXT=false`) because of token-burn complaints (#143, see `src/hooks/pre-tool-use.ts:9-22`).## 6. Cross-Agent HandoffTwo mechanisms:-- **`/handoff` skill** (`plugin/skills/handoff/SKILL.md`): finds the most recent session whose `cwd` matches your current directory (with proper path-boundary check), surfaces any unanswered question first, then fetches a recall of top concepts. This works *because all agents write to the same `:3111` server* - a Claude Code session and a Codex session in the same project share KV. Cross-agent recall is implicit.+- **`/handoff` skill** (`plugin/skills/handoff/SKILL.md`): finds the most recent session whose `cwd` matches your current directory (with proper path-boundary check), surfaces any unanswered question first, then fetches a recall of top concepts. This works *because all agents write to the same `:3111` server*: a Claude Code session and a Codex session in the same project share KV. Cross-agent recall is implicit.- **Signals** (`functions/signals.ts`): a typed inter-agent message bus with `from`/`to`/`threadId`/`type: handoff|request|response|alert|info` and TTLs. `mem::signal-send` + `mem::signal-read` MCP tools.- **Mesh sync** (`functions/mesh.ts`) does LWW-merge replication between agentmemory *servers* on different machines, but cross-agent on a single box is just the shared SQLite.-Roadmap explicitly flags "Cross-agent shared memory namespace" as Q3 2026 candidate and "Agent-to-agent memory handoff protocol" for Q4 2026 - so the current support is informal.+Roadmap explicitly flags "Cross-agent shared memory namespace" as Q3 2026 candidate and "Agent-to-agent memory handoff protocol" for Q4 2026, so the current support is informal.## 7. Self-Healing / Operations-- **Backup**: `mem::snapshot-create` (`functions/snapshot.ts:44-150`) dumps sessions + memories + graphNodes + observations + accessLogs to a `state.json` and `git commit`s it into a configurable directory. Configurable interval cron. Each snapshot has a SnapshotMeta with commitHash. There's a `mem::snapshot-diff` too. Git-as-backup is clever.+- **Backup**: `mem::snapshot-create` (`functions/snapshot.ts:44-150`) dumps sessions + memories + graphNodes + observations + accessLogs to a `state.json` and `git commit`s it into a configurable directory. Configurable interval cron. Each snapshot has a SnapshotMeta with commitHash. There's a `mem::snapshot-diff` too. Using git as the backup is a good idea.- **Migration**: `mem::migrate` (`functions/migrate.ts`) reads legacy `better-sqlite3` DBs and replays them through the KV layer, with a path-allowlist guard (only under `~/.agentmemory/`).- **Schema versioning**: an explicit `ExportData.version` union with 50+ string literals (`types.ts:296`) and `supportedVersions` in `export-import.ts`. Updating it requires editing 6 files (AGENTS.md:28-34).-- **Vector index corruption guard**: at boot, `src/index.ts:367-410` *refuses to start* if persisted vectors have mixed dimensions, with a structured remediation message. Beautiful defensive code.+- **Vector index corruption guard**: at boot, `src/index.ts:367-410` *refuses to start* if persisted vectors have mixed dimensions, with a structured remediation message. This is careful defensive code.- **Diagnostics**: `mem::diagnose` (`functions/diagnostics.ts`) runs 8 category checks (orphan leases, blocked actions with all deps done, dead sentinels...) and `mem::heal` auto-fixes the fixable ones.- **Audit**: every state-changing operation records to `KV.audit` with a typed operation union (`types.ts:493-539`, ~45 op types). `AGENTS.md:39-41` makes adding new ones mandatory.- **Resilience**: top-level `unhandledRejection` swallow with throttled logging (`src/index.ts:118-128`) to survive iii-engine timeout spikes (#204). Circuit-breaker + fallback-chain providers (`src/providers/`).@@ -103,18 +103,18 @@ Roadmap explicitly flags "Cross-agent shared memory namespace" as Q3 2026 candid**What's clever and worth reusing:**-- **Two-tier compression (synthetic default, LLM opt-in)**: the #138 fix is the right call. Default zero-LLM keeps token bills sane while preserving BM25/vector search. Critical lesson - don't make the LLM call mandatory.-- **Versioned in-place memory evolution** (`isLatest` + `supersedes` chain): exactly the Karpathy wiki-rewrite pattern. Cheaper than maintaining a separate "graveyard", and `parentId` keeps history queryable.-- **Retention-as-formula** rather than rules: `salience * exp(-λΔt) + Σ(σ/daysSinceAccess)`. Tunable, principled, batchable. Worth borrowing wholesale.+- **Two-tier compression (synthetic default, LLM opt-in)**: the #138 fix is the right call. Default zero-LLM keeps token bills down while preserving BM25/vector search. Lesson: don't make the LLM call mandatory.+- **Versioned in-place memory evolution** (`isLatest` + `supersedes` chain): the Karpathy wiki-rewrite pattern. Cheaper than maintaining a separate "graveyard", and `parentId` keeps history queryable.+- **Retention-as-formula** rather than rules: `salience * exp(-λΔt) + Σ(σ/daysSinceAccess)`. It is tunable and can be computed in batches. Worth borrowing wholesale.- **Triple-stream RRF retrieval** (BM25 + vector + graph): graph-walk-as-third-signal is unusual and the benchmark numbers (95.2% R@5) suggest it pays off.-- **Git-as-snapshot-backup**: dump state.json, `git commit`. Diffable, restorable, no DB-specific tooling needed.-- **Slots**: pinned, human-editable, always-injected wiki-style sections. The user can hand-edit `project_context` and it survives forever - a clean escape hatch from purely-emergent memory.-- **Hook scripts as standalone Node files** (no SDK import, just HTTP): fast startup, fault-tolerant. The 800ms-1500ms hard timeouts (`src/hooks/session-start.ts:27-28`) are explicit - there's a war story about #221 where unbounded hook fan-out OOM-killed iii-engine.-- **Privacy filter at observe boundary** (`stripPrivateData` before any persistence): defense in depth.+- **Git-as-snapshot-backup**: dump state.json, `git commit`. The result is diffable and restorable without DB-specific tooling.+- **Slots**: pinned, human-editable, always-injected wiki-style sections. The user can hand-edit `project_context` and it survives forever, which gives an escape hatch from purely emergent memory.+- **Hook scripts as standalone Node files** (no SDK import, just HTTP): fast startup, fault-tolerant. The 800ms-1500ms hard timeouts (`src/hooks/session-start.ts:27-28`) are explicit; issue #221 records unbounded hook fan-out OOM-killing iii-engine.+- **Privacy filter at observe boundary** (`stripPrivateData` before any persistence), as defense in depth.**What feels overengineered:**-- **~40 KV scopes, 53 MCP tools, 124 REST endpoints, 50+ iii functions** is a *lot* of surface for v0.9. Many feel speculative (sentinels, sketches, frontier, leases, routines, checkpoints, facets, crystals, mesh, branch-aware, flow-compress, vision-search). The AGENTS.md "you must update ALL of the following" 7-step checklists are a smell - the system is so wide that ordinary changes ripple far.+- **~40 KV scopes, 53 MCP tools, 124 REST endpoints, 50+ iii functions** is a *lot* of surface for v0.9. Many feel speculative (sentinels, sketches, frontier, leases, routines, checkpoints, facets, crystals, mesh, branch-aware, flow-compress, vision-search). The AGENTS.md "you must update ALL of the following" 7-step checklists are a warning sign: the system is so wide that ordinary changes ripple far.- **iii-engine dependency**: every install requires a separate Rust binary, pinned to a specific version (0.11.2; 0.11.6 broke them), with no canonical Windows installer (`README.md:549`). For a Rust rewrite this is a *strong argument to be self-contained*: embed SQLite directly, drop the engine.- **All-JSON storage under one big SQLite file**: every "memories" or "graph nodes" list operation is `state::list` → return *all* JSON, parse in Node, filter in memory. `auto-forget.ts:67` literally caps at 1000 latest memories because the O(N²) Jaccard loop. Won't scale past ~10K memories without proper indexing.- **XML-in-LLM-output everywhere**: `<memory>...</memory>`, `<temporal_graph>`, `<insight>`. Fragile regex parsing (`parseCompressionXml`, `parseTemporalGraphXml`). A schema-validated JSON / structured-outputs path would be more robust.@@ -124,13 +124,13 @@ Roadmap explicitly flags "Cross-agent shared memory namespace" as Q3 2026 candid1. **First-class embedded store.** Use `rusqlite` (or `sqlx` + SQLite/Postgres) with *proper indices and FTS5* instead of JSON-blob-in-KV. The retention/auto-forget logic deserves real WHERE clauses, not in-memory filter passes. Look at `sqlite-vec` or `lancedb` for vectors so you're not maintaining a Map<String, Vec<f32>>.2. **Self-contained binary.** No separate engine. A single `agentmemory` binary that *is* the MCP server, REST server, and storage. The iii-engine indirection costs operability for ~nothing the user sees.-3. **Native MCP transport.** Use a proper Rust MCP SDK; you don't need an HTTP shim between hooks and storage - hooks can speak MCP-over-stdio or a Unix socket. Cuts the 3s HTTP timeout and the auth bearer dance.+3. **Native MCP transport.** Use a proper Rust MCP SDK; you don't need an HTTP shim between hooks and storage; hooks can speak MCP-over-stdio or a Unix socket. Cuts the 3s HTTP timeout and the auth bearer dance.4. **First-class structured outputs.** Don't parse `<memory><type>...</type></memory>` regex-strings. Use JSON-schema constrained generation; `serde_json` deserialization with strict validation.-5. **Smaller, sharper tool surface.** Pick the 8–12 tools that demonstrably matter (recall, save, sessions, smart_search, handoff, consolidate, forget, governance_delete) and ship those well. The 53-tool surface invites confusion; the README admits 8 are visible by default for a reason.-6. **Real graph store for temporal edges.** The temporal-graph design (`tvalid`, `tvalidEnd`, `supersededBy`, edge-history) is *good* - but implementing it on JSON blobs in KV means every "what does Alice prefer as of 2024-06-15" query is a full table scan. Consider `petgraph` in memory backed by a real SQL graph table, or a proper graph DB if you're going big.-7. **Cross-agent handoff as a designed protocol**, shared SQLite. The Q4 2026 roadmap candidate is exactly this - get there day one. Define a `Handoff` type with from-agent, to-agent, context, open-questions, files-touched, model-used; expose `mcp::handoff/begin` and `mcp::handoff/accept`.-8. **Reproducible eval harness.** They ran LongMemEval-S and got 95.2% R@5 - bake the harness into CI from the start so regressions are caught.+5. **Smaller tool surface.** Pick the 8–12 tools that demonstrably matter (recall, save, sessions, smart_search, handoff, consolidate, forget, governance_delete) and ship those well. The 53-tool surface invites confusion; the README admits 8 are visible by default for a reason.+6. **Real graph store for temporal edges.** The temporal-graph design (`tvalid`, `tvalidEnd`, `supersededBy`, edge-history) is *good*, but implementing it on JSON blobs in KV means every "what does Alice prefer as of 2024-06-15" query is a full table scan. Consider `petgraph` in memory backed by a real SQL graph table, or a proper graph DB if you're going big.+7. **Cross-agent handoff as a designed protocol**, shared SQLite. The Q4 2026 roadmap candidate is exactly this; ship it from day one. Define a `Handoff` type with from-agent, to-agent, context, open-questions, files-touched, model-used; expose `mcp::handoff/begin` and `mcp::handoff/accept`.+8. **Reproducible eval harness.** They ran LongMemEval-S and got 95.2% R@5; bake the harness into CI from the start so regressions are caught.9. **Single source of truth for schema.** The AGENTS.md "update all 7 files" checklists indicate the schema is duplicated across types, tools-registry, REST, MCP, tests, README, plugin. In Rust, one `proto`-or-derive-driven definition can generate all of those.10. **A clear `ARCHITECTURE.md`.** Don't repeat their mistake of scattering architecture across AGENTS, README, and inline comments.-The big takeaway: **agentmemory's *concepts* are unusually thoughtful** - versioned supersession, retention formulas, slot pinning, hybrid retrieval, opt-in LLM compression, session-cwd-based handoff. The *implementation* is constrained by the iii-engine bet and the all-JSON-in-KV storage choice. A Rust rewrite has a real opportunity to keep the ideas and drop the substrate.+In short, **agentmemory's *concepts* are unusually thoughtful**: versioned supersession, retention formulas, slot pinning, hybrid retrieval, opt-in LLM compression, session-cwd-based handoff. The *implementation* is constrained by the iii-engine bet and the all-JSON-in-KV storage choice. A Rust rewrite can keep the ideas and drop the substrate.diff --git a/docs/research-basic-memory.md b/docs/research-basic-memory.mdindex 95a1745d..15e5ea88 100644--- a/docs/research-basic-memory.md+++ b/docs/research-basic-memory.md@@ -1,7 +1,7 @@# basic-memory - Research Report-> **Follow-up:** the September 2026 landscape refresh — how this project-> evolved, what the field looks like now, and what we concluded — is in+> **Follow-up:** the September 2026 landscape refresh (how this project+> evolved, what the field looks like now, and what we concluded) is in> [`research-2026-landscape.md`](research-2026-landscape.md).@@ -13,7 +13,7 @@Basic Memory is a **local-first, MCP-native, Markdown-based personal knowledge graph**. Its tagline is "Your AI never forgets again": notes live as plain Markdown files on disk, both humans (in Obsidian, VS Code) and LLMs (over MCP) read and write them, and a SQLite/Postgres index keeps a knowledge graph in sync.-**The model is explicitly *manual*.** The user (or, more often, the agent in response to the user) calls `write_note`, `edit_note`, `move_note`, etc. There is **no implicit capture** of conversation content. The "How it works" example in `README.md:317-356` is literally *"Ask the LLM to capture it: 'Make a note on coffee brewing methods.'"* The README even prescribes user prompts ("Create a note about our project architecture decisions") as the activation step. Nothing in the codebase auto-saves conversation turns. The closest thing to automation is the `continue_conversation` *prompt* (`src/basic_memory/mcp/prompts/continue_conversation.py:18-90`), which only *retrieves* - it asks the model to search recent activity and load context; it never writes.+**The model is explicitly *manual*.** The user (or, more often, the agent in response to the user) calls `write_note`, `edit_note`, `move_note`, etc. There is **no implicit capture** of conversation content. The "How it works" example in `README.md:317-356` is literally *"Ask the LLM to capture it: 'Make a note on coffee brewing methods.'"* The README even prescribes user prompts ("Create a note about our project architecture decisions") as the activation step. Nothing in the codebase auto-saves conversation turns. The closest thing to automation is the `continue_conversation` *prompt* (`src/basic_memory/mcp/prompts/continue_conversation.py:18-90`), which only *retrieves*: it asks the model to search recent activity and load context; it never writes.## 2. Storage Model@@ -45,7 +45,7 @@ There is also a `NoteContent` table (`knowledge.py:152-217`) that **materializes## 3. MCP Tools Exposed-All tools are registered via the `@mcp.tool` decorator and exported from `src/basic_memory/mcp/tools/__init__.py:9-65`. Every tool is annotated with MCP `readOnlyHint`/`destructiveHint`/`idempotentHint`/`openWorldHint` so agents can pick safely. Every single tool requires **explicit invocation** - none are triggered by the server itself.+All tools are registered via the `@mcp.tool` decorator and exported from `src/basic_memory/mcp/tools/__init__.py:9-65`. Every tool is annotated with MCP `readOnlyHint`/`destructiveHint`/`idempotentHint`/`openWorldHint` so agents can pick safely. Every single tool requires **explicit invocation**; none are triggered by the server itself.| Tool | Hint | File ||---|---|---|@@ -73,40 +73,40 @@ The only background process is the `WatchService` (`src/basic_memory/sync/watch_## 5. Cross-Project / Cross-Agent-Projects are a first-class concept. Config holds a `Dict[str, ProjectEntry]` (`config.py:184-195`), each with a `path`, a `mode` (`LOCAL` or `CLOUD` - per-project routing), optional `workspace_id`, and bisync state. A `default_project` is auto-set to the first project (`config.py:705-711`).+Projects are a first-class concept. Config holds a `Dict[str, ProjectEntry]` (`config.py:184-195`), each with a `path`, a `mode` (`LOCAL` or `CLOUD`, for per-project routing), optional `workspace_id`, and bisync state. A `default_project` is auto-set to the first project (`config.py:705-711`).**Project resolution is a unified three-tier chain** (`docs/ARCHITECTURE.md:298-324`): explicit `project` argument → default → single-project fallback. Every MCP tool accepts `project` and `project_id` (UUID) parameters. `get_project_client(project, ...)` (`mcp/project_context.py`) routes to local ASGI or cloud HTTP per-project, so you can mix.-For agent handoffs, there is no special handshake - basic-memory treats all MCP clients identically. The "handoff" story is: agent A writes notes to project `foo`, agent B (any other MCP client pointed at the same project) reads them. The Markdown files on disk are the lingua franca. There is no session/agent identifier, no per-agent scratchpad. `created_by`/`last_updated_by` columns exist (`knowledge.py:99-102`) but are populated only in cloud (user_profile_id), null for local/CLI.+For agent handoffs, there is no special handshake; basic-memory treats all MCP clients identically. The "handoff" story is: agent A writes notes to project `foo`, agent B (any other MCP client pointed at the same project) reads them. The Markdown files on disk are the lingua franca. There is no session/agent identifier, no per-agent scratchpad. `created_by`/`last_updated_by` columns exist (`knowledge.py:99-102`) but are populated only in cloud (user_profile_id), null for local/CLI.## 6. Backup & Portability- **Default location**: `~/basic-memory` for notes (per `BASIC_MEMORY_HOME` env, README:197), `~/.basic-memory/` for SQLite DB + config (`config.py:24, 67-80`). Config in `~/.basic-memory/config.json`, chmod 0600.-- **Portability**: Excellent for files (they're just Markdown - `git clone`, `rsync`, Syncthing, rclone all work). The DB is a derived index - `bm sync` rebuilds it from the files.+- **Portability**: Excellent for files (they're just Markdown, so `git clone`, `rsync`, Syncthing, and rclone all work). The DB is a derived index; `bm sync` rebuilds it from the files.- **Schema migrations**: 22 Alembic migrations in `src/basic_memory/alembic/versions/`, auto-run on startup via `get_or_create_db` (`services/initialization.py:23-38`). Migrations cover both SQLite and Postgres.- **Importers** for Claude conversations, ChatGPT exports, and `memory.json` (the original MCP "memory" server format) live in `src/basic_memory/importers/`.-- **Cloud sync** uses `rclone bisync` (`config.py:136-138, 164-167`), not a custom protocol - another portable choice.+- **Cloud sync** uses `rclone bisync` (`config.py:136-138, 164-167`), not a custom protocol, which is another portable choice.## 7. Strengths Worth Borrowing1. **Files are source of truth, DB is derived index.** Survives any DB corruption, plays nice with git, version control, and grep. Bidirectional human/AI editing via file-watcher + checksum.2. **MCP behavior annotations on every tool** (`readOnlyHint`, `destructiveHint`, etc., `tools/write_note.py:23`). Agents can plan multi-step actions without trial-and-error.3. **Aggressive `AliasChoices` aliasing** of parameter names (`write_note.py:31` accepts `directory|folder|dir|path`; `search.py:574` accepts `query|q|search|text`). LLMs use whatever name their training reaches for; the tool absorbs the variance.-4. **`memory://` URI scheme + `build_context` graph walker** (`tools/build_context.py:114-247`) - turns wiki-links into navigable context. Cleaner than dumping the whole graph.-5. **Unresolved relations as first-class state** (`knowledge.py:282`) - `to_id` nullable, resolves later when target appears. Forward references just work.+4. **`memory://` URI scheme + `build_context` graph walker** (`tools/build_context.py:114-247`) turns wiki-links into navigable context. Cleaner than dumping the whole graph.+5. **Unresolved relations as first-class state** (`knowledge.py:282`): `to_id` is nullable and resolves later when target appears. Forward references just work.6. **Per-project routing** with mixed local/cloud modes per project, not per-server.7. **Composition root + typed-client pattern** (`docs/ARCHITECTURE.md:14-256`) keeps MCP/CLI/API entrypoints clean and testable.-8. **The `NoteContent` table** with `file_write_status` state machine (`knowledge.py:155-217`) handles the race between agent writes and on-disk human edits - worth replicating if you keep a DB cache.+8. **The `NoteContent` table** with `file_write_status` state machine (`knowledge.py:155-217`) handles the race between agent writes and on-disk human edits. Worth replicating if you keep a DB cache.## 8. Weaknesses / Friction (Avoid)-1. **The manual `write_note` ceremony is the headline friction.** Users must explicitly tell the model "make a note about this," and the model must decide *title*, *directory*, *tags*, *note_type*, and the semantic observation/relation grammar - all on every call. The `write_note` signature has 11 parameters (`write_note.py:25-45`). Skip this entirely: capture should be ambient (post-turn summarization, automatic salience scoring, etc.) - not a tool the model must remember to call.+1. **The manual `write_note` ceremony is the headline friction.** Users must explicitly tell the model "make a note about this," and the model must decide *title*, *directory*, *tags*, *note_type*, and the semantic observation/relation grammar, all on every call. The `write_note` signature has 11 parameters (`write_note.py:25-45`). Skip this entirely: capture should be ambient (post-turn summarization, automatic salience scoring, etc.) instead of a tool the model must remember to call.2. **Append-only forever.** No decay, no consolidation, no automatic deduplication. Long-running graphs accumulate cruft. Recent v0.20 added a guard so `write_note` *errors* on conflict instead of silently upserting (`write_note.py:240-262`), which protects data but pushes the burden back onto the agent to manage identity. For agent long-term memory, decay/merge/consolidation is essential and absent here.3. **The semantic grammar is human-authored convention.** `- [category] text #tag (context)` and `- relation_type [[Target]]` are intuitive for humans in Obsidian but require the LLM to *generate* this format correctly every time. Drift is normal. A Rust server can store edges natively and let the LLM emit prose.4. **Note identity is brittle.** `permalink` is derived from title/path; renames create work (`update_permalinks_on_move` defaults to `False`, `config.py:349-352`). The 11-column `entity` table + separate `note_content` is a lot of machinery to keep in sync with files.5. **No agent/session model.** No notion of "who wrote this," "which session," or "what was the user's intent." `created_by` exists only for cloud auth (`knowledge.py:99-102`). For multi-agent handoffs, you'd want provenance baked in.6. **Search ranking is keyword-or-vector with a fixed `min_similarity=0.55`** (`config.py:307-312`). No recency/importance reranking, no usage feedback, no per-query learning.-7. **The Markdown source-of-truth tradeoff.** Filesystem latency, checksum recomputation, FTS5 rebuilds, and circuit-breaker retry tracking (`sync_service.py:179-281`) are a lot of infrastructure just to keep a DB consistent with files. For agent memory where the files exist only because LLMs wrote them, this is overhead with no payoff - keep the DB as primary and only export Markdown on demand.+7. **The Markdown source-of-truth tradeoff.** Filesystem latency, checksum recomputation, FTS5 rebuilds, and circuit-breaker retry tracking (`sync_service.py:179-281`) are a lot of infrastructure just to keep a DB consistent with files. For agent memory where the files exist only because LLMs wrote them, this is overhead with no payoff. Keep the DB as primary and only export Markdown on demand.8. **Tool surface is wide (~25 tools).** Agents have to pick among `write_note`/`edit_note`/`move_note`/`delete_note`/`read_note`/`view_note`/`read_content`/`search`/`search_notes`/`build_context`/`recent_activity`/`list_directory`/`list_memory_projects`/`canvas`/`schema_*`. Even with hints, that's a lot of context burned describing tools. Aim for a smaller, more orthogonal set.-**Bottom line**: borrow the *graph + observations + wiki-link* primitives, the *memory:// URI* navigation, the *typed-client + composition-root* layering, the *MCP annotations*, and the *file-as-portable-export* idea - but invert the capture model (ambient, not invoked), add a lifecycle (decay/consolidation/summarization), keep the DB primary, add agent/session provenance, and ship a much narrower MCP tool surface.+**Bottom line**: borrow the *graph + observations + wiki-link* primitives, the *memory:// URI* navigation, the *typed-client + composition-root* layering, the *MCP annotations*, and the *file-as-portable-export* idea, but invert the capture model (ambient, not invoked), add a lifecycle (decay/consolidation/summarization), keep the DB primary, add agent/session provenance, and ship a much narrower MCP tool surface.diff --git a/docs/research-codebase-memory-mcp.md b/docs/research-codebase-memory-mcp.mdindex e3c8e568..ed1f9d44 100644--- a/docs/research-codebase-memory-mcp.md+++ b/docs/research-codebase-memory-mcp.md@@ -1,45 +1,44 @@# codebase-memory-mcp — Research Report-*Repo:* <https://github.com/DeusData/codebase-memory-mcp> · MIT · pure **C**,-single static binary. *Snapshot:* 2026-09-03 — ~42k stars, ~3.4k forks,+*Repo:* <https://github.com/DeusData/codebase-memory-mcp> · MIT · pure C,+single static binary. *Snapshot:* 2026-09-03: ~42k stars, ~3.4k forks,created 2026-02, pushed daily. Preprint: *"Codebase-Memory: Tree-Sitter-BasedKnowledge Graphs for LLM Code Exploration via MCP"* (arXiv:2603.27277).-> **Category caveat, up front.** codebase-memory-mcp ("cbm") is **not a-> session-memory competitor** — it is *code-structure* memory. It answers-> *"what is this code and how does it connect?"*, ai-memory answers *"what did-> we do and decide, and why?"*. They are **complementary**: an agent can run-> both — cbm to navigate the code, ai-memory to recall the work. This report-> reads it for insights, not as a rival.+> **Category caveat.** codebase-memory-mcp ("cbm") is code-structure memory,+> so it does not compete with session memory. It answers *"what is this code+> and how does it connect?"*, while ai-memory answers *"what did we do and+> decide, and why?"*. An agent can run both: cbm to navigate the code,+> ai-memory to recall the work. This report reads cbm for ideas to borrow.## 1. Purpose & Scope*"The fastest and most efficient code intelligence engine for AI codingagents."* It parses a repository into a persistent knowledge graph so an agentcan ask structural questions (call chains, routes, impact of a change) with a-single graph query instead of dozens of grep/read cycles. Headline claim:-**~120× fewer tokens** — *"5 structural queries: ~3,400 tokens vs ~412,000 via-file-by-file search"* (99.2% reduction) — and it indexes the Linux kernel-(28M LOC) in ~3 minutes, answering Cypher queries in <1ms.+single graph query instead of dozens of grep/read cycles. The headline claim+is ~120× fewer tokens (*"5 structural queries: ~3,400 tokens vs ~412,000 via+file-by-file search"*, a 99.2% reduction). It also claims to index the Linux+kernel (28M LOC) in ~3 minutes and answer Cypher queries in <1ms.## 2. Architecture-- **Indexing:** multi-pass **tree-sitter** AST over 162 languages, plus a+- **Indexing:** multi-pass tree-sitter AST over 162 languages, plus a*"lightweight C implementation of language type-resolution algorithms"*("Hybrid LSP") that resolves imports/generics/inheritance/type inference- tree-sitter alone can't — structurally compatible with tsserver / pyright /+ tree-sitter alone can't. It is structurally compatible with tsserver / pyright /gopls / Roslyn / rust-analyzer but embedded and offline.- **Pipeline:** *"RAM-first: LZ4 compression, in-memory SQLite, fusedAho-Corasick pattern matching. Memory released after indexing."*-- **Storage:** **SQLite** at `~/.cache/codebase-memory-mcp/` (a familiar- choice — ai-memory is single-SQLite too).+- **Storage:** SQLite at `~/.cache/codebase-memory-mcp/` (ai-memory also uses+ a single SQLite database).- **Graph model:** nodes (Project, Package, File, Function, Class, Route, …)and edges (`CALLS`, `IMPORTS`, `IMPLEMENTS`, `HTTP_CALLS`, `DATA_FLOWS`,- `SIMILAR_TO`, `SEMANTICALLY_RELATED`), with **bundled `nomic-embed-code`- embeddings (768d int8) compiled into the binary** for `semantic_query`.+ `SIMILAR_TO`, `SEMANTICALLY_RELATED`), with bundled `nomic-embed-code`+ embeddings (768d int8) compiled into the binary for `semantic_query`.- **Zero runtime, zero network:** pure C, vendored grammars + embeddings- compiled in, *"makes no network request of its own accord"* — no telemetry,- no version check. All local.+ compiled in, *"makes no network request of its own accord"*: no telemetry+ and no version check. Everything runs locally.## 3. Agent Interface (15 MCP tools)@@ -54,118 +53,117 @@ classification), `semantic_query` (vector search over the graph),## 4. Freshness & Team Sharing-- **Auto-sync watcher** re-indexes on file change (`auto_watch` default true) —- the same "index stays live" instinct as ai-memory's wiki watcher.+- **Auto-sync watcher** re-indexes on file change (`auto_watch` default true),+ much like ai-memory's wiki watcher keeps its index live.- **Committed, compressed derived index:** *".codebase-memory/graph.db.zst isa zstd-compressed snapshot of the knowledge graph"* checked into the repo;new clones decompress and run incremental indexing instead of a fullreindex. Two-tier compression (`zstd -9` + `VACUUM INTO` on explicit index,`zstd -3` for the watcher's low-latency updates).- **Session-coordination daemon:** one per-account daemon shared across ~45- agent surfaces — first session starts it, each registers its work, last one- shuts it down.+ agent surfaces. The first session starts it, each session registers its work,+ and the last one shuts it down.## 5. Distinctive Ideas Worth Noting- **Committing a compressed *derived* index for team sharing** (`graph.db.zst`- in-repo). ai-memory deliberately keeps its DB derived/rebuildable and shares- through the **server** instead; cbm's git-artifact model is the offline,- server-less counterpart — a real trade-off to keep in mind (see the ECC and+ in-repo). ai-memory keeps its DB derived/rebuildable and shares through the+ server instead; cbm's git-artifact model is the offline, server-less+ alternative. The trade-off is worth keeping in mind (see the ECC andlandscape notes on git-shared vs server-mediated).-- **Multi-tier agent profiles** — auto-generated **Scout** (fast discovery) /- **Verify** (task-directed evidence) / **Auditor** (exhaustive) profiles,- each with an *"exact per-tier graph-tool list"* to **prevent- over-permissioning**. This is the most transferable idea: a principled way- to expose *different subsets* of tools to different task phases.-- **`detect_changes` → risk classification** — mapping a git diff to affected- symbols and a risk score. Adjacent to ai-memory's typed-edge/contradiction- lint, but over *code* rather than *knowledge*.-- **Token-efficiency as the headline metric**, benchmarked and published — the- same discipline ai-memory applies with LongMemEval; cbm makes "queries vs- grep tokens" its north star.+- **Multi-tier agent profiles**: auto-generated Scout (fast discovery) /+ Verify (task-directed evidence) / Auditor (exhaustive) profiles, each with+ an *"exact per-tier graph-tool list"* to prevent over-permissioning. This is+ the idea that transfers best: expose different subsets of tools to+ different task phases.+- **`detect_changes` → risk classification**: maps a git diff to affected+ symbols and a risk score. It resembles ai-memory's typed-edge/contradiction+ lint, applied to code instead of knowledge.+- **Token-efficiency as the headline metric**, benchmarked and published.+ ai-memory publishes LongMemEval numbers the same way; cbm's main metric is+ "queries vs grep tokens".## 6. What Good / What's Missing — Honest Take-**Not a competitor — a complement.** cbm indexes the *codebase*; ai-memory-indexes the *work*. The clean division of labour: cbm knows the code as it is-*right now*; ai-memory knows the decisions, gotchas, sessions, and handoffs —-the *why* and the *history* that no AST carries. An agent wanting both "where-is this function called" and "why did we build it this way" needs both tools.+**A complement, not a competitor.** cbm indexes the codebase; ai-memory+indexes the work. cbm knows the code as it is right now; ai-memory knows the+decisions, gotchas, sessions, and handoffs, which is the reasoning and history+no AST carries. An agent that needs both "where is this function called" and+"why did we build it this way" needs both tools.**Ideas ai-memory could borrow:**1. **Tiered tool exposure** (Scout/Verify/Auditor). ai-memory ships ~18 MCPtools to every client at every phase; a task-phase-scoped subset (e.g. aread-only "recall" tier vs a full "curate" tier) would cut prompt surface- and over-permissioning — worth considering alongside the rules-promotion+ and over-permissioning. Worth considering alongside the rules-promotionwork (`docs/design-rules-promotion.md`).2. **The token-efficiency framing** as a first-class, published metric for the*retrieval* side (ai-memory already benchmarks recall; "tokens to answer"is the complementary axis).3. **A committed, compressed derived-index option** for server-less small- teams — the same idea flagged in `research-ecc.md`'s git-shared team scope.+ teams, the same idea flagged in `research-ecc.md`'s git-shared team scope.**Where ai-memory is simply doing a different (harder-for-its-domain) job:**-- Automatic, sanitized **session capture** and cross-agent **handoff**; LLM- **consolidation** into human-readable knowledge; **temporal `as_of`**; a- **server** for multi-user/multi-machine. None of that is cbm's problem —- cbm never watches a session; it watches files.+- Automatic, sanitized session capture and cross-agent handoff; LLM+ consolidation into human-readable knowledge; temporal `as_of`; a server for+ multi-user/multi-machine use. cbm does none of that because it watches+ files, never sessions.-**Bottom line.** codebase-memory-mcp is an excellent, narrowly-scoped-code-intelligence engine and a natural companion to ai-memory rather than a-rival. Its best lessons for us are operational, not architectural: **tiered-tool profiles**, a **published token-efficiency metric**, and (optionally) a-**git-committed compressed index** for teams that won't run a server.+**Bottom line.** codebase-memory-mcp is a strong, narrowly scoped+code-intelligence engine that pairs well with ai-memory. The lessons for us+are operational rather than architectural: tiered tool profiles, a published+token-efficiency metric, and (optionally) a git-committed compressed index for+teams that won't run a server.## 7. 2.1 Feasibility — grounded in ai-memory's codeEach borrowable idea was checked against the current tree so the release call-rests on real choke points, not analogy. Verdicts: one **2.1 feature**, one-**land-now dev metric**, one **deferred design**.+rests on real choke points. Verdicts: one 2.1 feature, one land-now dev+metric, one deferred design.### 7.1 Tiered tool profiles — **recommend for 2.1**-*Where it plugs in.* The MCP server exposes **23 tools** through the rmcp+*Where it plugs in.* The MCP server exposes 23 tools through the rmcp`#[tool_router]` macro (`crates/ai-memory-mcp/src/server.rs:1239`), and-`list_tools` (`server.rs:3966`) is the **single choke point** — it returns+`list_tools` (`server.rs:3966`) is the single choke point. It returns`tool_router.list_all()` unfiltered, with only a per-dialect schema *reshape*(`restricted_schema_tool_list`, `server.rs:4021`) that never drops a tool. A-read/write partition **already exists**: `tool_call_is_write` (`server.rs:757`)+read/write partition already exists: `tool_call_is_write` (`server.rs:757`)classifies 8 tools as read-only (query, read_page, read_session_observations,-recent, briefing, explore, status, install_self_routing) — today used only for-rate-limit accounting, not visibility.+recent, briefing, explore, status, install_self_routing). Today it is used+only for rate-limit accounting, not visibility.-*Why 2.1.* 23 tools is heavy MCP prompt surface pushed to every client every-turn. A **read-only "recall" tier** (the 8 already-classified tools) versus the+*Why 2.1.* 23 tools is a heavy MCP prompt surface pushed to every client every+turn. A read-only "recall" tier (the 8 already-classified tools) versus thefull "curate" tier cuts prompt surface and over-permissioning for the commoncase (an agent that only *recalls* never needs `delete_page`/`forget_sweep`).-It is small, self-contained, and **pairs directly with the rules-promotion-work** (`docs/design-rules-promotion.md`) — both are about giving the agent-*less, better-scoped* authority by default.+The change is small and self-contained, and it pairs directly with the+rules-promotion work (`docs/design-rules-promotion.md`): both give the agent+less, better-scoped authority by default.*Shape.* Add a `--tool-profile recall|full` flag to `ServeArgs`(`crates/ai-memory-cli/src/cli.rs:2119`), or a per-request `?profile=` markermirroring the existing `?flavor=` mechanism (`server.rs:3980`); filter`list_all()` by `tool_call_is_write` before returning. No new classification-logic — the partition is already written.+logic is needed because the partition already exists.### 7.2 Token-efficiency metric — **land on main now (dev tooling, not a gated feature)**-*Where it plugs in.* The `evals/` crate measures **hit@k / recall@k only**+*Where it plugs in.* The `evals/` crate measures hit@k / recall@k only(`evals/src/retrieval/score.rs`). The full `memory_query` JSON payload is-already materialized in exactly one place before parsing —-`evals/src/retrieval/query.rs:114` (`text` holds the complete content string) —+already materialized in exactly one place before parsing,+`evals/src/retrieval/query.rs:114` (`text` holds the complete content string),so `text.len()` / a tokenizer pass yields a per-question "tokens to answer"-number with **zero server changes**, threaded into `report.rs`.+number with zero server changes, threaded into `report.rs`.*Why not gated to 2.1.* It changes no runtime behavior and ships nothing-user-facing — it is an eval/benchmark improvement that strengthens our-measurement story (the complement to LongMemEval recall: *recall* says we find-the answer, *tokens-to-answer* says we deliver it cheaply). It can go to `main`-as a quality improvement whenever, independent of the 2.1 train.+user-facing. It is an eval/benchmark improvement that complements LongMemEval+recall: *recall* says we find the answer, *tokens-to-answer* says we deliver it+cheaply. It can go to `main` at any time, independent of the 2.1 train.### 7.3 Committed compressed derived-index — **defer (design-only until a server-less use-case exists)**-*Where it plugs in.* The DB is **contractually derived and rebuildable**:+*Where it plugs in.* The DB is contractually derived and rebuildable:markdown-in-git is the source of truth, SQLite `db/` is the index(`crates/ai-memory-wiki/src/lib.rs:3`, `docs/companion-crates.md:14`), with aworking rebuild (`ai-memory reindex`, `crates/ai-memory-cli/src/commands/reindex.rs`)@@ -173,13 +171,13 @@ and an online-backup tarball producer (`POST /admin/backup`,`crates/ai-memory-mcp/src/admin.rs:746`). So a committed `graph.db.zst`-styleartifact *fits the model* mechanically.-*Why defer.* It is a **different distribution philosophy**, not a small-feature. ai-memory's multi-user/multi-machine story is deliberately-**server-mediated** (attributed writes, per-user scope, live handoff); a-git-committed binary index is the *server-less* counterpart, and it drags in+*Why defer.* It is a different distribution model and too large to count as+a small feature. ai-memory's multi-user/multi-machine story is server-mediated+by design (attributed writes, per-user scope, live handoff); a git-committed+binary index is the server-less counterpart, and it brings insnapshot-consistency, staleness, regeneration cadence, and binary-blob merge-conflicts. Building it before there is a concrete server-less-small-team-customer would be speculative — it belongs in the same "consider a git-shared+conflicts. Building it before there is a concrete server-less small-team+customer would be speculative. It belongs in the same "consider a git-sharedteam scope" bucket as `research-ecc.md` §8.4, to be designed only if that pathis chosen.@@ -193,4 +191,4 @@ is chosen.### Sources- <https://github.com/DeusData/codebase-memory-mcp> (README, metadata via GitHub API)-- Preprint arXiv:2603.27277 — *Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP*+- Preprint arXiv:2603.27277: *Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP*diff --git a/docs/research-cognee.md b/docs/research-cognee.mdindex bfe049ed..4f067a98 100644--- a/docs/research-cognee.md+++ b/docs/research-cognee.md@@ -1,7 +1,7 @@# cognee - Research Report-> **Follow-up:** the September 2026 landscape refresh — how this project-> evolved, what the field looks like now, and what we concluded — is in+> **Follow-up:** the September 2026 landscape refresh (how this project+> evolved, what the field looks like now, and what we concluded) is in> [`research-2026-landscape.md`](research-2026-landscape.md).@@ -9,11 +9,11 @@## 1. Purpose & Scope-Cognee bills itself as **"the brain behind your agents" - a memory control plane** (`README.md:40,67`). It ingests heterogeneous data (text, PDF, CSV, code, web pages), then continuously builds a hybrid **knowledge graph + vector index + relational catalog** so that agents can retrieve context by both meaning (embeddings) and structure (graph relationships). The current public SDK is intentionally minimal - four verbs: `remember`, `recall`, `forget`, `improve` (README L127). Internally, those map to the older `add`/`cognify`/`search`/`prune` primitives. Cognee positions itself between a RAG retriever and a "company brain," with multi-tenant isolation, ontology grounding, and a Claude Code plugin for capturing agent traces.+Cognee bills itself as "the brain behind your agents", a memory control plane (`README.md:40,67`). It ingests heterogeneous data (text, PDF, CSV, code, web pages), then continuously builds a hybrid knowledge graph + vector index + relational catalog so that agents can retrieve context by both meaning (embeddings) and structure (graph relationships). The current public SDK is intentionally minimal, with four verbs: `remember`, `recall`, `forget`, `improve` (README L127). Internally, those map to the older `add`/`cognify`/`search`/`prune` primitives. Cognee positions itself between a RAG retriever and a "company brain," with multi-tenant isolation, ontology grounding, and a Claude Code plugin for capturing agent traces.## 2. The Cognify Pipeline (heart of the system)-The pipeline is composed as a **list of `Task` objects** executed by `run_pipeline`. Canonical definition at `cognee/api/v1/cognify/cognify.py:316-344`:+The pipeline is a list of `Task` objects executed by `run_pipeline`. Canonical definition at `cognee/api/v1/cognify/cognify.py:316-344`:```pythondefault_tasks = [@@ -29,18 +29,18 @@ Step-by-step:1. **Classify documents** (`cognee/tasks/documents/classify_documents.py`). Wraps each raw `Data` row in a typed `Document` subclass (`PdfDocument`, `TextDocument`, `DltRowDocument`, etc.) so downstream chunkers know how to read content.-2. **Chunk documents** (`cognee/tasks/documents/extract_chunks_from_documents.py` + `cognee/modules/chunking/TextChunker.py:1-60`). The default `TextChunker` uses `chunk_by_paragraph` to pack paragraphs up to `max_chunk_size` tokens (calculated as `min(embedding_max_completion_tokens, llm_max_completion_tokens // 2)`). Each chunk becomes a `DocumentChunk` DataPoint with `metadata={"index_fields": ["text"]}` - those `index_fields` are how the storage layer later knows what to embed.+2. **Chunk documents** (`cognee/tasks/documents/extract_chunks_from_documents.py` + `cognee/modules/chunking/TextChunker.py:1-60`). The default `TextChunker` uses `chunk_by_paragraph` to pack paragraphs up to `max_chunk_size` tokens (calculated as `min(embedding_max_completion_tokens, llm_max_completion_tokens // 2)`). Each chunk becomes a `DocumentChunk` DataPoint with `metadata={"index_fields": ["text"]}`; the storage layer later reads those `index_fields` to know what to embed.3. **Extract graph + summarize** (`cognee/tasks/graph/extract_graph_and_summarize.py:21-37`). Two LLM tasks concurrently on every chunk via `asyncio.gather`:- - `extract_graph_from_data` (`cognee/tasks/graph/extract_graph_from_data.py:128-222`) calls `extract_content_graph(chunk.text, graph_model, custom_prompt)` for each chunk - an `instructor`/`litellm`-backed structured call that returns a Pydantic `KnowledgeGraph` of `Node`/`Edge`. Edges with missing source/target are filtered (L181-188). Entity nodes are then validated against an ontology via `expand_with_nodes_and_edges(..., ontology_resolver, ...)` (L110-112). Provenance is stamped onto every DataPoint (`_stamp_provenance_deep`, L30-53). Existing edges are deduplicated via `retrieve_existing_edges`.+ - `extract_graph_from_data` (`cognee/tasks/graph/extract_graph_from_data.py:128-222`) calls `extract_content_graph(chunk.text, graph_model, custom_prompt)` for each chunk, an `instructor`/`litellm`-backed structured call that returns a Pydantic `KnowledgeGraph` of `Node`/`Edge`. Edges with missing source/target are filtered (L181-188). Entity nodes are then validated against an ontology via `expand_with_nodes_and_edges(..., ontology_resolver, ...)` (L110-112). Provenance is stamped onto every DataPoint (`_stamp_provenance_deep`, L30-53). Existing edges are deduplicated via `retrieve_existing_edges`.- `summarize_text` produces a `TextSummary` for each chunk used by later "SUMMARIES" search.4. **Persist nodes, edges & embeddings** (`cognee/tasks/storage/add_data_points.py:30-149`). `get_graph_from_model` recursively walks the Pydantic graph into `(nodes, edges)` tuples, then `deduplicate_nodes_and_edges` removes duplicates. The pipeline branches on `EngineCapability.HYBRID_WRITE`:- Hybrid backend (e.g. Postgres+pgvector): `graph_engine.add_nodes_with_vectors(nodes)` in one transaction.- Otherwise, parallel writes: `graph_engine.add_nodes(nodes)` + `index_data_points(...)` to the vector engine.- - If `embed_triplets=True`, builds `(source -› relation -› target)` text strings and embeds them as additional `Triplet` DataPoints (L184-265). This is what makes graph-walk retrieval finable by similarity.+ - If `embed_triplets=True`, builds `(source -› relation -› target)` text strings and embeds them as additional `Triplet` DataPoints (L184-265). This makes graph-walk retrieval findable by similarity.-5. **DLT FK edges** - adds deterministic foreign-key edges for ingested SQL/DLT-backed datasets without LLM cost.+5. **DLT FK edges**: adds deterministic foreign-key edges for ingested SQL/DLT-backed datasets without LLM cost.There's also a parallel **temporal** pipeline (`cognify.py:347-392`) that swaps the graph extractor for `extract_events_and_timestamps` → `extract_knowledge_graph_from_events` to build a time-aware graph.@@ -54,59 +54,59 @@ Cognee always uses three stores in parallel, abstracted by a `UnifiedStoreEngine| **Vector** | `lancedb` (file-based, subprocess-isolated) | `pgvector`, `chromadb`, `neptune_analytics` || **Relational** | `sqlite` (aiosqlite) | `postgres` via SQLAlchemy async |-Selection is **environment-driven**: `GRAPH_DATABASE_PROVIDER`, `VECTOR_DB_PROVIDER`, `DB_PROVIDER`, with normalized credentials. There is also a `USE_UNIFIED_PROVIDER=pghybrid` short-circuit that makes a single Postgres instance back graph+vector+relational simultaneously.+Selection is environment-driven: `GRAPH_DATABASE_PROVIDER`, `VECTOR_DB_PROVIDER`, `DB_PROVIDER`, with normalized credentials. There is also a `USE_UNIFIED_PROVIDER=pghybrid` short-circuit that makes a single Postgres instance back graph+vector+relational simultaneously.Two `EngineCapability` flags (`HYBRID_WRITE`, `HYBRID_SEARCH`) let the pipeline branch on whether nodes+vectors can land in one transaction (saves a round trip) or need two writes.-The default local-only stack is therefore: **SQLite + LanceDB + Ladybug/Kuzu**, all file-based - no servers required. For homelab parity, that's the lean setup.+The default local-only stack is therefore SQLite + LanceDB + Ladybug/Kuzu, all file-based, with no servers required. For homelab parity, that's the lean setup.## 4. Search / Retrieval-Recall is **multi-strategy and auto-routed**. `SearchType` enum (`cognee/modules/search/types/SearchType.py`) lists 16 strategies: `GRAPH_COMPLETION` (default), `GRAPH_COMPLETION_COT`, `GRAPH_COMPLETION_CONTEXT_EXTENSION`, `GRAPH_COMPLETION_DECOMPOSITION`, `GRAPH_SUMMARY_COMPLETION`, `RAG_COMPLETION`, `TRIPLET_COMPLETION`, `CHUNKS`, `CHUNKS_LEXICAL`, `SUMMARIES`, `CYPHER`, `NATURAL_LANGUAGE`, `TEMPORAL`, `FEELING_LUCKY`, `CODING_RULES`, `AGENTIC_COMPLETION`.+Recall is multi-strategy and auto-routed. `SearchType` enum (`cognee/modules/search/types/SearchType.py`) lists 16 strategies: `GRAPH_COMPLETION` (default), `GRAPH_COMPLETION_COT`, `GRAPH_COMPLETION_CONTEXT_EXTENSION`, `GRAPH_COMPLETION_DECOMPOSITION`, `GRAPH_SUMMARY_COMPLETION`, `RAG_COMPLETION`, `TRIPLET_COMPLETION`, `CHUNKS`, `CHUNKS_LEXICAL`, `SUMMARIES`, `CYPHER`, `NATURAL_LANGUAGE`, `TEMPORAL`, `FEELING_LUCKY`, `CODING_RULES`, `AGENTIC_COMPLETION`.-The `recall()` API (`cognee/api/v1/recall/recall.py:314-513`) picks one via `route_query(query_text)` - a **rule-based classifier** in `query_router.py` (regex patterns for "when/before/after" → `TEMPORAL`, keyword fragments → `CHUNKS_LEXICAL`, multi-hop wording → `GRAPH_COMPLETION_COT`, etc.). Default fallback is `GRAPH_COMPLETION`.+The `recall()` API (`cognee/api/v1/recall/recall.py:314-513`) picks one via `route_query(query_text)`, a rule-based classifier in `query_router.py` (regex patterns for "when/before/after" → `TEMPORAL`, keyword fragments → `CHUNKS_LEXICAL`, multi-hop wording → `GRAPH_COMPLETION_COT`, etc.). Default fallback is `GRAPH_COMPLETION`.-The flagship retriever is `GraphCompletionRetriever` (`cognee/modules/retrieval/graph_completion_retriever.py`). It uses **`brute_force_triplet_search`** (`cognee/modules/retrieval/utils/brute_force_triplet_search.py:216-355`), which:+The main retriever is `GraphCompletionRetriever` (`cognee/modules/retrieval/graph_completion_retriever.py`). It uses `brute_force_triplet_search` (`cognee/modules/retrieval/utils/brute_force_triplet_search.py:216-355`), which:-1. Embeds the query, runs **vector search across multiple collections in parallel**: `Entity_name`, `TextSummary_text`, `EntityType_name`, `DocumentChunk_text`, `EdgeType_relationship_name` (L281-290).+1. Embeds the query, runs vector search across multiple collections in parallel: `Entity_name`, `TextSummary_text`, `EntityType_name`, `DocumentChunk_text`, `EdgeType_relationship_name` (L281-290).2. Projects results into a `CogneeGraph` memory fragment, scoring triplets by combined node+edge similarity with `triplet_distance_penalty` and `feedback_influence` (L318-333).3. Optionally expands a `neighborhood_depth` hop-out from top seed nodes.4. Resolves the top-K edges to natural-language sentences (`resolve_edges_to_text`).5. Feeds them into an LLM completion with `graph_context_for_question.txt` as the user prompt.-Recall also supports **session-cache first-pass** (keyword match against recent QA entries in a relational session table) with **fall-through to graph** when no session hit (`recall.py:382-397, 447-457`). That's the "hybrid working-memory + long-term memory" pattern.+Recall also supports a session-cache first pass (keyword match against recent QA entries in a relational session table) and falls through to the graph when the session has no hit (`recall.py:382-397, 447-457`). That's the "hybrid working-memory + long-term memory" pattern.## 5. Memory Lifecycle - Cognee Does Reorganize-Cognee has explicit **memory enrichment** beyond one-shot ingest. The `improve()` API (`cognee/api/v1/improve/improve.py:36-232`) runs up to five stages:+Cognee has explicit memory enrichment beyond one-shot ingest. The `improve()` API (`cognee/api/v1/improve/improve.py:36-232`) runs up to five stages:-1. **Feedback weights**: session entries with thumbs-up/down ratings adjust `feedback_weight` on the **specific graph nodes/edges that were used** to answer (`apply_feedback_weights_pipeline`, L284-299). Tracked via `used_graph_element_ids` recorded at retrieval time. Higher-rated answers boost their source nodes; lower-rated ones decrease them.+1. **Feedback weights**: session entries with thumbs-up/down ratings adjust `feedback_weight` on the specific graph nodes/edges that were used to answer (`apply_feedback_weights_pipeline`, L284-299). Tracked via `used_graph_element_ids` recorded at retrieval time. Higher-rated answers boost their source nodes; lower-rated ones decrease them.2. **Persist session Q&A**: cognifies session transcripts into permanent graph tagged `node_set="user_sessions_from_cache"`.3. **Triplet enrichment / memify**: `cognee/memify_pipelines/create_triplet_embeddings.py` builds and embeds new triplet datapoints.4. **Global context index**: `global_context_index_pipeline` builds bucket+root summaries over all text summaries.5. **Sync graph→session**: incrementally copies recently-added graph edges into session caches as JSON-lines so live agents pick up new knowledge without a re-query.-There's also a **`consolidate_entity_descriptions.py`** pipeline (`cognee/memify_pipelines/consolidate_entity_descriptions.py`) that walks Entity nodes, fetches neighbors+edges, and rewrites their `description` field via an LLM (`NodeDescription` Pydantic). And `apply_frequency_weights.py` ages knowledge by usage frequency. Deduplication happens at write time in `add_data_points.py` and at extraction time in `retrieve_existing_edges`.+There's also a `consolidate_entity_descriptions.py` pipeline (`cognee/memify_pipelines/consolidate_entity_descriptions.py`) that walks Entity nodes, fetches neighbors+edges, and rewrites their `description` field via an LLM (`NodeDescription` Pydantic). And `apply_frequency_weights.py` ages knowledge by usage frequency. Deduplication happens at write time in `add_data_points.py` and at extraction time in `retrieve_existing_edges`.-So: **not one-shot.** There's a clear feedback loop, summary consolidation, and edge-aging concept. There is no automatic decay/TTL, but `feedback_weight` and `frequency_weight` give you the levers.+So ingest is not one-shot. There is a feedback loop, summary consolidation, and an edge-aging concept. There is no automatic decay/TTL, but `feedback_weight` and `frequency_weight` give you the levers.## 6. MCP Integration-Yes, in `cognee-mcp/` as a sibling project with its own pyproject. The server (`cognee-mcp/src/server.py`) uses the official `mcp` SDK over stdio/SSE/HTTP. The **publicly exposed tools are deliberately minimal** (L1076-1222):+Yes, in `cognee-mcp/` as a sibling project with its own pyproject. The server (`cognee-mcp/src/server.py`) uses the official `mcp` SDK over stdio/SSE/HTTP. The publicly exposed tools are deliberately minimal (L1076-1222):-- `remember(data, dataset_name?, session_id?, custom_prompt?)` - with `session_id`, fast session-cache write; without, runs full `add + cognify` pipeline.-- `recall(query, search_type?, datasets?, session_id?, top_k=10)` - auto-routes search type.-- `forget(dataset?, everything=False)` - deletes across all three stores.+- `remember(data, dataset_name?, session_id?, custom_prompt?)`: with `session_id`, a fast session-cache write; without, runs the full `add + cognify` pipeline.+- `recall(query, search_type?, datasets?, session_id?, top_k=10)`: auto-routes the search type.+- `forget(dataset?, everything=False)`: deletes across all three stores.There are *internal* tools registered but not exposed in API mode: `cognify`, `search`, `list_data`, `delete`, `prune`, `improve`, plus a UI bundle (`visualize_graph_ui`, `upload_file_ui`, `open_cognee_workspace`, `cognify_file`) that opens an embedded HTML workspace from `src/app_bundles/visualize-graph.html`.-**Notable design choice**: per-MCP-client auto-named datasets (`cursor_vscode_memory`, `claude_code_memory`) so different agents don't pollute each other's memory unless they opt in by passing `dataset_name="main_dataset"`. Toggle with `COGNEE_MCP_AGENT_SCOPED=false`.+One design choice worth noting: per-MCP-client auto-named datasets (`cursor_vscode_memory`, `claude_code_memory`) so different agents don't pollute each other's memory unless they opt in by passing `dataset_name="main_dataset"`. Toggle with `COGNEE_MCP_AGENT_SCOPED=false`.-MCP integration is **manual** in the sense that the agent invokes `remember`/`recall` explicitly. The Claude Code plugin (separate repo `cognee-integrations`) automates it via Claude Code lifecycle hooks (`SessionStart`, `PostToolUse`, `UserPromptSubmit`, `PreCompact`, `SessionEnd`) - see README L204.+MCP integration is manual in the sense that the agent invokes `remember`/`recall` explicitly. The Claude Code plugin (separate repo `cognee-integrations`) automates it via Claude Code lifecycle hooks (`SessionStart`, `PostToolUse`, `UserPromptSubmit`, `PreCompact`, `SessionEnd`); see README L204.## 7. Operational Concerns-**Deployment**: A top-level `Dockerfile` builds the FastAPI server; `cognee-mcp/Dockerfile` builds the MCP server. `docker-compose.yml` ships the API on port 8000 with **resource limits of 4 CPUs and 8 GB RAM** - non-trivial. Deployment targets include Cognee Cloud, Modal, Railway, Fly.io, Render, Daytona (`distributed/deploy/`).+**Deployment**: A top-level `Dockerfile` builds the FastAPI server; `cognee-mcp/Dockerfile` builds the MCP server. `docker-compose.yml` ships the API on port 8000 with resource limits of 4 CPUs and 8 GB RAM, which is a lot. Deployment targets include Cognee Cloud, Modal, Railway, Fly.io, Render, Daytona (`distributed/deploy/`).**LLM cost per ingest**: heavy. For *every* chunk, cognify runs:- 1 structured-extraction call (entity/relationship → Pydantic KnowledgeGraph)@@ -117,33 +117,33 @@ A 100-chunk document easily generates 200+ LLM calls plus hundreds of embeddings**What needs API keys**: `LLM_API_KEY` is mandatory unless you point at a local Ollama/HuggingFace model via the `ollama`/`huggingface` extras. Default provider is OpenAI (`openai>=1.80.1` is a core dep). Defaults to its own embedding model via `litellm`.-**Local-only stack**: SQLite + LanceDB + Ladybug means **no external services** for the storage layer, but the LLM is the cost driver. Replacing OpenAI with Ollama makes it CPU/GPU-heavy but free.+**Local-only stack**: SQLite + LanceDB + Ladybug means no external services for the storage layer, but the LLM is the cost driver. Replacing OpenAI with Ollama makes it CPU/GPU-heavy but free.## 8. Strongest Ideas to Adopt-1. **Task-list pipeline composition.** `cognify.py:316-344` reads like a data-flow recipe. Each `Task` is a thin wrapper with a `batch_size` config and a context object. This is the cleanest pattern to port to Rust - represent the pipeline as a typed `Vec<Box<dyn Task>>` and let tasks declare their batching behavior.+1. **Task-list pipeline composition.** `cognify.py:316-344` reads like a data-flow recipe. Each `Task` is a thin wrapper with a `batch_size` config and a context object. This is the cleanest pattern to port to Rust: represent the pipeline as a typed `Vec<Box<dyn Task>>` and let tasks declare their batching behavior.-2. **Triplet embeddings as first-class citizens.** Embedding `(source -› relation -› target)` text directly (`add_data_points.py:184-265`) is the trick that lets a graph become searchable by semantic similarity, by walking. This is genuinely the bridge between "vector RAG" and "graph RAG."+2. **Triplet embeddings as first-class citizens.** Embedding `(source -› relation -› target)` text directly (`add_data_points.py:184-265`) lets a graph become searchable by semantic similarity, by walking. It bridges "vector RAG" and "graph RAG."3. **Capability-flag-driven storage facade.** `UnifiedStoreEngine.has_capability(HYBRID_WRITE)` lets the same pipeline target separate `(Kuzu, LanceDB)` or fused `(Postgres+pgvector)` without conditionals scattered everywhere.-4. **`improve()` lifecycle with feedback weights.** The `feedback_weight` on graph elements + `used_graph_element_ids` from the retrieval trace is a sharp idea - it gives you graded knowledge without retraining anything.+4. **`improve()` lifecycle with feedback weights.** The `feedback_weight` on graph elements + `used_graph_element_ids` from the retrieval trace gives you graded knowledge without retraining anything.-5. **Multi-collection vector search at recall time.** Querying `Entity_name`, `TextSummary_text`, `DocumentChunk_text`, and edge collections in parallel and merging by triplet score, rather than picking one index, is the core retrieval move.+5. **Multi-collection vector search at recall time.** Querying `Entity_name`, `TextSummary_text`, `DocumentChunk_text`, and edge collections in parallel and merging by triplet score, rather than picking one index, is the core of retrieval.-6. **Provenance stamping** (`_stamp_provenance_deep`) - every DataPoint carries `source_pipeline` + `source_task`, making the graph debuggable.+6. **Provenance stamping** (`_stamp_provenance_deep`): every DataPoint carries `source_pipeline` + `source_task`, making the graph debuggable.## 9. Realistic Downsides for a Lean Homelab-- **Dependency weight**: 40+ core dependencies - `openai`, `litellm`, `instructor`, `sqlalchemy`, `aiosqlite`, `lancedb`, `pylance`, `ladybug`, `networkx`, `pypdf`, `fastapi`, `fastapi-users`, `rdflib`, `langdetect`, `datamodel-code-generator`, `tiktoken`, `tenacity`, `aiolimiter`, `diskcache`, `fakeredis`, plus optional extras (neo4j, chromadb, postgres, anthropic, ollama, huggingface, scraping, dlt, monitoring). Cold install is huge - `poetry.lock` is **1.4 MB**.-- **Python async everywhere + LRU-cached engine handles** (`closing_lru_cache`) - debugging stale-adapter issues required adding `_GraphEngineHandle` (see the 50-line docstring at `get_graph_engine.py:56-105`). That's complexity you inherit.-- **Per-cognify LLM cost** is high. There's no obvious caching of "I've already extracted entities from this chunk hash" - re-ingestion repeats work. `incremental_loading=True` helps but only at the dataset level.+- **Dependency weight**: 40+ core dependencies (`openai`, `litellm`, `instructor`, `sqlalchemy`, `aiosqlite`, `lancedb`, `pylance`, `ladybug`, `networkx`, `pypdf`, `fastapi`, `fastapi-users`, `rdflib`, `langdetect`, `datamodel-code-generator`, `tiktoken`, `tenacity`, `aiolimiter`, `diskcache`, `fakeredis`, plus optional extras (neo4j, chromadb, postgres, anthropic, ollama, huggingface, scraping, dlt, monitoring)). Cold install is huge: `poetry.lock` is 1.4 MB.+- **Python async everywhere + LRU-cached engine handles** (`closing_lru_cache`): debugging stale-adapter issues required adding `_GraphEngineHandle` (see the 50-line docstring at `get_graph_engine.py:56-105`). That's complexity you inherit.+- **Per-cognify LLM cost** is high. There's no obvious caching of "I've already extracted entities from this chunk hash", so re-ingestion repeats work. `incremental_loading=True` helps but only at the dataset level.- **Three databases to back up**, three to migrate. The "wipe `.cognee_system/` when you flip `ENABLE_BACKEND_ACCESS_CONTROL`" caveat (cognee-mcp/README L518-525) shows the multi-store coordination is fragile.- **8 GB RAM limit** in docker-compose is the recommended floor. LanceDB + Kuzu + embedding model loaded simultaneously is heavy on a low-end NAS.-- **Bus factor on `ladybug`** - a 0.16.0 pinned Kuzu fork by the same org. If they stop maintaining it, you're on a single-vendor graph DB.+- **Bus factor on `ladybug`**: a 0.16.0 pinned Kuzu fork by the same org. If they stop maintaining it, you're on a single-vendor graph DB.- **Two-tier MCP API**: public 3 tools + 10+ "internal" tools means the API surface is in motion; not stable.-For a Rust homelab MCP server, the **lean equivalents** would be: SQLite (relational) + a single embedded vector store (e.g. `lancedb-rs` or embedded `sqlite-vec`) + an embedded graph DB (CozoDB, SurrealDB, or just SQL tables with proper indices) - then port the *task pipeline + triplet embedding + capability flag pattern* and skip the FastAPI/users/migrations/UI bundle stack entirely.+For a Rust homelab MCP server, the lean equivalents would be SQLite (relational) + a single embedded vector store (e.g. `lancedb-rs` or embedded `sqlite-vec`) + an embedded graph DB (CozoDB, SurrealDB, or just SQL tables with proper indices). Then port the task pipeline + triplet embedding + capability flag pattern and skip the FastAPI/users/migrations/UI bundle stack entirely.### Key file referencesdiff --git a/docs/research-ecc.md b/docs/research-ecc.mdindex 999f72f5..146739a5 100644--- a/docs/research-ecc.md+++ b/docs/research-ecc.md@@ -1,17 +1,17 @@# ECC — Research Report*Repo:* <https://github.com/affaan-m/ECC> · MIT · primarily JavaScript/TypeScript-(with Python, Go, Shell). *Snapshot:* 2026-09-03 — ~247k stars, ~37k forks,+(with Python, Go, Shell). *Snapshot:* 2026-09-03: ~247k stars, ~37k forks,created 2026-01, pushed daily. One of the most-starred AI-agent repos onGitHub, single-maintainer-led with an active contributor community.> **Category caveat, up front.** ECC is **not** a memory backend like-> ai-memory. It bills itself as *"the agent harness operating system"* — a+> ai-memory. It bills itself as *"the agent harness operating system"*, a> plan → test → implement → review → verify → **remember** → improve loop> installed once into a coding agent (Claude Code, Codex, OpenCode, Cursor,> Gemini, Zed, …) as skills, subagents, rules, hooks, and MCP wiring. Memory> is one pillar among Skills, Instincts, Security, and Research-first-> development — not the product. So this report compares only the overlapping+> development, not the product itself. This report compares only the overlapping> surface (its memory / continuous-learning component) and mines it for> insights, rather than treating ECC as a like-for-like competitor.@@ -21,14 +21,14 @@ ECC's pitch: *"Your agent can write code, but ECC gives it a coordinatedengineering system and toolbox: it plans before it builds, verifies changeswith tests, reviews its own work from a fresh context, remembers whatmatters, and turns repeated wins into reusable skills and workflows."* The-memory value prop is captured in one line — **"Optimize the context window.-Persist everything else."** — which is exactly ai-memory's own reason to-exist. Where ai-memory *is* the "persist everything else" layer, ECC ships a-lightweight version of it inside a much larger workflow framework.+memory value prop fits in one line, **"Optimize the context window.+Persist everything else."**, which is also ai-memory's reason to exist.+ai-memory *is* the "persist everything else" layer; ECC ships a lightweight+version of it inside a much larger workflow framework.ai-memory is the deeper, dedicated memory system; ECC is the broader agent-scaffolding with a shallow-but-opinionated memory slice. They are adjacent,-not substitutes.+scaffolding with a shallow-but-opinionated memory slice. The two sit next to+each other and do not replace one another.## 2. Architecture@@ -38,9 +38,9 @@ not substitutes.tracking and session recording; git distributes config.- **Hook-driven persistence.** PreToolUse / PostToolUse / Stop hooks(`hooks/hooks.json`, with `ECC_HOOK_PROFILE=minimal|standard|strict`- runtime gating) capture session summaries and learned patterns — the same- lifecycle-hook capture spine ai-memory uses, but writing local files rather- than posting to a server.+ runtime gating) capture session summaries and learned patterns. This is the+ same lifecycle-hook capture approach ai-memory uses, but it writes local+ files instead of posting to a server.- **Skills / Agents / Rules.** ~286 Markdown "skills" (workflows loaded ondemand), ~68 subagents with isolated context + scoped tool permissions, andalways-loaded language/framework "rules" packs. This is a governance layer@@ -48,33 +48,33 @@ not substitutes.Contrast: ai-memory is a single-writer SQLite + wiki-git **server** with areal retrieval engine (FTS5 + vector + entity + graph, fused by RRF) and an-OKF-portable on-disk format; ECC is a distributed pile of Markdown + a+OKF-portable on-disk format; ECC is a distributed set of Markdown files + aSQLite side-table, retrieved by search over active files.## 3. Memory Model-- **Format:** `ecc.memory.v1` Markdown documents — portable and inspectable- (same instinct as ai-memory's OKF-v0.2 human-readable wiki).+- **Format:** `ecc.memory.v1` Markdown documents, portable and inspectable+ (the same idea as ai-memory's OKF-v0.2 human-readable wiki).- **Scopes:** project / team / user. The **team scope is version-controlled- and shared through git** — a genuinely different multi-user story than+ and shared through git**, a different multi-user approach fromai-memory's server-mediated workspaces (see §6).-- **Capture:** semi-manual — `ecc memory save`, `ecc memory handoff`- (`--stdin` / `--body-file`) — plus hook-driven session summaries. This is+- **Capture:** semi-manual (`ecc memory save`, `ecc memory handoff`,+ `--stdin` / `--body-file`) plus hook-driven session summaries. This isthe biggest divergence: ai-memory's capture is **automatic andzero-ceremony** (every prompt/tool/session boundary sanitized and stored bylifecycle hooks with no `save` call), whereas ECC leans on explicit savecommands for durable notes and reserves automation for summaries.- **Retrieval:** `ecc memory search "query"` over active memories, and`ecc memory doctor` for vault integrity. No evidence of hybrid- vector/entity/graph retrieval or temporal (`as_of`) queries — it appears to+ vector/entity/graph retrieval or temporal (`as_of`) queries. It appears tobe text search over a curated file set, which is adequate for a small,human-pruned vault but not for a large auto-captured corpus.## 4. Consolidation & Continuous Learning ("Instincts")ECC's "Continuous Learning v2" extracts **instincts with confidence-scoring** from session patterns — *"instinct-based learning with confidence-scoring, import/export, evolution"* — and can promote recurring wins into+scoring** from session patterns (*"instinct-based learning with confidence+scoring, import/export, evolution"*) and can promote recurring wins intogenerated skills. This maps closely to ai-memory's session-end consolidation+ auto-improve loop, with two notable differences:@@ -84,7 +84,7 @@ generated skills. This maps closely to ai-memory's session-end consolidationimplicit; surfacing a per-page/per-rule confidence would be a cheap,legible upgrade.2. **Promotion to skills, not just recall.** ECC turns repeated patterns into- *executable* skills/workflows, not only retrievable notes — a stronger+ *executable* skills/workflows, not only retrievable notes. That is a stronger"learning produces behavior" story than ai-memory's "learning producesbetter recall."@@ -92,34 +92,34 @@ generated skills. This maps closely to ai-memory's session-end consolidation- **"Memory is unreviewed context, not executable policy. Verify importantclaims against authoritative sources and promote accepted knowledge into- governed project documentation."** This is the sharpest idea in the repo. It- draws a hard line between *raw captured memory* (untrusted, for context)+ governed project documentation."** This is the most useful idea in the repo.+ It draws a hard line between *raw captured memory* (untrusted, for context)and *governed knowledge* (reviewed, promoted into rules the agent obeys).-- **AgentShield** — a bundled security scanner that audits harness config,+- **AgentShield**: a bundled security scanner that audits harness config,hooks, MCP definitions, agent files, permissions, and secrets(`ecc-agentshield scan --path .`). ai-memory has a security-audit *skill*but ships no scanner for the hook/MCP config it writes.-- **Plan Canvas** — browser review of implementation plans (Mermaid- diagrams, approval gates). Orthogonal to memory, but a nice human-in-the-+- **Plan Canvas**: browser review of implementation plans (Mermaid+ diagrams, approval gates). Unrelated to memory, but a useful human-in-the-loop surface.-- **Research-first development** — source-verification baked into the flow+- **Research-first development**: source-verification baked into the flowbefore knowledge is trusted.## 6. Cross-Agent / Multi-User-ECC's **team memory is git-shared Markdown** — every teammate pulls the same+ECC's **team memory is git-shared Markdown**: every teammate pulls the samecommitted vault. ai-memory instead mediates multi-user/multi-machine througha **server** (attributed writes, per-user scoping, live sync acrossmachines). ECC's model is simpler and offline-friendly but has git'smerge/conflict story and no live cross-session handoff; ai-memory's is richer(real-time handoff, attribution, one store many machines) at the cost of-running a server. Different trade-offs for different teams.+running a server. Which one fits depends on the team.## 7. What's Good / What's Missing — Honest Take**What ECC does better (or at least differently, worth stealing):**- The **memory-vs-governed-knowledge distinction** as a first-class- principle. ai-memory already gestures at this (the lint pass suggests+ principle. ai-memory already hints at this (the lint pass suggests"this looks like a durable rule — copy it into CLAUDE.md/AGENTS.md"), butECC makes *promotion* an explicit, designed path. ai-memory could formalizea **promotion flow**: memory page → reviewed → emitted as a governed@@ -127,15 +127,15 @@ running a server. Different trade-offs for different teams.hints at.- **Explicit confidence scores** on learned knowledge (cheap legibility win).- **A bundled config scanner** (AgentShield analogue) for the hooks/MCP- ai-memory itself installs — the data-layer audit this project just ran by+ ai-memory itself installs. The data-layer audit this project just ran byhand could become a shippable `ai-memory audit-config`.- **Learning that produces behavior** (instincts → skills), not just recall.**Where ai-memory is clearly ahead (for the memory problem specifically):**- **Automatic, zero-ceremony capture** vs ECC's `ecc memory save`. ai-memorynever asks the agent to remember to persist.-- **A real retrieval engine** — hybrid FTS5 + vector + entity + graph RRF,- temporal `as_of`, benchmarked on LongMemEval-S (hit@5 0.62 → 0.82) — vs+- **A real retrieval engine** (hybrid FTS5 + vector + entity + graph RRF,+ temporal `as_of`, benchmarked on LongMemEval-S, hit@5 0.62 → 0.82) vstext search over an active file set.- **Scale of corpus.** ai-memory is built to auto-capture and retrieve overthousands of pages and hundreds of thousands of observations; ECC's vault@@ -143,8 +143,8 @@ running a server. Different trade-offs for different teams.- **Server-mediated multi-user, temporal windows, OKF portability, andeval-gated consolidation.**-**Bottom line.** ECC is not a memory competitor — it's an agent-harness OS-whose memory is deliberately thin ("optimize the context window, persist+**Bottom line.** ECC is an agent-harness OS rather than a memory competitor,+and its memory is deliberately thin ("optimize the context window, persisteverything else; keep memory as context, not policy"). Its best lesson forai-memory is *governance*: the explicit line between raw memory and promoted,reviewed, agent-obeyed knowledge, plus confidence scoring and a config@@ -157,9 +157,9 @@ scanner. Its capture and retrieval are well behind ai-memory's, by design.reviewed-and-emitted governance artifact.2. **Surface confidence** on consolidated pages / auto-improve proposals(already eval-gated internally; make it legible in `status`/`memory_query`).-3. **`ai-memory audit-config`** — a shippable scanner for the hook/MCP config+3. **`ai-memory audit-config`**: a shippable scanner for the hook/MCP configai-memory writes (AgentShield analogue), built from the data-layer auditwork already done.4. **Consider a lightweight git-shared "team rules" scope** for offline/small- teams that don't want to run the server — complementary to, not a- replacement for, the server model.+ teams that don't want to run the server, as a complement to the server+ model rather than a replacement.diff --git a/docs/research-hindsight.md b/docs/research-hindsight.mdindex 7e724176..b5cb6051 100644--- a/docs/research-hindsight.md+++ b/docs/research-hindsight.md@@ -3,159 +3,160 @@> Source project: `vectorize-io/hindsight` (Python/Node/Go, PostgreSQL+pgvector,> MCP-native, LLM-required). MIT, ~23.5K stars, ~2,970 commits, production at> named enterprises, a preprint paper (arXiv:2512.12818), and a LongMemEval-> claim of 91.4%. Studied as the **best-funded, paper-backed, benchmark-leading-> competitor to date** - and, importantly, as an *independent* implementation+> claim of 91.4%. We studied it as the best-funded, paper-backed,+> benchmark-leading competitor to date, and as an *independent* implementation> of two bets we already made (pages-over-facts; auto-rewritten wiki pages of-> settled knowledge). A follow-up to the September 2026 landscape+> settled knowledge). This is a follow-up to the September 2026 landscape> ([`research-2026-landscape.md`](research-2026-landscape.md)); the landscape's> camps table and its R2/R5 recommendations are updated there to name this-> project. Same lens as the rest: what it does, what is worth borrowing, what to-> deliberately avoid. Every load-bearing claim was checked against the repo, the-> paper, or a primary announcement in September 2026, not remembered.+> project. The lens is the same as the rest: what it does, what is worth+> borrowing, what to avoid. Every claim the conclusions depend on was checked+> against the repo, the paper, or a primary announcement in September 2026,+> not remembered.## 1. Purpose & Scope-Hindsight is an **agent memory system built "to create smarter agents that-learn over time"** - the pitch leans hard on *learn*, not *store*. Its+Hindsight is an agent memory system built "to create smarter agents that+learn over time". The pitch leans on *learn* more than *store*. Itsorganizing metaphor is biomimetic: four "logical networks" that separate whatthe world is, what the agent did, what it has concluded, and what it nowbelieves. It is MCP-native, LLM-required, and packaged for everything from a2-line Docker run to a managed SaaS with a 99.9% SLA. Vectorize (the company)positions it enterprise-first (Fortune 500 references, Kubernetes Helm charts,-Oracle 23ai parity), which is the opposite end of the deployment spectrum from+Oracle 23ai parity), the opposite end of the deployment spectrum fromour single self-contained homelab binary.-The reason it matters to us is not the enterprise packaging. It is that-Hindsight independently arrived at **markdown "mental model" pages that a-background process continuously rewrites as the agent learns** - which is our-`wiki/` + auto-improve loop under a different name - and then went further into-the cross-session abstraction layer our own landysc research flagged as the-open frontier (R5). It is the strongest existing prior art for where we said we-want to go, from a team that published a paper and a benchmark to back it.+It matters to us because Hindsight independently arrived at markdown "mental+model" pages that a background process continuously rewrites as the agent+learns. That is our `wiki/` + auto-improve loop under a different name. It then+went further into the cross-session abstraction layer our own landscape+research flagged as the open frontier (R5). It is the strongest existing prior+art for where we said we want to go, from a team that published a paper and a+benchmark to back it.## 2. Storage Model-**A database, not files, as source of truth** - the inverse of our substrate+The source of truth is a database, not files, the inverse of our substrateand of basic-memory's. Storage backends:- **PostgreSQL + pgvector** (primary).- **Oracle AI Database 23ai** (enterprise-parity option).- **Embedded `pg0`** (a bundled Postgres so the Python `hindsight-all` package- has no external DB dependency - their answer to our "single binary, no- services" property, achieved by embedding Postgres rather than SQLite).+ has no external DB dependency). This is their answer to our "single binary,+ no services" property, achieved by embedding Postgres rather than SQLite.-Memory is represented as **"entities, relationships, and time series with-sparse/dense vector representations"** - i.e. a temporal, entity-aware layer+Memory is represented as "entities, relationships, and time series with+sparse/dense vector representations": a temporal, entity-aware layerover Postgres, with both BM25-sparse and dense vectors materialized. On top of-that raw layer sit the **four biomimetic tiers**, which are the actual product+that raw layer sit the four biomimetic tiers, which are the actual productabstraction:-1. **World facts** - static, provider-independent knowledge ("Paris is in+1. **World facts**: static, provider-independent knowledge ("Paris is inFrance").-2. **Experiences** - the agent's own interaction trajectories (what happened,+2. **Experiences**: the agent's own interaction trajectories (what happened,turn by turn). This is the *narrative/trajectory* tier the "Storage →Reflection → Experience" survey (`research-2026-landscape.md` §4) names, madefirst-class.-3. **Observations** - *consolidated, evidence-backed beliefs*. Each carries- provenance: quotes and a **proof count**, so a belief's strength is the- weight of evidence behind it, not a single write.-4. **Mental models** - *learned understanding synthesized from observations*,- stored as **living markdown "knowledge pages" that a background process- auto-rewrites** as the bank accumulates evidence. These are "standing+3. **Observations**: consolidated, evidence-backed beliefs. Each carries+ provenance, namely quotes and a proof count, so a belief's strength is the+ weight of evidence behind it rather than a single write.+4. **Mental models**: learned understanding synthesized from observations,+ stored as living markdown "knowledge pages" that a background process+ auto-rewrites as the bank accumulates evidence. These are "standinganswers": an agent "can boot with a page of settled knowledge instead ofrediscovering it every session."-Tier 4 is the one to sit with. Structurally it is *our wiki page*, and the+Tier 4 deserves the most attention. Structurally it is *our wiki page*, and the"auto-rewritten as the bank learns" mechanism is *our auto-improve/consolidationloop*. Two independent teams, from opposite substrates (they DB-first, usfile-first), converged on "the durable unit of agent memory is acontinuously-maintained markdown page of settled knowledge, not a pile of atomicfacts." That convergence is the strongest external validation of our core bet in-this whole research series - stronger than a listicle or a star count, because-it is a competitor's *architecture* agreeing, backed by a benchmark.+this research series. It counts for more than a listicle or a star count,+because a competitor's *architecture* agrees with it and a benchmark backs it.## 3. Capture / Ingestion-Hindsight offers a spectrum, anchored on an explicit `retain()` API call and-climbing toward automatic:+Hindsight offers several capture paths, from an explicit `retain()` API call+up to automatic capture:-- **`retain()`** - the manual API. Behind it, **an LLM extracts "key facts,+- **`retain()`**: the manual API. Behind it, an LLM extracts "key facts,temporal data, entities, and relationships" through a normalization- pipeline.** Every retain is therefore an LLM call.-- **LLM Wrapper** - transparently wraps the OpenAI / Anthropic SDKs (and 100++ pipeline, so every retain is an LLM call.+- **LLM Wrapper**: transparently wraps the OpenAI / Anthropic SDKs (and 100+models via LiteLLM); once wrapped, "memories are then stored and retrieved- automatically on every call." This is a **fundamentally different capture- surface from ours**: they intercept the *model API call itself*; we intercept+ automatically on every call." This capture surface differs from ours at the+ root: they intercept the *model API call itself*, and we interceptthe *agent harness lifecycle* (hooks). Theirs captures any app that routesthrough the SDK, at the cost of being in the inference path and coupled to theLLM provider. Ours captures tool/session/prompt events harness-side, workswith zero LLM, and never sits in the model call path.-- **IDE / coding-agent auto-ingestion** from **git history and past sessions** -+- **IDE / coding-agent auto-ingestion** from git history and past sessions,a coding-agent specialization that seeds a bank from the repo's history.- **MCP server** exposes `retain` as a tool.-The load-bearing difference: **capture requires an LLM.** There is no rule-based-or zero-LLM path. Every memory written pays an extraction-LLM call. Our+The main difference is that capture requires an LLM. There is no rule-based+or zero-LLM path, and every memory written pays for an extraction-LLM call. Ourzero-LLM default (capture + FTS + rule-based summaries with no provider) has no-analogue here - which is precisely the homelab/offline segment Hindsight cedes.+analogue here, and that homelab/offline segment is the one Hindsight cedes.## 4. Retrieval-Four strategies run **in parallel**, then fuse:+Four strategies run in parallel, then fuse:-- **Semantic** - dense-vector similarity.-- **Keyword** - BM25 exact matching.-- **Graph** - entity / temporal / causal link traversal.-- **Temporal** - explicit time-range filtering (`recall("What happened in+- **Semantic**: dense-vector similarity.+- **Keyword**: BM25 exact matching.+- **Graph**: entity / temporal / causal link traversal.+- **Temporal**: explicit time-range filtering (`recall("What happened inJune?")`).-Merged via **reciprocal rank fusion + a cross-encoder reranking model.** This is-the same shape as ours (RRF over multiple streams, optional rerank) with two-streams we treat differently: their "graph" stream traverses typed-entity/causal edges as a first-class retriever, and their "temporal" stream is a-dedicated time-range filter rather than a decay weighting. Our recent+Results are merged via reciprocal rank fusion plus a cross-encoder reranking+model. This is the same shape as ours (RRF over multiple streams, optional+rerank), with two streams we treat differently: their "graph" stream traverses+typed entity/causal edges as a first-class retriever, and their "temporal"+stream is a dedicated time-range filter rather than a decay weighting. Our recentbi-temporal work (`docs/temporal.md`, the `as_of` FTS stream on `release/2.2`)is the closest we have to their temporal retriever; their causal-graph stream isthe direction our typed-edges thread (`fixes`/`causes`/`contradicts`) points at.## 5. Memory Lifecycle - Consolidation over Replacement-This is Hindsight's sharpest idea and its clearest lesson for us.+This is Hindsight's best idea and the clearest lesson for us.-**Memory does not overwrite. "New information strengthens, weakens or extends an-existing belief instead of silently replacing it."** An observation is an+Memory does not overwrite: "New information strengthens, weakens or extends an+existing belief instead of silently replacing it." An observation is anevidence-backed belief with a proof count; corrections adjust the belief's-weight and lineage rather than deleting the prior version. Mental-model pages are-**rewritten continuously "as the bank learns more"** by a background process --consolidation is a standing job, not a per-write action.--Compare to us: our pages **supersede** (the loser stays reachable in a-supersession chain; invariant #16), which is corrections-as-versions. Hindsight-adds a dimension we do not have: **belief *strength* as an accumulating,-evidence-weighted quantity**, with the supporting quotes and a proof count-attached. "The team decided against a queue" is not just the latest page; it is a-belief with N pieces of evidence behind it, and a contradicting sighting-*weakens* it rather than replacing the page. That is a richer model than binary-supersession, and it is exactly the substrate a `contradicts` edge + a lint pass-wants (our R3). Worth noting the failure mode too: an evidence-weighted belief+weight and lineage rather than deleting the prior version. A background process+rewrites mental-model pages continuously "as the bank learns more", so+consolidation is a standing job rather than a per-write action.++Our pages **supersede** instead (the loser stays reachable in a+supersession chain; invariant #16), which treats corrections as versions.+Hindsight adds a dimension we do not have: belief *strength* as an accumulating,+evidence-weighted quantity, with the supporting quotes and a proof count+attached. "The team decided against a queue" is a belief with N pieces of+evidence behind it, beyond being the latest page, and a contradicting sighting+*weakens* it rather than replacing the page. That model is richer than binary+supersession, and it is the substrate a `contradicts` edge + a lint pass+wants (our R3). It has a failure mode too: an evidence-weighted beliefstore can entrench a popular-but-wrong belief (many weak confirmations-outvoting one correct correction) - a known risk their "disposition traits"-(below) gesture at but do not obviously solve.+outvoting one correct correction). Their "disposition traits" (below) gesture+at this risk but do not obviously solve it.## 6. Isolation Model - "Banks" (and why #708 should read this)-A **bank** is "an isolated memory store - one 'brain' for one user, agent, or+A bank is "an isolated memory store - one 'brain' for one user, agent, orproject. Isolation is strict: no cross-bank leakage." This is the **opposite ofour core bet.** Our invariant #16 makes pages *shared* within a project acrosssessions and users on purpose (team continuity); owner-scoping applies only to-handoff batons. Hindsight chose strict per-bank isolation and gave up the-in-project team-sharing story to get a simpler tenancy boundary.+handoff batons. Hindsight chose strict per-bank isolation and gave up+in-project team sharing to get a simpler tenancy boundary.-The timely connection: **issue #708** ("multi-user servers have no per-project-authorization") is asking us to add exactly a bank-like isolation boundary+This bears directly on **issue #708** ("multi-user servers have no per-project+authorization"), which asks us to add a bank-like isolation boundary*above* our shared-within-project model. Hindsight's bank is the prior art for-that design - one brain per (user | agent | project), strict no-leakage - and-its choice is instructive: they get tenant isolation for free but cannot do+that design: one brain per (user | agent | project), with strict no-leakage. Its+choice is instructive. They get tenant isolation for free but cannot doin-project multi-user collaboration, which is our differentiator. The #708 designshould be "grants that gate *which projects a user can see at all*, above theshared-within-a-granted-project model," i.e. a bank boundary layered on top of@@ -168,17 +169,17 @@ Hindsight's per-bank keying needs.**LLM required** for retain (extraction) and reflect (synthesis). 25+ providers:hosted (OpenAI, Anthropic, Gemini, Groq, Bedrock, Vertex, Deepseek, Meta),local (Ollama, LM Studio, llama.cpp), gateways (LiteLLM/Router, any-OpenAI-compatible endpoint), and - notably - **existing subscriptions with no+OpenAI-compatible endpoint), and **existing subscriptions with noAPI key** (ChatGPT Plus, Claude Pro, GitHub Copilot). That last one is a real-onboarding advantage worth borrowing conceptually: we already support Copilot-and Anthropic-OAuth tokens; framing "use the subscription you already pay for,-no API key" as a first-class install path (rather than a buried option) is a-low-cost positioning win.+onboarding advantage worth borrowing as an idea. We already support Copilot+and Anthropic-OAuth tokens; presenting "use the subscription you already pay+for, no API key" as a first-class install path (rather than a buried option)+would cost little and help positioning.-But the hard requirement is the story: **there is no zero-LLM Hindsight.** Turn+The hard requirement matters more: **there is no zero-LLM Hindsight.** Turnthe provider off and it does not capture. Our default path (capture, FTS search,-rule-based summaries, all with no provider) is the segment they structurally-cannot serve.+rule-based summaries, all with no provider) serves a segment their design+cannot.## 8. Deployment, Packaging, Privacy@@ -188,28 +189,28 @@ cannot serve.`hindsight-api` server), Node (`@vectorize-io/hindsight-client`), Go, a CLI,and a built-in MCP server at `http://localhost:8888/mcp/{bank_id}/` exposing`retain`/`recall`/`reflect`.-- **60+ integrations** - coding agents (Claude Code, Cursor, Copilot, Cline,+- **60+ integrations**: coding agents (Claude Code, Cursor, Copilot, Cline,Aider), frameworks (LangGraph, LlamaIndex, CrewAI, Pydantic AI), no-code (n8n,Zapier, Dify, Flowise). This breadth is a company-scale investment we will notand should not match; our integration story is depth on the coding-agent- lifecycle, not breadth across no-code platforms.-- **Memory Defense** - an *optional, per-bank* policy that scans retains against- **45 patterns** for secrets/PII and can **redact** (`[REDACTED:github_token]`,- a *typed* redaction label) or **block** outright. This is a more configurable- version of our sanitizer (invariant #6): ours is a fixed built-in trust- boundary on the hook path; theirs is per-scope-configurable with a- redact-vs-block choice and typed redaction labels. The **typed label**- (`[REDACTED:<what>]` instead of a blanket mask) is the borrowable detail - it- preserves that *a* github token was there without leaking it, which is more- useful for later reading than an anonymous `***`.-- **Multilingual by default** - input language detected and preserved end to+ lifecycle rather than breadth across no-code platforms.+- **Memory Defense**: an *optional, per-bank* policy that scans retains against+ 45 patterns for secrets/PII and can **redact** (`[REDACTED:github_token]`,+ a *typed* redaction label) or **block** outright. It is a more configurable+ version of our sanitizer (invariant #6). Ours is a fixed built-in trust+ boundary on the hook path; theirs is configurable per scope, with a+ redact-vs-block choice and typed redaction labels. The typed label+ (`[REDACTED:<what>]` instead of a blanket mask) is the detail to borrow. It+ records that *a* github token was there without leaking it, which helps a+ later reader more than an anonymous `***`.+- **Multilingual by default**: input language detected and preserved end toend.## 9. The Benchmark Claim - Read Skeptically (per the mempalace lesson)-The paper - **"Hindsight is 20/20: Building Agent Memory that Retains, Recalls,-and Reflects"** (Latimer, Boschi, Neeser, Bartholomew, Srivastava, Wang,-Ramakrishnan; arXiv:2512.12818, **preprint**, submitted 2025-12-14) - reports:+The paper, "Hindsight is 20/20: Building Agent Memory that Retains, Recalls,+and Reflects" (Latimer, Boschi, Neeser, Bartholomew, Srivastava, Wang,+Ramakrishnan; arXiv:2512.12818, **preprint**, submitted 2025-12-14), reports:- **LongMemEval: 91.4%** accuracy (scaled backbone) vs **39%** full-contextbaseline. Sub-scores show where structure helps most: multi-session@@ -217,94 +218,94 @@ Ramakrishnan; arXiv:2512.12818, **preprint**, submitted 2025-12-14) - reports:**60.3% → 84.6%**.- **LoCoMo: 89.61%** vs 75.78% for the strongest prior open system.-Two things are genuinely better than the mempalace pattern the landscape flagged+Two things put it ahead of the mempalace pattern the landscape flagged(§2, the ~47K-star system whose headline number reproduced with the architecture-*inactive*): Hindsight published a **paper with per-category sub-scores** (not a-single cherry-picked figure), and the gains concentrate exactly where a+*inactive*). Hindsight published a paper with per-category sub-scores instead+of a single cherry-picked figure. And the gains concentrate where astructured temporal memory *should* help (multi-session, temporal,-knowledge-update) rather than uniformly, which is the signature of a real+knowledge-update) rather than appearing uniformly, which points to a realmechanism rather than a lucky default.-But apply the same skepticism the landscape earned:+The same skepticism the landscape applied still holds:- **"Independently reproduced by Virginia Tech and The Washington Post" is notarms-length.** Wang and Ramakrishnan (two of the seven authors) are VirginiaTech Sanghani Center faculty; the Post is a named development collaborator.The reproduction is by the *co-developing* institutions, which is more than- self-report but is not third-party. The claim should be cited as "reproduced+ self-report but is not third-party. Cite the claim as "reproducedby the collaborating labs," not "independently verified."- It is a **preprint**, not peer-reviewed.- LongMemEval numbers here are **accuracy**, not the R@5 retrieval metric othersystems in our series report (agentmemory 0.967 R@5, mcp-memory-service 80.4%),- so the 91.4% is not directly comparable to those - a reason our own R2 harness- must fix a metric and a split, not quote a competitor's.+ so the 91.4% is not directly comparable to those. This is one reason our own+ R2 harness must fix a metric and a split instead of quoting a competitor's.-Net: it is the most *credible* memory-benchmark claim in this research series-(paper + sub-scores + a plausible mechanism), and simultaneously a reminder that-the serious players now ship papers - which raises the bar our R2 gap sits under.+Overall, it is the most credible memory-benchmark claim in this research series+(paper + sub-scores + a plausible mechanism). It also shows that the serious+players now ship papers, which raises the bar for our open R2 gap.## 10. Disposition Traits - Flagged as Possible Metaphor-Driven Cruft-Banks carry **"disposition traits" (skepticism, literalism, empathy)** that+Banks carry "disposition traits" (skepticism, literalism, empathy) that"shape how reflect reasons." Treat this with mempalace-grade suspicion until the-paper's ablation says otherwise. It is exactly the kind of anthropomorphic+paper's ablation says otherwise. It is the kind of anthropomorphicflourish that reads well in a launch post and may or may not move a retrievalnumber; the burden of proof is an ablation showing traits-on beats traits-off on-a held-out split. Absent that, it is a prompt-flavoring knob dressed as an+a held-out split. Without that, it is a prompt-flavoring knob presented asarchitecture, and the landscape's mempalace conclusion applies: metaphor is not-retrieval architecture. (The one place it *could* be load-bearing is the-entrenchment failure mode of §5 - a "skeptical" disposition that discounts weak-repeated confirmations - but the docs don't claim that mechanism explicitly.)+retrieval architecture. (The one place it *could* matter is the+entrenchment failure mode of §5, where a "skeptical" disposition would discount+weak repeated confirmations, but the docs don't claim that mechanism explicitly.)## 11. Strengths Worth Borrowing1. **"Mental models" as continuously-rewritten markdown pages of settledknowledge.** This is our wiki + auto-improve, validated by an independent,- benchmark-backed competitor. The specific thing to study: they make the+ benchmark-backed competitor. What to study: they make the*standing-answer page* a first-class tier an agent boots from, and rewrite itas a background job across accumulated evidence. That is our open R5- (cross-session abstraction) with a shipped reference implementation - read+ (cross-session abstraction) with a shipped reference implementation, so readtheir reflect loop before designing ours.2. **Consolidation as belief-strength, not just supersession.** Evidence-backed- observations with quotes + a proof count, where new evidence- strengthens/weakens/extends rather than replaces. Richer than our binary- supersession, and the natural substrate for the `contradicts` lint (R3) and- temporal validity (R4). Consider a "confidence/evidence-count" field on- pages or entity-links.+ observations carry quotes and a proof count, and new evidence+ strengthens, weakens, or extends them rather than replacing them. This is+ richer than our binary supersession, and the natural substrate for the+ `contradicts` lint (R3) and temporal validity (R4). Consider a+ "confidence/evidence-count" field on pages or entity-links.3. **Typed redaction labels in the sanitizer.** `[REDACTED:github_token]`- instead of an anonymous mask - preserves *what kind* of secret was present+ instead of an anonymous mask keeps *what kind* of secret was presentfor the later reader without leaking it. A one-line refinement to oursanitizer boundary.4. **Four parallel retrieval streams with an explicit causal-graph retriever.**- Their graph stream traverses `causes`/typed edges as a retrieval path, not- just for display. Validates the typed-edges direction (R3) as *retrieval*- value, not only lint value.+ Their graph stream traverses `causes`/typed edges as a retrieval path, beyond+ display. This shows the typed-edges direction (R3) has *retrieval*+ value as well as lint value.5. **"Use the subscription you already pay for" as a headline install path.** Wesupport Copilot/Anthropic-OAuth already; promoting "no API key, use your- Claude Pro / Copilot" to a first-class onboarding line is free positioning.+ Claude Pro / Copilot" to a first-class onboarding line costs nothing.6. **Bank isolation as prior art for #708.** A clean, documented per-(user |- agent | project) tenancy boundary to design our authorization against -- adopting the *boundary* while keeping our shared-within-project collaboration+ agent | project) tenancy boundary to design our authorization against.+ Adopt the *boundary* while keeping our shared-within-project collaboration(which they gave up).## 12. Weaknesses / Friction (Avoid)-1. **LLM-required capture.** No zero-LLM path; every write costs an extraction- call. This is the segment we own by construction - do not follow them into- provider-mandatory capture.-2. **Postgres-primary, DB-as-source-of-truth.** Heavier substrate (pgvector, or- an embedded Postgres, or Oracle), enterprise/K8s-shaped. Our single- self-contained binary with files as source of truth stays the homelab- differentiator; the "embedded pg0 so there's no external dependency" move is- them working to recover a property we get for free.+1. **LLM-required capture.** There is no zero-LLM path; every write costs an+ extraction call. We own this segment by construction, so do not follow them+ into provider-mandatory capture.+2. **Postgres-primary, DB-as-source-of-truth.** The substrate is heavier+ (pgvector, or an embedded Postgres, or Oracle) and shaped for enterprise/K8s.+ Our single self-contained binary with files as source of truth stays the+ homelab differentiator; the "embedded pg0 so there's no external dependency"+ move is them working to recover a property we get for free.3. **Strict bank isolation loses in-project team memory.** Their simplicitycosts the multi-user-within-a-project collaboration that is our invariant#16. When #708 adds authorization, layer a bank-like boundary *above*sharing; do not replace sharing with isolation.-4. **Disposition traits** - unproven metaphor-as-architecture until an ablation+4. **Disposition traits**: unproven metaphor-as-architecture until an ablationsays otherwise (§10). Do not add "personality" knobs without a held-outnumber.-5. **Benchmark framing** - "independently reproduced" by co-developers, a+5. **Benchmark framing**: "independently reproduced" by co-developers, apreprint, accuracy-not-R@5. A caution for how *we* report R2: fix the metricand split, publish the harness, never a bare number.6. **60+ integration breadth** is a company-scale surface. Depth on the coding@@ -312,8 +313,8 @@ repeated confirmations - but the docs don't claim that mechanism explicitly.)## 13. Bottom Line-Hindsight is the most serious competitor in this series and, usefully, it agrees-with us where it matters: **the durable unit of agent memory is a+Hindsight is the most serious competitor in this series, and it agrees+with us on the main point: **the durable unit of agent memory is acontinuously-maintained markdown page of settled knowledge, not a bag of atomicfacts.** Two teams from opposite substrates converged there, and theirs has apaper and a benchmark. That is the strongest external validation of our core bet@@ -321,15 +322,15 @@ we have logged.Borrow four concrete things: **belief-strength/evidence-count consolidation**(richer than our supersession, feeds R3/R4), **typed redaction labels**, the-**causal-graph retriever** as evidence that typed edges pay off in retrieval not-just lint, and their **reflect loop as the reference implementation for our open-R5** (cross-session abstraction). Read their **bank model as prior art for+**causal-graph retriever** as evidence that typed edges pay off in retrieval as+well as lint, and their **reflect loop as the reference implementation for our+open R5** (cross-session abstraction). Read their **bank model as prior art for#708**, adopting the isolation boundary while keeping our shared-within-projectcollaboration. And let their **paper sharpen R2**: the serious players nowpublish audited-ish numbers, we publish none, and "experienced colleague overlong horizons" is still literally our pitch.-Deliberately do **not** follow them into: LLM-required capture (we own zero-LLM),+Do **not** follow them into LLM-required capture (we own zero-LLM),a Postgres/enterprise substrate (single binary is the homelab win), strictisolation *instead of* sharing (invariant #16 is the team story), orpersonality/disposition knobs without an ablation (the mempalace lesson holds).@@ -345,7 +346,7 @@ personality/disposition knobs without an ablation (the mempalace lesson holds)."Vectorize Breaks 90% on LongMemEval with Open-Source AI Agent Memory System";VentureBeat "With 91% accuracy, open source Hindsight ...".- Independent-reproduction claim: attributed to Virginia Tech Sanghani Center- for AI and Data Analytics + The Washington Post - **noted as co-developing+ for AI and Data Analytics + The Washington Post, **noted as co-developingcollaborators, not arms-length third parties** (two paper authors are VTSanghani faculty).- Cross-references: `research-2026-landscape.md` (camps table, R2/R5),diff --git a/docs/research-karpathy-llm-wiki.md b/docs/research-karpathy-llm-wiki.mdindex b5964a35..6b944cc9 100644--- a/docs/research-karpathy-llm-wiki.md+++ b/docs/research-karpathy-llm-wiki.md@@ -1,7 +1,7 @@# Karpathy's "LLM Wiki" - Research Report-> **Follow-up:** the September 2026 landscape refresh — how this project-> evolved, what the field looks like now, and what we concluded — is in+> **Follow-up:** the September 2026 landscape refresh, covering how this+> project evolved, what the field looks like now, and what we concluded, is in> [`research-2026-landscape.md`](research-2026-landscape.md).@@ -10,7 +10,7 @@## 1. What Karpathy Actually Said-The canonical primary source is Karpathy's April 2026 gist [`llm-wiki.md`](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f), which he calls an **"idea file"** - explicitly *not* a library or app, but a pattern designed to be copy-pasted into an agent (Claude Code, Codex, OpenCode) so the agent can instantiate it for the user's domain.+The canonical primary source is Karpathy's April 2026 gist [`llm-wiki.md`](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f), which he calls an "idea file". He is explicit that it is not a library or app. It is a pattern designed to be copy-pasted into an agent (Claude Code, Codex, OpenCode) so the agent can instantiate it for the user's domain.The original framing came from an X thread on April 2, 2026, paraphrased as: *"using LLMs to build personal knowledge bases for various topics of research interest"*. He followed up two days later with the gist. He then [boosted "Farzapedia"](https://x.com/karpathy/status/2040572272944324650) as a good example of the pattern in the wild.@@ -24,7 +24,7 @@ The original framing came from an X thread on April 2, 2026, paraphrased as: *"u> "The tedious part of maintaining a knowledge base is not the reading or the thinking — it's the bookkeeping... LLMs don't get bored, don't forget to update a cross-reference, and can touch 15 files in one pass."-He explicitly links the idea to Vannevar Bush's 1945 Memex - "a personal, curated knowledge store with associative trails between documents" - arguing the part Bush couldn't solve was *who does the maintenance*; LLMs solve that.+He explicitly links the idea to Vannevar Bush's 1945 Memex ("a personal, curated knowledge store with associative trails between documents"), arguing that the part Bush couldn't solve was *who does the maintenance*, and that LLMs solve it.## 2. The Core Principles@@ -32,9 +32,9 @@ From the gist itself (Karpathy's, not paraphrased):1. **Compilation, not retrieval.** Knowledge is compiled at ingest time, not re-synthesized at query time. The wiki is the artifact; raw sources are the source of truth.2. **Three-layer architecture.**- - **Raw sources** - immutable; LLM reads only.- - **Wiki** - markdown files; LLM owns and maintains entirely.- - **Schema** (CLAUDE.md / AGENTS.md) - conventions that turn "a generic chatbot into a disciplined wiki maintainer."+ - **Raw sources**: immutable; LLM reads only.+ - **Wiki**: markdown files; LLM owns and maintains entirely.+ - **Schema** (CLAUDE.md / AGENTS.md): conventions that turn "a generic chatbot into a disciplined wiki maintainer."3. **Three operations: Ingest / Query / Lint.**- *Ingest*: one source typically touches **10–15 wiki pages**.- *Query*: "good answers can be filed back into the wiki as new pages... explorations compound in the knowledge base just like ingested sources do."@@ -47,16 +47,16 @@ From the gist itself (Karpathy's, not paraphrased):The community frequently attributes a few additional ideas to him that are **paraphrase / extension**, not in his gist:-- **Episodic vs. semantic memory tiers** - neuroscience framing. Not in the gist. This comes from extensions like [LLM Wiki v2](https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2) and the broader memory-research literature.-- **"Sleep-like" consolidation passes** - also extension framing, not Karpathy's. His closest analog is the *Lint* operation (periodic health-check), which is rule-based rather than dream-like.-- **Confidence scoring, Ebbinghaus decay, supersession semantics** - these are LLM Wiki v2's additions, not the original.-- **The numbered "1. Explicit. 2. ..." Farzapedia points** - community summaries say Karpathy listed several advantages of *explicit memory artifacts* over the "AI that allegedly gets better the more you use it" status quo. Flagged as **community paraphrase**.+- **Episodic vs. semantic memory tiers**: neuroscience framing. Not in the gist. This comes from extensions like [LLM Wiki v2](https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2) and the broader memory-research literature.+- **"Sleep-like" consolidation passes**: also extension framing, not Karpathy's. His closest analog is the *Lint* operation (periodic health-check), which is rule-based rather than dream-like.+- **Confidence scoring, Ebbinghaus decay, supersession semantics**: these are LLM Wiki v2's additions, not the original.+- **The numbered "1. Explicit. 2. ..." Farzapedia points**: community summaries say Karpathy listed several advantages of *explicit memory artifacts* over the "AI that allegedly gets better the more you use it" status quo. Flagged as **community paraphrase**.## 3. Implementation Hints from the Gist- **Trigger**: human-in-the-loop on ingest ("I prefer to ingest sources one at a time and stay involved"), though batch ingestion is allowed.- **Format**: plain markdown in a git repo. Optional YAML frontmatter for Dataview queries.-- **Retrieval at small scale**: `index.md` is "surprisingly good... at ~100 sources, ~hundreds of pages" - no embeddings needed.+- **Retrieval at small scale**: `index.md` is "surprisingly good... at ~100 sources, ~hundreds of pages", with no embeddings needed.- **Retrieval at larger scale**: shell out to a local hybrid search tool (he names [`qmd`](https://github.com/tobi/qmd), BM25 + vector + LLM re-rank, available as CLI and MCP).- **Tooling**: Obsidian as the viewer (graph view to spot orphan/hub pages), Web Clipper to capture sources, version-controlled in git.@@ -64,25 +64,25 @@ The community frequently attributes a few additional ideas to him that are **par- **MemGPT / Letta** ([letta.com](https://www.letta.com/blog/benchmarking-ai-agent-memory)): treats the context window as virtual memory; the *agent itself* decides what to page in/out across core, recall, and archival tiers. Stronger on long-horizon episodic coherence; higher lock-in (owns the agent loop).- **Mem0** ([tokenmix.ai comparison](https://tokenmix.ai/blog/ai-agent-memory-mem0-vs-letta-vs-memgpt-2026)): lightweight memory layer with `extract / store / retrieve`. Extracts memories *passively* from conversations rather than letting the agent self-edit. Low lock-in.-- **A-MEM** ([arXiv 2502.12110](https://arxiv.org/abs/2502.12110), NeurIPS 2025): explicitly Zettelkasten-inspired. Each memory is an atomic note with structured attributes, keywords, tags; new memories trigger *evolution* of existing notes' representations. This is the closest published research analog to Karpathy's wiki - atomic notes + automatic linking + revision propagation.-- **ReadAgent** (Google DeepMind, 2024): "gist memory" - compresses long contexts into a tree of summaries with pointers back to detail. Different angle (long-document reading), but shares the "compile, don't re-retrieve" instinct.+- **A-MEM** ([arXiv 2502.12110](https://arxiv.org/abs/2502.12110), NeurIPS 2025): explicitly Zettelkasten-inspired. Each memory is an atomic note with structured attributes, keywords, tags; new memories trigger *evolution* of existing notes' representations. This is the closest published research analog to Karpathy's wiki: atomic notes + automatic linking + revision propagation.+- **ReadAgent** (Google DeepMind, 2024): "gist memory", which compresses long contexts into a tree of summaries with pointers back to detail. Different angle (long-document reading), but shares the "compile, don't re-retrieve" instinct.- **LLM Wiki v2** (Rohit Ghumare): explicit extension with confidence scores, supersession, Ebbinghaus decay, four consolidation tiers (working → episodic → semantic → procedural), event-driven hooks, audit trails. This is basically the agentmemory model.- **Rowboat / knowledge-graph extension** ([dailydoseofds.com](https://blog.dailydoseofds.com/p/the-next-step-after-karpathys-wiki)): argues the wiki of summaries breaks down for evolving work contexts (deadlines, commitments) and proposes a *typed-entity knowledge graph* (decisions, people, projects as nodes).## 5. Design Implications for a Rust MCP Server for Coding Agents-Translating Karpathy faithfully - a "Karpathy-style" backend looks very different from naive vector RAG:+Translated faithfully, a "Karpathy-style" backend looks very different from naive vector RAG:**What it is, concretely:**- **Storage = markdown files in a git repo**, not opaque vector blobs. The wiki must be human-inspectable and grep-able. Embeddings can index it but never replace it.- **Three directories enforced by the MCP server**: `raw/` (append-only, immutable), `wiki/` (LLM-writable, structured), and a schema doc (`AGENTS.md`-style) the server injects into every session.-- **MCP tools mirror the three operations**: `memory_ingest`, `memory_query`, `memory_lint` - plus low-level primitives (`wiki_read`, `wiki_write`, `wiki_link`, `wiki_supersede`). Not `vector_search` as the headline tool.-- **Ingest must be a *write fan-out*, an insert.** A new observation should *touch ~10–15 existing pages* - updating an entity page, a concept page, a decisions log, a gotchas page. This is the single biggest deviation from vector RAG, which only ever appends.+- **MCP tools mirror the three operations**: `memory_ingest`, `memory_query`, `memory_lint`, plus low-level primitives (`wiki_read`, `wiki_write`, `wiki_link`, `wiki_supersede`). Not `vector_search` as the headline tool.+- **Ingest must be a *write fan-out*, an insert.** A new observation should *touch ~10–15 existing pages*: updating an entity page, a concept page, a decisions log, a gotchas page. This is the single biggest deviation from vector RAG, which only ever appends.- **`index.md` and `log.md` as first-class files.** The log is the audit trail and the consolidation trigger source. Use the prefix convention (`## [YYYY-MM-DD] action | title`) so it's grep-able.- **Retrieval is hierarchical, nearest-neighbor.** Read `index.md` → narrow to candidate pages → read them → optionally fall back to hybrid search (BM25 + vector, RRF-fused) for novel queries. The index *is* the synthesis; the embeddings are a backstop.- **Consolidation is an explicit, scheduled MCP operation**, not a side-effect. `memory_consolidate` is invoked on true session-end hooks where the client exposes them, on the manual `ai-memory finalize-session` flow for clients without a true session-end hook such as Antigravity CLI, on compaction events, or on a timer. It is LLM-driven (needs a provider key); if absent, it runs no-op as agentmemory does.-- **Cross-agent shared state.** Because the wiki is plain text, Claude Code, Codex, and OpenCode all read/write the *same* artifact. The MCP server is the gatekeeper; the markdown is the contract. No vendor lock.+- **Cross-agent shared state.** Because the wiki is plain text, Claude Code, Codex, and OpenCode all read/write the *same* artifact. The MCP server is the gatekeeper and the markdown is the contract, so there is no vendor lock.- **Coding-specific page types**: library gotchas, architectural decisions (ADR-style), failed approaches, repo conventions, environment quirks. Karpathy's example domains were personal/research; for coding agents the high-value pages are *failure modes* and *decisions*, because those are exactly what gets dropped on context compaction.**What it deliberately is *not*:**@@ -91,7 +91,7 @@ Translating Karpathy faithfully - a "Karpathy-style" backend looks very differen- Not a chronological transcript. The log exists, but it's metadata. The semantic content lives in synthesized pages.- Not opaque. Every memory the agent has must be openable in Obsidian, diff-able in git, and explainable in prose.-**Honest tension** worth resolving in design: Karpathy's gist is optimized for *human-curated research wikis* ingested one source at a time with the user watching. A coding agent ingests *continuously and unsupervised* from tool calls. This project inherits Karpathy's structure but needs the lifecycle layer (decay, supersession, confidence) that LLM Wiki v2 proposes - otherwise the wiki will fill with stale, low-signal observations from autonomous runs.+One tension to resolve in design: Karpathy's gist is optimized for *human-curated research wikis* ingested one source at a time with the user watching. A coding agent ingests *continuously and unsupervised* from tool calls. This project inherits Karpathy's structure but needs the lifecycle layer (decay, supersession, confidence) that LLM Wiki v2 proposes; otherwise the wiki will fill with stale, low-signal observations from autonomous runs.## Sourcesdiff --git a/docs/security-boundaries.md b/docs/security-boundaries.mdindex 5f0bd95d..024d4311 100644--- a/docs/security-boundaries.md+++ b/docs/security-boundaries.md@@ -3,20 +3,20 @@ai-memory is single-tenant wiki data with optional multi-user attribution, runby parallel harnesses and shared teams. A handful of guards keep one project,workspace, operator, or untrusted input from crossing into another. Each guard-is only as good as a test that **actively tries to break it** — a happy-path or+is only as good as a test that **actively tries to break it**. A happy-path orsingle-tenant test cannot see an isolation defect, so a regression that removesthe guard would pass CI silently.This file is the source of truth for which boundaries exist, where each isenforced, and the adversarial test that would fail if the guard were removed.-**Keep it current** (see the protocol at the end) — it is referenced by the-AGENTS.md "security-boundary tests" rule.+**Keep it current** (see the protocol at the end); the AGENTS.md+"security-boundary tests" rule refers to it.-An adversarial test = *attempt the violation and assert refusal, plus a-legitimate control case* (so a blanket deny is not mistaken for a working-guard). Coverage verdicts: **STRONG** = a test would fail if the guard were-deleted; **PARTIAL** = only some paths of the guard are probed; **FUTURE** =-boundary not yet built.+An adversarial test attempts the violation and asserts refusal, and also runs a+legitimate control case so a blanket deny is not mistaken for a working guard.+Coverage verdicts: **STRONG** means a test would fail if the guard were+deleted; **PARTIAL** means only some paths of the guard are probed; **FUTURE**+means the boundary is not built yet.## Boundary map@@ -97,8 +97,8 @@ boundary not yet built.## Keeping this current (the standing protocol)1. **Touch a guard, add/extend its adversarial test.** Any change to code in the- "Enforcing code" column — or that adds a new read/write/admin/hook entry- point past one of these guards — must add or extend an adversarial test that+ "Enforcing code" column, or that adds a new read/write/admin/hook entry+ point past one of these guards, must add or extend an adversarial test thatwould fail if the guard were removed, and update this file's row.2. **New boundary → new row + tests before merge.** Adding an isolationdimension (a new tenancy axis, a new capability, a new cross-scope surface)@@ -106,11 +106,12 @@ boundary not yet built.3. **A raw-id or unscoped entry point is guilty until tested.** Any handler thattakes a bare `session_id`/`run_id`/`page_id`/message id, or fans out acrossprojects (`global=true`, global `recent`, search), bypasses scope resolution- by construction — it must resolve→authorize (or filter-before-`LIMIT`) and+ by construction. It must resolve→authorize (or filter-before-`LIMIT`) andcarry an adversarial test proving a foreign id/scope is refused.4. **Prove the test bites.** An adversarial test that still passes when the guard- is deleted is not a guard test. Confirm fail-without-guard / pass-with-guard.+ is deleted is not a guard test. Confirm that it fails without the guard and+ passes with it.5. Unit tests exercise one session/tenant at a time and cannot see these- defects — the guards live at integration level (`multi_session.rs`,+ defects, so the guards live at integration level (`multi_session.rs`,`handoff_ownership.rs`, `agent_messages.rs`, `active_project` pointer tests,the MCP permission suites). Put boundary tests there.diff --git a/docs/security.md b/docs/security.mdindex a5ef3434..2b9ca03c 100644--- a/docs/security.md+++ b/docs/security.md@@ -1,6 +1,6 @@# Security-> The full security model. Moved verbatim from the README front page; the README keeps a summary.+> The full security model. Moved from the README front page; the README keeps a summary.Loopback-only (`127.0.0.1:49374`) with no auth is the default becauseit is safe for a single-user laptop: no process outside the machine can@@ -88,24 +88,23 @@ sessions. Shared servers that rely on `[auto_scope]` session isolation stillneed explicit `workspace` + `project` / `scopes`, or a bridge that forwards thereal lifecycle-hook session id on MCP requests.-**Want HTTPS?** ai-memory deliberately does not terminate TLS itself —-the right answer is a battle-tested reverse proxy in front of it.+**HTTPS.** ai-memory deliberately does not terminate TLS itself; put a+well-tested reverse proxy in front of it.[`docs/https-via-proxy.md`](https-via-proxy.md) is the deploymentguide, with copy-paste docker compose templates in[`docker/compose.tls.caddy.yml`](../docker/compose.tls.caddy.yml) (Caddywith Let's Encrypt or internal CA) and[`docker/compose.tls.cloudflared.yml`](../docker/compose.tls.cloudflared.yml)-(Cloudflare Tunnel — no open ports). Both are recommended once you-turn on multi-user or bind beyond loopback. The Quick Start happy-path of single-user on loopback doesn't need TLS — that case is-called out explicitly in the guide so you don't add ceremony where-it doesn't earn its keep.+(Cloudflare Tunnel, no open ports). Both are recommended once you+turn on multi-user or bind beyond loopback. The Quick Start default+of single-user on loopback doesn't need TLS; the guide says so+explicitly so you don't add setup you don't need.**Multi-user attribution (v0.8, optional) plus human login.** When morethan one human shares a server, ai-memory attributes each write to anamed user. Humans sign in with username/password; agents and CLIs use`Authorization: Bearer` (`AI_MEMORY_AUTH_TOKEN` for root automation, or-an `aim_` key from `ai-memory api-key add`). Data stays single-tenant —+an `aim_` key from `ai-memory api-key add`). Data stays single-tenant:there is no per-page RBAC. A`[auth].token_pepper` is required for DB-user authentication, but creating thefirst user row is what immediately switches every `/admin/*` endpoint todiff --git a/docs/shell-completions.md b/docs/shell-completions.mdindex dedca81f..d9aea9c0 100644--- a/docs/shell-completions.md+++ b/docs/shell-completions.md@@ -3,7 +3,7 @@`ai-memory completions <shell>` prints a completion script to stdout for`bash`, `zsh`, `fish`, `powershell`, or `elvish`. The script is generated fromthe binary's own command tree, so it covers every subcommand and flag of the-version that produced it — including nested commands like `user reset-password`,+version that produced it, including nested commands like `user reset-password`,`api-key rotate`, and `auth login`.The Docker wrapper's `upgrade` command is wrapper-owned rather than part of the@@ -27,8 +27,8 @@ mkdir -p ~/.config/fish/completionsai-memory completions fish > ~/.config/fish/completions/ai-memory.fish```-Fish loads that path lazily on first use — no shell restart, no `config.fish`-edit.+Fish loads that path lazily on first use, so you need neither a shell restart+nor a `config.fish` edit.### zsh@@ -96,7 +96,7 @@ Then add `use ai-memory` to `~/.config/elvish/rc.elv`.The script is a snapshot of the command tree at the moment it was generated.Re-run the same command after upgrading `ai-memory` so completions pick up new-subcommands and flags. Nothing is checked into the repository, precisely so a+subcommands and flags. Nothing is checked into the repository, so astale script cannot ship alongside a newer binary.Docker users can generate a script without a local install:diff --git a/docs/sso.md b/docs/sso.mdindex 0d5fc095..c2dcb0cc 100644--- a/docs/sso.md+++ b/docs/sso.md@@ -2,10 +2,10 @@This page consolidates ai-memory's existing OIDC support into one place forteams whose IT-security policy requires centralized identity (SSO) for any-tool touching a workstation, before they can approve local install. It does-not introduce new behavior — everything here already exists in-[`docs/install.md`](install.md) and [`SECURITY.md`](../SECURITY.md); this-page just answers "does it support our IdP?" without reading either in full.+tool touching a workstation, before they can approve local install. It adds+no new behavior: everything here already exists in+[`docs/install.md`](install.md) and [`SECURITY.md`](../SECURITY.md). This+page answers "does it support our IdP?" without reading either in full.## What's supported today@@ -20,7 +20,7 @@ ai-memory auth login oidc-device \The resulting access token is stored per-developer and used for two things:-- **Native lifecycle-hook auth** — the client-side hook that reports coding-+- **Native lifecycle-hook auth**: the client-side hook that reports coding-session events to the server.- **Thin-client HTTP commands** (`status`, `search`, `read-page`,`write-page`, `backup`, `embed`, and similar), when no static@@ -40,7 +40,7 @@ for the full command reference and provider setup notes.admin auth.- If you front the server with an OIDC-aware gateway or reverse proxy, thatgateway can translate accepted OIDC identity into the auth ai-memory- understands (static bearer / DB-user token) — ai-memory itself does not+ understands (static bearer / DB-user token). ai-memory itself does notvalidate OIDC tokens against your IdP for server API access.- OIDC/Keycloak `sid` (session) claims describe the identity provider's loginsession, not the coding-agent session ai-memory tracks for per-session@@ -55,13 +55,13 @@ for the full command reference and provider setup notes.3. If you need the *server's* HTTP/admin surface behind your IdP too (notjust the CLI/hooks), put an OIDC-aware reverse proxy or gateway in frontof it and translate accepted identities into ai-memory's static bearer /- DB-user tokens — see `SECURITY.md`'s network-exposure guidance and+ DB-user tokens. See `SECURITY.md`'s network-exposure guidance and[`docs/https-via-proxy.md`](https-via-proxy.md) for the TLS-terminationside of that setup.## Related documents-- [`docs/install.md`](install.md) — full `auth login oidc-device` reference.-- [`SECURITY.md`](../SECURITY.md) — server-side authentication/authorization+- [`docs/install.md`](install.md): full `auth login oidc-device` reference.+- [`SECURITY.md`](../SECURITY.md): server-side authentication/authorizationmodel.-- [`DATA_HANDLING.md`](../DATA_HANDLING.md) — what data moves where.+- [`DATA_HANDLING.md`](../DATA_HANDLING.md): what data moves where.diff --git a/docs/temporal.md b/docs/temporal.mdindex 14917d15..9beb5f77 100644--- a/docs/temporal.md+++ b/docs/temporal.md@@ -2,15 +2,15 @@*2.0 item 4.* The entity index carries an **ingestion-time** validitywindow, so "what did we know about X as of June" is answerable from-the store — the one mainstream graph-camp mechanism (Zep/Graphiti)-worth having at our scale.+the store. Of the mainstream graph-camp mechanisms (Zep/Graphiti), this is+the one worth having at our scale.*2.2, issue #656.* Page versions carry the same window at page grain(`pages.valid_from` / `valid_to`, V62), and `as_of` fuses the entitytimeline with version-filtered full-text search. Vocabulary is pinnedin `docs/design-page-ingestion-windows.md`: this is **ingestion time**("the version the store treated as current"), never world-time-validity — "valid-time" stays reserved for the deferred Phase B.+validity; "valid-time" stays reserved for the deferred Phase B.## Honest scope@@ -23,11 +23,11 @@ validity — "valid-time" stays reserved for the deferred Phase B.- **Two grains, one semantic.** Entity links inherit their pageversion's timeline (V56, repaired by V58); page versions nowmaterialize it directly (V62). Typed relation edges (item 3) die with- their page version, which is already a timeline — no extra columns- needed there yet.+ their page version, which is already a timeline, so they need no extra+ columns yet.- **Deletion is deletion.** Purged pages cascade their entity linksaway; the timeline does not survive an explicit purge (that is what- purge means here — see the purge docs).+ purge means here; see the purge docs).## Schema@@ -43,7 +43,7 @@ from the linked version's `created_at`; `superseded_at` from thesuperseding version's `created_at` (found via `pages.supersedes`),`NULL` for latest versions. New writes populate `valid_from` atinsert, and the supersede path closes the outgoing version's windows-in the same transaction — a link's window can never be open-ended in+in the same transaction, so a link's window can never be open-ended ina superseded version.`pages` carries the same window at page grain (V62, issue #656):@@ -65,7 +65,7 @@ NULL`. Every retire path closes both grains in the same transaction(supersede, decay, reorg graveyard, move-regenerate); the V62 backfillcovers existing stores with the same rules. No FTS rebuild is needed:the `pages_fts_*` triggers already index every version row, superseded-ones included — version-filtered search is a join-predicate change,+ones included, so version-filtered search is a join-predicate change,not an index change.## When to reach for it@@ -93,7 +93,7 @@ memory_query { "query": "postgres", "as_of": "2026-07-01T00:00:00Z" }```The entity leg needs the entity: it only answers when the query names-a tracked entity the version carried. The FTS leg covers the rest — a+a tracked entity the version carried. The FTS leg covers the rest: aversion with no `entities:`/`tags:` frontmatter, or a question phrasedwithout the exact retired term ("which database were we on during theoutage?"), still resolves through the text that was live at T.@@ -139,7 +139,7 @@ salient nouns a page is *about*, and they are populated from each page'sfrontmatter at write time:- an explicit `entities:` list, when an LLM consolidator emits one; and-- the page's `tags:` list, which nearly every page carries — tags *are*+- the page's `tags:` list, which nearly every page carries. Tags *are*"what this page is about", so they seed the entity index deterministicallywith no LLM pass and no re-consolidation.@@ -150,7 +150,7 @@ proportionally little.Existing stores self-heal. On the first start after upgrading, aone-shot, idempotent backfill scans latest pages that have no entitylinks yet, derives their entities from the same frontmatter, and opens-each link's validity window at the page version's own `created_at` — so+each link's validity window at the page version's own `created_at`, so`as_of` works historically, not just from the upgrade forward. A storewhose pages were all written through the current path finds nocandidates and the pass is a no-op. No command is required; a manualdiff --git a/docs/typed-edges.md b/docs/typed-edges.mdindex ebf9981f..2927348d 100644--- a/docs/typed-edges.md+++ b/docs/typed-edges.md@@ -1,7 +1,7 @@# Typed relation edges-Pages can declare *typed* edges to other pages — not just "these are-related" but *how*:+Pages can declare *typed* edges to other pages, which say *how* two pages+are related instead of only that they are:```yaml---@@ -15,19 +15,19 @@ relations:## When to bother — and when not toPlain `[[wikilinks]]` remain the default and are enough for "these-pages are related". Typed edges earn their keep in one specific loop —-**contradictions you want lint to chase**:+pages are related". Typed edges are worth adding in one specific loop:+**contradictions you want lint to chase**.1. A gotcha page exists: `gotchas/linker-oom.md` ("the linker OOMs onmachines under 32 GB").2. Months later a session fixes it; the consolidator (or you) writes`notes/linker-fix.md` with `relations: { fixes:- ["gotchas/linker-oom.md"] }` — the gotcha's page history now shows+ ["gotchas/linker-oom.md"] }`, and the gotcha's page history now showswhat resolved it.3. Later still, new evidence disagrees with a stored decision; the new- page declares `contradicts:` — and `memory_lint` reports the pair as- a `contradiction` finding until someone reconciles them. No LLM- involved: the declaration IS the signal.+ page declares `contradicts:`, and `memory_lint` reports the pair as+ a `contradiction` finding until someone reconciles them. No LLM is+ involved, because the declaration itself is the signal.If you are not using lint and don't need fix/cause chains, skip thefrontmatter entirely; nothing else changes.@@ -42,7 +42,7 @@ frontmatter entirely; nothing else changes.The set is deliberately closed: a free-text relation column turns intoan unqueryable folksonomy. Keys outside the vocabulary are skipped at-the write boundary (with a warning) — a typo cannot mint a new edge+the write boundary (with a warning), so a typo cannot mint a new edgekind. Targets use the same grammar as wikilinks: `path`,`project:path`, `workspace/project:path`, or `_global:path` (thereserved preferences project in the default workspace); extension-less@@ -51,14 +51,14 @@ targets gain `.md`.## What typed edges do- **`contradicts` feeds lint.** A declared contradiction is the- highest-signal zero-LLM finding possible — someone (or the+ strongest zero-LLM finding available, because someone (or theconsolidator) explicitly said two pages disagree. `memory_lint`reports each edge as a `contradiction` finding until the pages arereconciled, including the case where the target no longer resolves(a stale declaration).- **They participate in the retrieval graph** as ordinary edges. No- relation-specific ranking weight is applied — the LongMemEval- harness showed no basis for one yet; the data is stored so a future+ relation-specific ranking weight is applied, since the LongMemEval+ harness showed no basis for one yet. The data is stored so a futurechange can be measured rather than guessed.- **Backlinks stay clean.** A typed edge and a plain `[[wikilink]]`to the same target coexist as distinct rows (`links.link_type`), but@@ -67,7 +67,7 @@ targets gain `.md`.## Who writes them- **You**, in any page's frontmatter (the wiki files are plain- markdown — edit them and let the watcher reindex the page; `ai-memory+ markdown: edit them and let the watcher reindex the page; `ai-memoryreindex` only rebuilds a clean store from the markdown).- **The consolidator**, sparingly: both single-page consolidation and`memory_consolidate` with `multi_page=true` can preserve a relationdiff --git a/docs/usage.md b/docs/usage.mdindex d77a5fc2..faebe8e8 100644--- a/docs/usage.md+++ b/docs/usage.md@@ -76,8 +76,8 @@ session-start hook will not consume stale context.### Offering instead of claiming at session start-By default, `SessionStart` claims a pending handoff automatically — the-behavior described above. With several concurrent lines of work in the same+By default, `SessionStart` claims a pending handoff automatically, as+described above. With several concurrent lines of work in the sameproject, an unrelated session (a different task, a different harness, or anon-interactive launch) can consume a baton meant for a specific follow-upsession. Set `claim_on_session_start = false` under `[handoff]` in@@ -90,7 +90,7 @@ claim_on_session_start = false`SessionStart` then leaves the handoff open and renders a non-consumingnotice instead, naming the exact `handoff_id`, the agent that left it, and-its age — never the stored summary, open questions, or next steps (same+its age. It never includes the stored summary, open questions, or next steps (samesecurity bar as the inbox notice: that content is written by whatever agentor operator ended the prior session, and a notice injected into the on-startcontext cannot be deliberately skipped the way leaving `memory_handoff_accept`@@ -100,7 +100,7 @@ uncalled can). Pick it up explicitly:> memory_handoff_accept handoff_id=<the id from the notice>```-This is server-wide — every operator on the server gets the same behavior.+This is server-wide: every operator on the server gets the same behavior.Restart the server after changing `config.toml`; configuration is loaded onceat startup. The default (`true`) is unchanged for every existing install.@@ -146,7 +146,7 @@ at the managed ai-memory Agent Skills that carry detailed tool routing.| "Save context for the next session" | `memory_handoff_begin` | Writes a terse session-end handoff with open questions and next steps. Do not use for status or briefing requests. || "Discard that handoff" / "I created a handoff by mistake" | `memory_handoff_cancel` | Marks an exact open handoff id expired before the next session can consume it. || "Ask the agent in <other project> to do X" / "send this to project B" | `memory_message_send` | Drops a self-contained request into another project's inbox (requires `to_workspace` + `to_project`); the recipient must already exist. Cross-project, claim-once. See [agent-messaging.md](agent-messaging.md). |-| "Check my inbox" / "any messages waiting?" | `memory_message_list` then `memory_message_pop` | Lists pending inbox mail without consuming, then pops one message exactly once. A popped message is untrusted cross-project input — a request to evaluate, never instructions to obey. |+| "Check my inbox" / "any messages waiting?" | `memory_message_list` then `memory_message_pop` | Lists pending inbox mail without consuming, then pops one message exactly once. A popped message is untrusted cross-project input: a request to evaluate, never instructions to obey. || "Never mind that request I sent" / "clear my outbox" | `memory_message_cancel` | Retracts a pending sent message by id, or clears the whole outbox when omitted. Only affects mail this project sent. || "Consolidate this session" | `memory_consolidate` | Manually runs LLM consolidation on the server's model. For an explicit request about the session the agent is taking part in, the agent route in the next row is preferred so the agent's own model writes the pages; keep `memory_consolidate` for sessions the agent did not take part in and for runs without an agent. Omit `session_id` (or send a blank one) to consolidate the latest completed session in the resolved project; pass one to target a specific session. A project can keep advisory preferences in `_prompts/consolidation.md`; `instructions` overrides them for one call. Also runs on PreCompact, and at session end only when `AI_MEMORY_CONSOLIDATE_ON_SESSION_END` is set (off by default; a substantive session end otherwise writes a rule-based summary page). Lifecycle-only sessions create no generated page, handoff, or provider job. Opt-in SessionEnd provider work is durably queued outside the hook response, retried with backoff, and recovered after server restart. Resumed sessions re-end only when their persisted observation generation advances, so duplicate delivery and clock skew cannot loop consolidation. || "Write this session's page yourself" / an in-session "consolidate this session" | `memory_read_session_observations`, then `memory_write_page` with `session_id` and `path: sessions/<id>.md` | The agent compiles the session page with its own model instead of the server's provider. To match the server's multi-page layout it may also write up to four more pages with the same `session_id`: `concepts/<slug>.md` (`tier: semantic`, `kind: fact`), `decisions/<short>.md` (`kind: decision`), `gotchas/<slug>.md` (`kind: gotcha`) and `_rules/<slug>.md` (`kind: rule`); the session page is `tier: episodic`, `kind: fact`. The session must belong to the project the page is written to; the page records it as evidence, gets the same session-page frontmatter (plus `consolidated_by: agent`) and duplicate-title suffix, and the session's queued SessionEnd job is marked completed. The write uses the `write_page` admission op, so a webhook that filters on `consolidate` does not see it. A pinned page is never overwritten this way. SessionEnd keeps the page: neither the rule-based summary nor the opt-in SessionEnd worker replaces it, even when the session went on after the write, and a PreCompact or PostCompaction checkpoint leaves it alone too. |@@ -456,8 +456,8 @@ Client cleanup hints:entries live under `context_servers` in its user `settings.json`.If you want a visible startup reminder during the transition, keep it small. A-rules-file note such as “Active memory: ai-memory; legacy export is historical-reference only; use memory_query for retrieval” is safer than dumping large+rules-file note such as "Active memory: ai-memory; legacy export is historical+reference only; use memory_query for retrieval" is safer than dumping largelegacy context into every session.If you use the ChatGPT/Codex OAuth provider, sign in once before starting the@@ -503,7 +503,7 @@ command: ["serve", "--transport", "http", "--bind", "0.0.0.0:49374", "--enable-wThe web UI is read-only: project list, per-project page tree,breadcrumbs, rendered markdown, metadata, and FTS5 search. In rendered-pages, `[[wiki links]]` become clickable links to the target page —+pages, `[[wiki links]]` become clickable links to the target page.`[[path]]`, `[[path|label]]`, `[[project:path]]`,`[[workspace/project:path]]`, and `[[_global:path]]` are all supported(resolved against the current page's project unless the target carries@@ -526,7 +526,7 @@ completed bootstrap exists. Browser-stored Bearers remain unsupported.as `Authorization: Bearer <token>` by MCP, hook, handoff, and workstream clients.To host the web UI under a URL subpath behind a reverse proxy, the-`--base-path` / `--web-slug` flags do the work — see+`--base-path` / `--web-slug` flags do the work. See[`docs/frontend-api.md`](frontend-api.md#6-custom-ui-hosting-and-base-paths)for the flag semantics and[`docs/https-via-proxy.md`](https-via-proxy.md#hosting-under-a-subpath)@@ -655,14 +655,13 @@ pull requests). Three facts frame how such a record and ai-memory interact:1. **ai-memory never touches files in your repository.** Its wiki livesin the server's data dir; the background jobs (consolidation,curation, retention decay, auto-improvement) read and write wiki- pages only. A decision-record directory in the repo is categorically- outside ai-memory's write surface. Run both side by side without- ceremony: the repo owns the canonical record, ai-memory owns+ pages only. A decision-record directory in the repo is outside+ ai-memory's write surface. Run both side by side: the repo owns the canonical record, ai-memory ownscross-session recall.2. **Keep the record directory out of capture.** An agent reading therecord is captured like any other file read, and consolidation compiles- what it saw into wiki pages — including a `decisions/` page that says+ what it saw into wiki pages, including a `decisions/` page that says"active" long after the repo has superseded it, ranked first by`memory_query` because it matches the topic. List the directory in themarker's `[capture]` section so the copy is never made:@@ -690,6 +689,6 @@ the managed durable-pages Agent Skill teaches agents the recipe:`decisions/<slug>.md`, ADR structure (Status / Context / Decision /Consequences, including rejected alternatives), `pinned: true`, andsupersede-by-new-page instead of editing history. Ask an agent to "record this as an architectural-decision" and the skill does the rest; the structured shape also+decision" and the skill does the rest. The structured shape alsoretrieves noticeably better through `memory_query` than free-formprose.diff --git a/docs/use-cases.md b/docs/use-cases.mdindex f42987ed..e403d2f7 100644--- a/docs/use-cases.md+++ b/docs/use-cases.md@@ -55,7 +55,7 @@the server's public activity and page-count metadata. A fast, bounded depth-1scan of the current directory also finds new checkouts carrying a projectmarker (`.git`, `Cargo.toml`, `package.json`, `go.mod`, `pyproject.toml`, and- friends), while skipping dependency and build directories. The server never+ similar files), while skipping dependency and build directories. The server neverexposes a checkout path, so two client machines can safely use differentlocal paths for the same project on a remote homeserver.@@ -115,7 +115,7 @@than a local path. Use `ai-memory workstreams` when you are already in acheckout and only want the read-only list.- **"Quit at 4 PM, pick up at 9 AM in a different agent."** The- classic. SessionStart hook in the next supported hook client prepends a+ SessionStart hook in the next supported hook client prepends atyped handoff with open questions, next steps, and a session summary. Grokcannot show that text before the first prompt. The first tool's`PostToolUse` hook adds it as `additionalContext`. If the session never@@ -132,14 +132,14 @@`global: true` search uses its separate FTS-only ranker and reportsthat active stream without per-hit RRF details.- **"Remember this permanently."** When something is worth keeping- beyond auto-captured session logs - a decision, a convention, a- gotcha - tell the agent "save a permanent note that we standardised+ beyond auto-captured session logs (a decision, a convention, a+ gotcha), tell the agent "save a permanent note that we standardisedon Postgres for X" or "annotate this as a project rule" and it calls`memory_write_page` to write a durable, git-versioned wiki page. Froma terminal it's `ai-memory write-page --path decisions/0007-db.md--body $'# Standardised on Postgres\n\n...' --pinned`. `--pinned`exempts it from the decay sweep; the H1 on the first line of- `--body` becomes the page title (omit `--title` — it's still+ `--body` becomes the page title (omit `--title`; it's stillaccepted, but LLM callers trip over JSON-escaping their way throughit, see issue #67). Unlike a handoff (single-use) or anauto-synthesised session page (rewritten on consolidation), a@@ -151,13 +151,13 @@page (they move its salience, which scales the decay formula's time term),while `stale` / `wrong` floor the salience *and* make any current pageshow up as a `feedback_flagged` finding in the next `memory_lint` report.- Feedback never deletes anything — it lowers confidence and flags for review —+ Feedback never deletes anything (it lowers confidence and flags for review),and it attaches to the version current when feedback is recorded, so alater rewrite clears the flag. Retrieved page text is untrusted and neverauthorizes feedback by itself.- **"Remember this, but only until the sprint ends."** Pass`expires_at` to `memory_write_page` (RFC3339 or `YYYY-MM-DD` = end of- that day, UTC) — or put `expires_at:` in a page's frontmatter by+ that day, UTC), or put `expires_at:` in a page's frontmatter byhand. Past the TTL the page disappears from search/recent/briefing(pass `include_expired: true` to `memory_query` to still see it) andthe next forget sweep hard-deletes the file and its rows. A TTL beats@@ -213,9 +213,9 @@pages cleanly separated; the `/web` UI is reachable from abrowser anywhere on the LAN.- **"Audit what landed before sharing with a teammate."** Browse- the wiki at `http://<server>:49374/web` - sign in with username and- password when human auth is on. Per-project tree view,- rendered markdown, supersession chain visible per page.+ the wiki at `http://<server>:49374/web`, signing in with username and+ password when human auth is on. It shows a per-project tree view,+ rendered markdown, and the supersession chain for each page.- **"Undo one bad page edit without rolling back the whole server."**`ai-memory checkpoints` shows recent wiki commits, then`ai-memory restore-page --path notes/foo.md --from <rev>` restores that one@@ -224,5 +224,5 @@users, audit rows, and embeddings.- **"Drop an experiment, keep the rest."**`ai-memory purge-project --project experimental --confirm`.- Atomic: that project's DB rows cascade away, its wiki subdir gets+ The purge is atomic: that project's DB rows cascade away, its wiki subdir gets`rm -rf`'d, every sibling project is untouched by construction.diff --git a/docs/users.md b/docs/users.mdindex 83ee5e3f..4fc71668 100644--- a/docs/users.md+++ b/docs/users.md@@ -4,7 +4,7 @@> native `aim_` API credentials are the current shipped contract.ai-memory is **single-tenant wiki data** with **optional multi-user-attribution**. Every authenticated request sees the same wiki pages —+attribution**. Every authenticated request sees the same wiki pages;there is no per-page RBAC or group permission model. Operational handoffs andopen-session recovery are owner-scoped so one operator cannot accidentallyconsume or finalize another's live context. What multi-user mode also adds is@@ -25,7 +25,7 @@ Authenticated clients sharing one server must emit a distinct agent-run id foreach run and forward that same id on their MCP requests when using session-awareauto-scope. Legacy sessions whose stored owner is `NULL` remain shared.-If you run ai-memory alone, you can skip this page — your install+If you run ai-memory alone, you can skip this page; your installkeeps working unchanged.## When to enable it@@ -37,7 +37,7 @@ You probably want multi-user mode when:- You want the audit log to record *who* made each write (e.g. totrace `Codex` writes vs `Claude Code` writes vs hand-rolled CLIcalls).-- You're planning to use the admission webhook chain —+- You're planning to use the admission webhook chain, becausewebhooks receive the actor identity in their payload.You probably **don't** need it when:@@ -60,7 +60,7 @@ Every HTTP request is resolved to one of four authentication tiers:| **1 — Root** | Bearer matches `[auth].bearer_token`. | Allowed as **root**. When `[auth].root_username` is set, writes attribute to that name; otherwise attribution stays anonymous. || **1b — Proxy-asserted user** | Bearer matches the distinct `[auth].actor_proxy_bearer_token`. | Identity is taken from trusted `X-Memory-Actor-*` headers. The request is a **user** unless its OIDC issuer/subject pair exactly matches the configured root pair. Missing or malformed identity is rejected. || **2 — DB user** | Bearer doesn't match root, matches an active `api_credentials.token_hash` (SHA-256 of the secret + `[auth].token_pepper`). Native keys use the `aim_` prefix. | Allowed as **that user** for normal read/write APIs. Native keys always resolve as `AuthLevel::User`, even when the owning identity is `role=root`. All `/admin/*` endpoints are root-only in multi-user mode. The audit log records the username/email/name. |-| **3 — 401** | Bearer present but matches nothing. | Rejected. Closes the bypass — unknown bearers can't slip through as anonymous. |+| **3 — 401** | Bearer present but matches nothing. | Rejected. This closes the bypass: unknown bearers can't slip through as anonymous. |The rungs are sticky: a request is matched at the first credential thatapplies, never escalates. Startup rejects equal root and proxy credentials;@@ -90,10 +90,10 @@ Passwords are Argon2id PHC strings, 12–1024 UTF-8 bytes, hashed off the writeractor. The last enabled root with a password cannot be disabled or demoted.Greenfield bootstrap consumes `AI_MEMORY_AUTH__INITIAL_ROOT_PASSWORD` once-(`human_auth_state.bootstrap_completed`). Later restarts ignore it — unset the+(`human_auth_state.bootstrap_completed`). Later restarts ignore it, so unset theenv var. Lost root uses `AI_MEMORY_AUTH__RECOVERY_TOKEN` (at least 32characters), compared constant-time and never stored in SQLite. Public-recovery failures — wrong token, recovery unset, or password policy —+recovery failures (wrong token, recovery unset, or password policy)share one 401 `{"error":"invalid credentials"}` body. `Config::load()`rejects equality among the initial password, recovery token, root bearer,and actor-proxy bearer without logging the values. Operator runbook:@@ -139,8 +139,8 @@ root_subject = "<root-subject>"send a Secure cookie.- **The proxy MUST strip client-supplied `X-Memory-Actor-*` headers beforesetting its own.** Use a directive that *replaces* the header rather than- appending to it (nginx `proxy_set_header`, Traefik `customRequestHeaders`) —- with an appending ingress the client's value arrives first and would be the+ appending to it (nginx `proxy_set_header`, Traefik `customRequestHeaders`).+ With an appending ingress the client's value arrives first and would be theone read. Repeated headers and comma-folded values are rejected with `400`rather than resolved to one identity.- Every proxy request must assert `X-Memory-Actor-User`, or both@@ -155,7 +155,7 @@ root_subject = "<root-subject>"bearer, not the proxy bearer. Raw actor headers on the root rung are ignored.- **A proxied non-root end-user is not subject to per-project `restricted`grants.** The proxy branch authenticates the request as `AuthLevel::User`- with an `ActorContext`, but — unlike a database user — never maps it to a+ with an `ActorContext`, but, unlike a database user, never maps it to adatabase `UserId`/`AuthorizedViewer`: grants are keyed on `UserId`, and aproxied identity has none to key on. A missing `AuthorizedViewer` reads as"no per-project check applies" (the same as root, or an install with no@@ -184,7 +184,7 @@ username-only assertion to the OIDC pair deliberately changes it once.Handoffs and sessions record the operator they belong to (`owner_user` /`actor_user`, holding the qualified `IdentityKey::storage_key()` TEXT). On ashared server this stops one operator's pending handoff from being delivered-to — and consumed by — the next session to start, whoever it belongs to.+to, and consumed by, the next session to start, whoever it belongs to.- A `NULL` owner means **shared with the project**: every row written beforeownership existed, and anything written without an authenticated actor, stays@@ -193,13 +193,13 @@ to — and consumed by — the next session to start, whoever it belongs to.Single-operator servers are unaffected even when they name their operator via`[auth].root_username`: with no `users` rows and no proxy bearer there isnobody to separate, and stamping the one name would separate that operator's- *transports* instead — HTTP requests carry the name, while the stdio /+ *transports* instead: HTTP requests carry the name, while the stdio /in-process MCP transport and the local CLI carry no actor at all and wouldstop seeing what the HTTP side wrote. Reads are deliberately **not** gated thesame way, so a row stamped while the deployment did distinguish operatorsstays readable by that operator afterwards.-- The owner is the qualified identity the request names —- `ActorContext::identity_key()`, so the issuer-qualified OIDC key when a+- The owner is the qualified identity the request names, as returned by+ `ActorContext::identity_key()`: the issuer-qualified OIDC key when acomplete issuer/subject pair is asserted and `user:<name>` otherwise. It isthe same rule that decides the auth tier, so the proxy path gets realper-operator isolation rather than one shared bucket.@@ -223,7 +223,7 @@ to — and consumed by — the next session to start, whoever it belongs to.deployment distinguishes operators.- The read-only handoff listing (`GET/api/v1/workspaces/{ws}/projects/{p}/handoffs`) serves its prompt-derived- fields — `summary`, `open_questions`, `next_steps` — to a caller the server+ fields (`summary`, `open_questions`, `next_steps`) to a caller the servercan name (their own rows plus the shared ones) and to the root operator, whoreads every page body through the wiki API anyway. A caller an authenticatingserver can place as neither gets the metadata with `redacted: true`. A server@@ -232,16 +232,16 @@ to — and consumed by — the next session to start, whoever it belongs to.the explicit recovery view with `?all_owners=true`, while user and anonymoustiers receive `403`.- Handoff lifecycle events raise admission ops (`handoff_begin`,- `handoff_accept`, `handoff_cancel`), so an admission webhook can observe or —- with `failure_policy = "reject"` — refuse them. Only reject-policy hooks are+ `handoff_accept`, `handoff_cancel`), so an admission webhook can observe them or,+ with `failure_policy = "reject"`, refuse them. Only reject-policy hooks areawaited on these ops; observers are notified after the operation is durable."Multi-user mode" here means *the deployment distinguishes operators*: either`users` rows exist, or `[auth].actor_proxy_bearer_token` is configured. A trustedproxy never writes a `users` row, so counting only rows would leave everyproxied caller on the single-operator escape hatch that waves admin through.-One question, every gate: the MCP admin tools, the `/admin/*` route layer, and-the ownership stamped on handoffs and sessions all ask it.+The MCP admin tools, the `/admin/*` route layer, and+the ownership stamped on handoffs and sessions all ask this same question.## MCP client activity@@ -278,20 +278,20 @@ written before this is unnamespaced, therefore shared.ON:- session briefs and consolidation prompts show you the shared slots plus your- own — including the pointer list of recently touched pages, so another+ own, including the pointer list of recently touched pages, so anotheroperator's slot path and title stay out of your brief too;- the engine namespaces the slots it writes: a consolidation run that targetsthe shared slot lands in the session operator's own namespace instead, and apath the model aims at somebody else's namespace is skipped rather than- written or re-homed — that path comes from the model, and+ written or re-homed, because that path comes from the model, andanything reaching your observations can dictate it;- a `memory_write_page` call naming the SHARED slot is namespaced into yourown prefix, exactly as the engine would (the response reports the path thepage actually got), and writing into another operator's namespace is refused(admins may still curate any namespace, the shared slot included).-With it OFF a nested slot path means nothing in particular — every slot goes-into every brief, exactly as before the feature existed — so turning it back+With it OFF a nested slot path means nothing in particular: every slot goes+into every brief, exactly as before the feature existed, so turning it backoff makes personal slots visible to everyone again rather than stranding them.The `<segment>` is derived from the qualified identity on this server: a short,@@ -324,17 +324,17 @@ writes pages at paths the model picks from the repository's own README, docsand code, with no operator to attribute them to, so a repo carrying injectedinstructions can make it write a `_slots/…` page. It is an admin-onlyoperation on a repository the admin chose to ingest, and the behaviour is the-same with the flag off; review `bootstrap.md` — it lists every path written.+same with the flag off; review `bootstrap.md`, which lists every path written.## Other per-operator stateBeyond attribution, some engine state is recorded per operator. "Absent means-shared" is the rule throughout — a row with no recorded operator behaves-exactly as it did before the column existed — so a single-operator server+shared" is the rule throughout. A row with no recorded operator behaves+exactly as it did before the column existed, so a single-operator serverkeeps its historical behaviour:- **Auto-improvement proposals.** Each records the operator who staged it (the- qualified identity key — username or complete OIDC issuer/subject pair — so+ qualified identity key, meaning username or complete OIDC issuer/subject pair, soproxy-asserted humans count too, and it shows up on the proposal detail),and the "onepending proposal per page" rule applies per operator, so operators stop@@ -346,7 +346,7 @@ keeps its historical behaviour:any named operator's pending proposal for the same page.A proposal that does collide with one already pending is skipped on its own- — the run's other proposals still stage — and every staging surface reports+ (the run's other proposals still stage), and every staging surface reportsthe skip with the target path and the reason (the `skipped` list in the MCPand `/admin` responses, the CLI output, and the scheduler's log), so a runof N-1 proposals is never silently indistinguishable from a clean run of@@ -355,7 +355,7 @@ keeps its historical behaviour:operator is recorded per page alongside the existing shared access counter.`[decay] breadth_weight` (default `0.0`) optionally lets apage reinforced by many different people outrank one read repeatedly by a- single person — the forget sweep reads the per-page count of distinct+ single person: the forget sweep reads the per-page count of distinctoperators and feeds it into the retention score. At the default, and forpages with fewer than two distinct readers at any weight, retention scoresare unchanged.@@ -399,7 +399,7 @@ root_name = "Boss" # optional, surfaced in UIs````token_pepper` was auto-generated by `ai-memory init`; **do not-change it after issuing native API keys** — rotating the pepper invalidates+change it after issuing native API keys**, because rotating the pepper invalidatesevery `aim_` credential. The pepper makes copied`api_credentials.token_hash` rows useless to an offline attacker; humanpasswords and sessions do not use it.@@ -457,7 +457,7 @@ secrets.`ai-memory user disable <username>` stamps `disabled_at` and revokes websessions. Historical `author_id` references keep resolving. Native API-credentials stay valid — revoke those separately with `api-key revoke`.+credentials stay valid; revoke those separately with `api-key revoke`.```console$ ai-memory user disable alice@@ -489,7 +489,7 @@ $ ai-memory api-key revoke <id>Rotation 401s the previous plaintext immediately. A revoked secret doesnot come back; issue a new key instead. Native keys authenticate as-`AuthLevel::User` even when attached to a `role=root` identity —+`AuthLevel::User` even when attached to a `role=root` identity;root automation still uses `[auth].bearer_token`. External `amk_` keysstay in `mcp-auth`; they are not listed here.@@ -508,15 +508,15 @@ uninstall or `--only hooks`); `--only mcp`, `--only instructions` and `--onlyskills` keep them for the hooks still installed.It is deliberately **not** written into the agent's own config any more. Before-#552 it went onto the hook's command line — `--auth-token <token>` for native-hooks, an `AI_MEMORY_AUTH_TOKEN=` shell prefix for the script hooks — which put+#552 it went onto the hook's command line (`--auth-token <token>` for native+hooks, an `AI_MEMORY_AUTH_TOKEN=` shell prefix for the script hooks), which putit in the agent's config file *and* in `/proc/<pid>/cmdline` for the lifetime ofevery hook and every `curl`, readable by any local user, on every tool call.The second file exists for exactly that reason: building the header inlinewould put the credential straight back on a command line.An explicit `--auth-token` on a hook command, or `AI_MEMORY_AUTH_TOKEN` in the-environment, still takes precedence — so configs written before this keep+environment, still takes precedence, so configs written before this keepworking unchanged. Re-run `install-hooks --apply` to move an existing installonto the stored form.@@ -528,7 +528,7 @@ therefore strands every spooled event captured under the old one: each isrejected with `401` on the next drain.Since #542 the drain recovers them. Re-run `install-hooks --apply` with the new-token, and the next drain retries any `401`ed entry with the current bearer —+token, and the next drain retries any `401`ed entry with the current bearer;the hook that spawns the drain hands it down in the child's environment. Theretry is bounded: it only runs for an entry the server has already rejected,only for a static bearer (an OIDC token is re-resolved and refreshed every pass@@ -536,7 +536,7 @@ anyway), and only when the current token actually differs from the one thatjust failed.Until you re-run `install-hooks`, the hooks still hold the old token and there-is nothing newer to retry with — those events stay queued and age out on the+is nothing newer to retry with, so those events stay queued and age out on thenormal retry budget rather than blocking the rest of the spool (#493).## Running for a team@@ -546,18 +546,18 @@ other half is *which project* it lands in, and it matters most once more thanone person shares a server.**Knowledge is shared; batons are owned.** A page written in a project is-readable by every operator in that project — `pages.author_id` records who+readable by every operator in that project; `pages.author_id` records whowrote it and is never a read filter. That is the point of a shared server: whatone person learns, the next person retrieves. Handoffs are the opposite: ahandoff carries an owner, and only that operator receives it.**Concurrent edits supersede rather than collide.** Two people editing the samepage produce a version chain, not a conflict; the later write becomes latest and-the earlier one stays reachable. There is no merge, and none is claimed — but-nothing is destroyed either.+the earlier one stays reachable. There is no merge, and none is claimed,+but nothing is destroyed either.**Isolation of the "current project" pointer is automatic** since v1.39. Unscoped-calls (the normal case — the MCP tools default to the current project) resolve+calls (the normal case, since the MCP tools default to the current project) resolvethrough a pointer keyed by the caller's identity and session, so two operators,or one operator with two harnesses, do not overwrite each other. Confirm what aserver is running with the startup line:@@ -605,7 +605,7 @@ finds. To populate `token_pepper` without losing your currentconfig:1. **Back up the existing config** (`cp config.toml config.toml.bak`).-2. **Generate a pepper**: `ai-memory generate-auth-token 32` — this+2. **Generate a pepper**: `ai-memory generate-auth-token 32`. Thisprints a hex string of the same shape `init` would havegenerated.3. **Add the `[auth]` block** to your `config.toml`:@@ -622,7 +622,7 @@ config:4. Restart `ai-memory serve`. The new fields are picked up; existingbehaviour is unchanged.-You can defer steps 3-4 indefinitely — `bearer_token` alone keeps+You can defer steps 3-4 indefinitely; `bearer_token` alone keepsworking as it always has.## How credentials are stored@@ -691,8 +691,8 @@ actual token wired into the hook env block is whatever you pass viaserver will resolve to bob at runtime. The flag is there to keep theoperator honest, not to enforce.-Without `--as-user`, hooks install the same way they always have —-the bearer authenticates, attribution flows from the token's owner+Without `--as-user`, hooks install the same way they always have:+the bearer authenticates and attribution flows from the token's owner(root user or DB user) at write time.## Per-project access@@ -702,7 +702,7 @@ what they may reach (#708):| Mode | Who reaches the project ||---|---|-| `open` (default) | Every authenticated user — what every project was before access modes existed. |+| `open` (default) | Every authenticated user, which is what every project was before access modes existed. || `restricted` | The root operator, the user who created it, and users holding a grant on it. |Every existing project is `open` after upgrading, so nothing changes until an@@ -714,7 +714,7 @@ ai-memory user grant --user alice --workspace acme --project checkout-api --leve```Both are root-only. Restricting prints the users who have written to the-project, hold no grant and did not create it — the people it now refuses — so you can grant the+project, hold no grant and did not create it (the people it now refuses), so you can grant theones who should keep access; nothing is granted automatically.- **Grants** are `read` or `write`, per project; `write` includes `read`.diff --git a/docs/windows.md b/docs/windows.mdindex 98477768..e2cbe023 100644--- a/docs/windows.md+++ b/docs/windows.md@@ -15,17 +15,17 @@ Antigravity CLI, or another agent.- Do not mix the Windows wrapper with WSL2-launched agents unless youdeliberately override every config and hook path.- To keep the server running across logoff and reboot on native- Windows, use a service wrapper — see [Scenario- E](#scenario-e-keep-the-server-running-native-windows-service). Do not- launch it from a Scheduled Task via `Start-Process`; that looks like it- works and is silently killed at the next reboot.+ Windows, use a service wrapper (see [Scenario+ E](#scenario-e-keep-the-server-running-native-windows-service)). Do not+ launch it from a Scheduled Task via `Start-Process`: the server appears to+ start and is silently killed at the next reboot.The difference matters because hook configs contain executable paths.WSL2 agents need Linux paths and POSIX `.sh` hooks. Native Windowsagents need Windows paths, but the hook runner is agent-specific: localsupported profiles default to host-native commands. Claude Code may useits supported direct exec form (`command: "…ai-memory.exe"`, `args: ["hook",-"--event", …]`) with no shell — see [Native Hook+"--event", …]`) with no shell; see [Native HookCommand](#native-hook-command-claude-code-on-windows). Other agents use nativesingle command strings matching their hook schema. PowerShell/Git Bash scriptbundles are compatibility fallbacks and do not enforce capture-policy v1.@@ -262,8 +262,7 @@ error: failed to run custom build command for `proc-macro2`An Application Control policy has blocked this file. (os error 4551)```-This is not a toolchain problem and re-installing Rust will not fix it.-Cargo compiles each crate's `build.rs` into an unsigned executable under+Re-installing Rust will not fix it, because the toolchain is fine. Cargo compiles each crate's `build.rs` into an unsigned executable under`target\debug\build\`, and those policies block unsigned binaries fromrunning out of user-writable directories. `proc-macro2` and`icu_properties_data` are usually the first to hit it because they build@@ -318,13 +317,13 @@ whether enforcement is active. See [Capture exclusions](marker-file.md#capture-e## Scenario E: Keep The Server Running (Native Windows Service)Scenarios C and D both end at `ai-memory serve` in a foreground terminal.-That is fine for a trial and wrong for daily use: close the window, log-off, or reboot, and the server is gone.+That works for a trial but not for daily use: when you close the window,+log off, or reboot, the server stops.On Linux the packaged units in `packaging/systemd/` supply-`Restart=on-failure` and `RestartSec=5s`. Note where that resiliency-lives — systemd performs the restarts, not ai-memory. Native Windows-gets the same bargain through a **service wrapper**. ai-memory does not+`Restart=on-failure` and `RestartSec=5s`. systemd performs those+restarts, not ai-memory. Native Windows gets the same arrangement through+a **service wrapper**. ai-memory does notimplement a Windows Service control-code dispatcher, so `sc create` or`New-Service` pointed straight at `ai-memory.exe` will not work: the SCMstarts the process, waits for it to report in, never hears from it, and@@ -335,8 +334,8 @@ kills it.**Symptoms: `LastTaskResult = 0` reports success forever, the server isgone after every reboot, and there is no crash dialog, no ApplicationError event, and no further line in the server log after its startup-line.** A failure whose only symptom is a green status is why this-warning exists.+line.** This warning exists because the only visible status is a green+one.The broken shape is a task whose action is`powershell.exe -File start-server.ps1`, where the script calls@@ -352,7 +351,7 @@ The broken shape is a task whose action isthe action process exits, the job is torn down and every processstill assigned to it is terminated. `ai-memory.exe` was started as achild of the task's PowerShell and never broke away from the job, so- it dies with it — in the same second it started.+ it dies with it, in the same second it started.The server's log therefore contains exactly one line, its own startupline, and nothing after it.@@ -366,12 +365,12 @@ stays in the job for as long as it runs. Then also:logoff and starts without an interactive session;- clear the default **3-day execution time limit**(`-ExecutionTimeLimit ([TimeSpan]::Zero)`), which otherwise stops a- perfectly healthy long-running server;+ healthy long-running server;- set restart-on-failure explicitly (`-RestartCount`,`-RestartInterval`). A task has no `Restart=on-failure` unless asked.-Even corrected, that is a task pretending to be a service. Prefer the-wrapper below.+Even with those fixes it is still a task standing in for a service, so+prefer the wrapper below.### WinSW@@ -392,7 +391,7 @@ Move-Item .\WinSW-x64.exe "$Dest\ai-memory-service.exe"````ai-memory-service.xml`, beside it. Substitute your own expanded `$Dest`-for `C:\Users\you\AppData\Local\ai-memory` — spell it out rather than+for `C:\Users\you\AppData\Local\ai-memory`, and spell it out rather thanleaving a variable in the file:```xml@@ -413,9 +412,9 @@ that mirrors the units' `Restart=on-failure` + `RestartSec=5s`.**Use absolute paths here, not `%LOCALAPPDATA%`.** A Windows service runsas `LocalSystem` unless you say otherwise, and `%LOCALAPPDATA%` expands-against *that* account — `C:\Windows\System32\config\systemprofile\AppData\Local`-— so the service would quietly serve an empty data directory somewhere-you never look, while your real wiki sits untouched in your profile. Either+against *that* account (`C:\Windows\System32\config\systemprofile\AppData\Local`),+so the service would serve an empty data directory somewhere you never+look while your real wiki sits untouched in your profile. Eitherwrite the path out in full as above, or add a `<serviceaccount>` block sothe service runs as your user.@@ -444,8 +443,8 @@ The data directory is account-sensitive, and so is the **wiki's gitrepository inside it**. libgit2 enforces the same dubious-ownership guardas Git itself (CVE-2022-24765): when the process account is not the ownerof the repository, every commit fails with `code=Owner (-36)`. The server-still starts, capture still works, and search still answers — but the-wiki git history silently stops advancing, because a wiki commit failure+still starts, capture still works, and search still answers, but the+wiki git history silently stops advancing because a wiki commit failureis not fatal. As of ai-memory 2.4.x the server logs this at **ERROR** onstartup with the same remedy below; on older builds it was a WARN that waseasy to miss.@@ -475,12 +474,12 @@ account).> WinSW `<password>` must be your *account password*, which for a> Microsoft account is your online Microsoft password (not your PIN or> Hello gesture), and it must be updated in the service config whenever-> that password changes — Windows does not roll it forward. Consider a+> that password changes, because Windows does not roll it forward. Consider a> local account, or a dedicated service account with a non-expiring> password, for an unattended service.Keep running `install-mcp` and `install-hooks` **as your own user**, not-as the service — they write per-user agent config, and the rule at the+as the service. They write per-user agent config, and the rule at thetop of this page still applies.> Verified from the WinSW project documentation and the ai-memory CLI@@ -495,9 +494,9 @@ top of this page still applies.> Confirmed: `install`; `start`; the service `Running` as `LocalSystem`> with `StartType Automatic`; an MCP `initialize` answered over the bound> port; the absolute `--data-dir` honoured, with no-> `systemprofile\AppData\Local\ai-memory` created; crash recovery — the+> `systemprofile\AppData\Local\ai-memory` created; crash recovery (the> wrapped `ai-memory.exe` was force-killed and a new process was answering-> 8s later, consistent with the 5-second `<onfailure>` delay plus startup;+> 8s later), consistent with the 5-second `<onfailure>` delay plus startup;> and a clean `stop` + `uninstall`. The service was configured with> `StartType Automatic`; actual boot-time startup was not independently> exercised. At the time of this validation (2026-08-31), v2.12.0 was the@@ -531,7 +530,7 @@ native on an i7-6700HQ). Notes:- Exec form requires a real executable path (`.exe`). It does not run `.cmd` or`.bat` shims through a shell. `install-hooks` uses the path of the running`ai-memory.exe`, so release binaries and Cargo-built binaries work directly.-- The `.sh`/`.ps1` scripts stay bundled as a fallback — the Docker /+- The `.sh`/`.ps1` scripts stay bundled as a fallback: the Docker /`setup-agent` flow (no local binary) keeps emitting the shell command.For outage parity with the native hooks, both script bundles spool anundeliverable event (connection failure, timeout, 5xx) to the same@@ -539,16 +538,16 @@ native on an i7-6700HQ). Notes:the backlog after the next successful delivery; a terminal 4xx is notretried.- `AI_MEMORY_HOOK_PLATFORM` accepts five values:- - `windows-native` — Claude exec-form direct binary call (default on native Windows).- - `windows` — PowerShell `-EncodedCommand` + staged `.ps1` script. The native- Windows Docker-wrapper default because the helper container cannot install+ - `windows-native`: Claude exec-form direct binary call (default on native Windows).+ - `windows`: PowerShell `-EncodedCommand` + staged `.ps1` script. This is the+ native Windows Docker-wrapper default because the helper container cannot installits Linux binary into a host hook entry.- - `windows-bash` — `bash -c` + `.sh` through Git Bash (the previous+ - `windows-bash`: `bash -c` + `.sh` through Git Bash (the previousdefault; set this to opt back in, or as a fallback for older Claude Codebuilds that do not support exec form).- - `posix` — POSIX `.sh`. An explicit Linux/macOS Docker-wrapper compatibility+ - `posix`: POSIX `.sh`. An explicit Linux/macOS Docker-wrapper compatibilityfallback; set it to opt a native install back into the scripts.- - `posix-native` — direct binary call on macOS / Linux (`<exe> hook+ - `posix-native`: direct binary call on macOS / Linux (`<exe> hook--event …`) instead of the `.sh` script, so the hook uses the local eventspool + OIDC-token fallback. The **default for native macOS / LinuxClaude Code installs** (cargo / release binary), mirroring@@ -611,41 +610,41 @@ hook.## Support Tier: Experimental → Supported Exit CriteriaNative Windows is currently an **Experimental** tier. This is the checklist a-maintainer uses to decide whether it can be promoted to **Supported** — it is a-status inventory, not a promotion. Nothing here claims the tier has changed.+maintainer uses to decide whether it can be promoted to **Supported**. It records+status only; the tier has not changed.Each item is marked **done**, **in-progress**, or **deferred-pending-policy**,from what the repository actually ships today.-- **CI trigger coverage — done.** `.github/workflows/windows.yml` runs on a+- **CI trigger coverage: done.** `.github/workflows/windows.yml` runs on anightly `schedule`, on `workflow_dispatch`, and on pull requests. A pullrequest that touches platform-sensitive code (path handling, file locking,- git plumbing, the hook bundle — `crates/ai-memory-{wiki,store,hooks}/**`,+ git plumbing, the hook bundle: `crates/ai-memory-{wiki,store,hooks}/**`,`crates/ai-memory-cli/src/commands/install_hooks.rs`, `hooks/**`,`tests/hooks/**`, and the workflow itself) now opts in automatically via theworkflow's leading `changes` job (`dorny/paths-filter`, SHA-pinned); the- `windows` label remains a manual override for PRs outside those paths. The- tier promise no longer depends on a human remembering the label.+ `windows` label remains a manual override for PRs outside those paths, so+ coverage does not depend on someone remembering the label.-- **Hook-bundle Windows job — done.** The `hooks` job in `windows.yml` runs+- **Hook-bundle Windows job: done.** The `hooks` job in `windows.yml` runs`tests/hooks/test_lib.sh` on `windows-latest`. That suite drives`hooks/lib/ai-memory-hook.ps1`, whose PowerShell branch only ever executes- natively on Windows — so the one platform its PowerShell code is written for- is now exercised in CI rather than only on a contributor's box.+ natively on Windows, so CI now exercises that PowerShell code on the platform+ it targets instead of leaving it to a contributor's machine.-- **`#[cfg(windows)]` regression coverage — in-progress.** The Windows-only+- **`#[cfg(windows)]` regression coverage: in-progress.** The Windows-onlyregression tests that no Linux/macOS leg can compile run here: the drain-lock`ERROR_LOCK_VIOLATION` busy-state handling, the libgit2 path-resolutionfallback to the Git CLI when opening a freshly initialized wiki repository,and verbatim (`\\?\`) path handling (see the header of `windows.yml` andScenario D above). This coverage exists for the platform code that has hit a- documented bug; it stays **in-progress** because each new Windows path-,- lock-, or git-touching change is expected to add its own `#[cfg(windows)]`- regression before promotion, not because the current tests are absent.+ documented bug. The current tests exist; the item stays **in-progress**+ because each new Windows path-, lock-, or git-touching change is expected to+ add its own `#[cfg(windows)]` regression before promotion.-- **`.exe` code-signing — deferred-pending-policy.** Release binaries and the+- **`.exe` code-signing: deferred-pending-policy.** Release binaries and the`build.rs` helper executables Cargo emits are unsigned. On machines enforcing**App Control for Business** or **Smart App Control**, unsigned binaries run- from user-writable directories are blocked — this is the `os error 4551`+ from user-writable directories are blocked. This is the `os error 4551`build failure documented in Scenario D, and it can equally block an unsignedreleased `ai-memory.exe`. Signing needs a code-signing certificate and adecision on how its private material is held as a CI secret (and rotated).@@ -653,11 +652,11 @@ from what the repository actually ships today.decision is made; it is a blocker for a frictionless Supported experience onApplication-Control-enforced fleets.-- **Native `ai-memory upgrade` path — done.** `ai-memory upgrade` upgrades a+- **Native `ai-memory upgrade` path: done.** `ai-memory upgrade` upgrades awritable native install in place (#801, #802): it verifies the`ai-memory-windows-x86_64.zip` checksum, replaces `ai-memory.exe` byrename-aside, refreshes a sibling `hooks/` tree, and re-stages installed- hooks — see Scenario B. A non-writable prefix (for example under Program+ hooks (see Scenario C). A non-writable prefix (for example under ProgramFiles) still upgrades through the manual download/extract sequence.Promotion to Supported is the maintainer's decision once the in-progress items