Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat: add dry-run auto-improvement review
AkitaOnRails95c4901476da
diff --git a/AGENTS.md b/AGENTS.mdindex 359e9739..258655e3 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -2,12 +2,28 @@## Long-term memory (ai-memory)This project uses [ai-memory](https://github.com/akitaonrails/ai-memory)-for cross-session continuity. **Lifecycle hooks already capture every-prompt + tool call automatically.** You never need to manually write-routine notes; the SessionStart hook auto-fetches pending handoffs and-the SessionEnd hook auto-consolidates. Only write a durable wiki page-when the user explicitly asks to remember or annotate something-permanently.+for cross-session continuity.++**Default to the current project — always.** Every ai-memory tool+auto-scopes to the project resolved from your session's working+directory. **Do NOT pass `project`, `workspace`, or `cwd` arguments unless the user+explicitly references a *different* project by name** (e.g. "what did we+decide in the `other-app` project?"). Phrases like "this project",+"here", "we", "our work", "where did we leave off" all mean the *current*+project — call the tool with no scoping args. If the user asks about a+handoff and the SessionStart auto-fetched block is already in your+context, just answer from it; do not re-call the tool to "find it again"+in another project.++**Lifecycle hooks already capture every prompt + tool call+automatically.** You never need to manually write routine notes; the+SessionStart hook auto-fetches pending handoffs, and on session end+ai-memory writes a session-summary page and a handoff.+LLM consolidation (compiling observations into topical wiki pages) runs+on PreCompact, on demand via `memory_consolidate`, and at session end+only when the server sets `AI_MEMORY_CONSOLIDATE_ON_SESSION_END`. Only+write a durable wiki page when the user explicitly asks to remember or+annotate something permanently.### When to reach for each tool@@ -16,17 +32,20 @@ match the intent to the tool. They do not need to name the tool.| User says / situation | Tool ||---|---|-| "have we discussed X?" / "search memory for Y" / before proposing architecture | `memory_query` |+| "have we discussed X?" / "search memory for Y" / before proposing architecture | `memory_query` (current project; `scopes` for named siblings; `global=true` to search every project) || "what's been going on" / "show recent activity" (light) | `memory_recent` || "is ai-memory healthy?" / "how big is the wiki?" | `memory_status` || "give me the stats" / structured snapshot for the agent to consume | `memory_briefing` (read-only; never creates handoffs) || "catch me up" / "I've been away" / "what's important right now?" / open-ended exploration | `memory_explore` || "where did we leave off?" — and you see a `📥 ai-memory: pending handoff` block in your context | already done — answer from that block; do NOT re-call `memory_handoff_accept` |-| "where did we leave off?" — and no such block is visible | `memory_handoff_accept` (rare; the SessionStart hook usually got there first) |-| "save context for the next session" / wrapping up / ending this session | `memory_handoff_begin` (session-end only; do **not** use for status/briefing; single-use handoff; terse summary; put detail in `open_questions` + `next_steps` bullets) |+| "where did we leave off?" — and no such block is visible | `memory_handoff_accept` (rare; the SessionStart hook usually got there first; pass `workspace` + `project` together only for a named sibling workspace/project) |+| "save context for the next session" / wrapping up / ending this session | `memory_handoff_begin` (session-end only; do **not** use for status/briefing; single-use handoff; terse summary; put detail in `open_questions` + `next_steps` bullets; pass `workspace` + `project` together only for a named sibling workspace/project) || "discard that handoff" / "I created a handoff by mistake" | `memory_handoff_cancel` (requires exact `handoff_id` from `memory_handoff_begin`; marks it expired before the next session sees it) |-| "consolidate this session" / "compile what we learned" (usually automatic) | `memory_consolidate` |-| "remember this permanently" / "save a note" / "add an annotation" / durable project knowledge | `memory_write_page` (write a wiki page; do **not** use handoff for permanent notes) |+| "consolidate this session" / "compile what we learned" (also runs on PreCompact; at session end only if `AI_MEMORY_CONSOLIDATE_ON_SESSION_END` is set) | `memory_consolidate` |+| "what did we learn from this session?" / "what memory should we add?" / explicit wrap-up learning review | `memory_auto_improve` (dry-run only; omit `session_id` for latest completed session; show proposals and evidence; do **not** apply/write them unless the user explicitly approves) |+| "remember this permanently" / "save a note" / "add an annotation" / durable project knowledge | `memory_write_page` (write a wiki page; do **not** use handoff for permanent notes; put the title as a `# H1` on the first line of `body` and omit the `title` arg — ai-memory derives it from the H1) |+| "read the page about X" / "show me the full content of Y" / "open the page on Z" | `memory_read_page` (full body; pass a query to search or `path` for a direct lookup; pass `workspace` + `project` together only for a named sibling workspace/project) |+| "delete the page X" / "remove that note" | `memory_delete_page` (by exact `path`; idempotent; pass `workspace` + `project` together only for a named sibling workspace/project) || "audit the wiki" / "find contradictions" / "what rules should we add?" | `memory_lint` || "prune old pages" / "memory cleanup" | `memory_forget_sweep` |@@ -35,12 +54,62 @@ going on" use case — it returns a prose digest whose verbosityscales automatically to how long it's been since the last activity(< 1 h → one line; > 30 days → full catchup).+### When the current project comes up empty — broaden the search++`memory_query` searches only the **current** project by default. If a+search comes back empty or thin, the knowledge may live in a **sibling+project** — shared `infra`, `ops`, or a related app. Don't conclude+"we never recorded it" after a single project misses; broaden instead:++- **Know which projects to check?** Re-run with explicit `scopes`, e.g.+ `scopes: [{ "workspace": "default", "project": "infra" }]`.+- **Don't know where it lives?** Pass `global=true` to search every+ project in every workspace at once. Each hit is annotated with its+ workspace + project so you can tell where it came from. `global=true`+ cannot be combined with `scopes`/`project`/`workspace`.++`memory_query` returns **snippets, not full page bodies** — an empty or+short snippet does **not** mean the page is empty (a large page can+match outside the snippet window). To read the whole page, use+`memory_read_page` (by `path`, or pass a `query` to fetch the top hit's+full body; add `workspace` + `project` together only when the user names+a sibling workspace/project).++### Use Retrieved Memory As Operating Guidance++When `memory_query` or `memory_recent` returns `_rules/`, `gotchas/`,+`procedures/`, or `decisions/` pages that match the current task, treat+them as actionable context, not trivia:++- Read full pages with `memory_read_page` when the snippet looks relevant.+- Apply `_rules/` as constraints.+- Check `gotchas/` as preflight warnings before editing the same subsystem.+- Follow `procedures/` as checklists for releases, PR reviews, deploys,+ migrations, and other repeatable workflows.+- Use `decisions/` as prior architecture unless the user explicitly asks+ to revisit them.++Before non-trivial coding, debugging, deployment, release, auth, scope,+migration, PR-review, or data-preservation work, search memory for the+subsystem and task type first. If the first query is thin, broaden or+query specific error/subsystem terms before designing a fix.++### Learning Review++`memory_auto_improve` is a dry-run learning reviewer. Use it when the+user asks what durable lessons this session suggests, or at explicit+wrap-up when reviewing proposed memory would be useful. It returns+proposed wiki edits with evidence and never writes pages or pending+proposals. Do not apply proposals with `memory_write_page` unless the+user explicitly approves.+### When you write a project rule, write it hereIf you're about to write a durable project rule ("always X", "never-Y", "all PRs must …"), this rules file (CLAUDE.md for Claude Code;-AGENTS.md for Codex / OpenCode / Cursor / Gemini CLI; whichever-convention your agent uses) is where it belongs. ai-memory's lint+Y", "all PRs must …"), write it in the project's canonical agent+instruction file. Many projects use CLAUDE.md for Claude Code and+AGENTS.md for Codex / OpenCode / Cursor / Gemini CLI, but if the+project says one file is canonical, use that file. ai-memory's lintpass surfaces the same hint automatically when a `kind: rule` pagelands in `_rules/`.@@ -55,15 +124,68 @@ the latest binary's recommended copy:(Claude Code → `CLAUDE.md`; Codex / OpenCode / Cursor / Gemini →`AGENTS.md`), and uses its Write / Edit tool to land the block.- **From the CLI**: `ai-memory install-instructions` (defaults to- `CLAUDE.md`; pass `--target AGENTS.md` for non-Claude agents).+ `CLAUDE.md`; pass `--target AGENTS.md` for non-Claude agents or+ projects that use `AGENTS.md` as the canonical instruction file).Both are idempotent: re-runs replace the block bracketed by`<!-- ai-memory:start -->` / `<!-- ai-memory:end -->` markerswithout disturbing the rest of the file.<!-- ai-memory:end -->+## Canonical Agent Instructions++- `AGENTS.md` is the single canonical instruction file for this repository,+ including Claude Code. Keep `CLAUDE.md` as a short pointer to this file;+ do not duplicate project rules there.+- Read `docs/ARCHITECTURE.md` when you need the current operational map, and+ `docs/design-decisions.md` when you need historical rationale.+- Read `docs/auto-improvement-loop.md` before changing auto-improvement review,+ pending proposal storage, approval flows, or prompt routing for learning+ review.++## Project Summary++ai-memory is a self-contained Rust binary providing long-term memory for AI+coding agents over MCP and lifecycle hooks. Markdown-in-git is the wiki source+of truth; SQLite is the derived index for search, sessions, observations,+handoffs, users, audit, and embeddings. Capture is automatic through hooks;+durable retrieval follows the Karpathy-style LLM Wiki pattern.++## Stack And Layout++- Runtime: Rust edition 2024, `tokio`, workspace resolver 3.+- MCP/HTTP: `rmcp` plus `axum` for MCP HTTP, hooks, admin, and web routes.+- Store: `rusqlite`, `refinery` migrations, FTS5, sqlite-vec-compatible+ embeddings, one SQLite file, one writer actor, read pool.+- Wiki: markdown on disk, `notify-debouncer-full` watcher, atomic writes,+ `git2` checkpoints.+- LLM: typed providers in `ai-memory-llm`; provider-specific behavior belongs+ there, not in CLI/admin handlers.+- Config: `figment`; runtime behavior resolves config once and threads typed+ settings through call sites.+- Crates: `ai-memory-core`, `ai-memory-store`, `ai-memory-wiki`,+ `ai-memory-mcp`, `ai-memory-hooks`, `ai-memory-llm`,+ `ai-memory-consolidate`, `ai-memory-cli`, plus `ai-memory-web` and `evals/`.++## Workflow Rules++- Keep changes small and scoped. Do not start adjacent feature work unless the+ current task requires it.+- No dead code or half-built public surface. If something is future work,+ document it in docs/design notes rather than shipping unreachable stubs.+- Document constraints and incidents, not line-by-line mechanics.+- Add focused regression tests for bug fixes and behavior changes.+- MCP tool surface changes must update `MEMORY_INSTRUCTIONS`,+ `ai_memory_core::SNIPPET_BODY`, README/docs tool references, and regression+ tests that assert every tool appears in both prompt surfaces.+- Any change affecting user-visible behavior, installation, supported agents,+ providers, deployment, env/config, or public tool/admin surfaces must update+ `CHANGELOG.md` and relevant docs in the same change.+## Project Maintenance Rules+- Keep `CLAUDE.md` as a pointer to `AGENTS.md`; this avoids split-brain+ instructions between Claude Code and AGENTS-aware harnesses.- When a change affects user-visible behavior, installation, supportedplatforms, supported agents, providers, or deployment, update`CHANGELOG.md` and the README/docs support references in the same commit.diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f20a3fe5..2e0efaa9 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Added+- Added a dry-run-only auto-improvement reviewer: `ai-memory auto-improve+ --dry-run --session-id <uuid>` calls `POST /admin/auto-improve`, reads one+ completed session, applies preflight noise filters, samples large sessions via+ the consolidated session page plus high-signal observations, asks the+ configured LLM for structured durable wiki edit proposals, validates+ path/evidence/confidence and duplicate existing path/title constraints, and+ returns a report without writing wiki files or pending proposals. New+ `[auto_improve]` config defaults are enabled in safe `dry_run` mode, with no+ session-end trigger or writes unless a future staged/apply mode is explicitly+ enabled. Thresholds remain configurable: confidence, input budget, proposal+ cap, `auto_improve` attribution, and `_pending/auto-improve` staging path.+- Added read-only MCP tool `memory_auto_improve` so agents can dry-run learning+ review for the latest completed session (or a named session) without shelling+ out. The canonical MCP instructions and installed CLAUDE.md/AGENTS.md routing+ snippet now teach agents to treat `_rules/`, `gotchas/`, `procedures/`, and+ `decisions/` as actionable guidance for proactive retrieval.++### Changed+- Clarified upgrade guidance: Docker-wrapper users should run+ `ai-memory upgrade` on each agent machine to refresh the wrapper, pulled+ image, and staged hook scripts; native package/source installs should rerun+ `install-hooks --apply` after binary upgrades; remote servers still need a+ separate redeploy; and existing projects can refresh the managed routing block+ to pick up new proactive retrieval and `memory_auto_improve` guidance.+### Fixed- Admin destructive ops (`/admin/purge-project`, `/admin/move-project`) nowpropagate the authenticated actor (from the auth middleware'sdiff --git a/CLAUDE.md b/CLAUDE.mdindex 6f6a0d5c..113043a9 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1,375 +1,7 @@-# CLAUDE.md — ai-memory project directives+# Claude Code Instructions-> Read this every session before touching code. The long-form research and-> design specs live under [`docs/`](docs/); this file is the operating rules.+Read and follow [`AGENTS.md`](AGENTS.md). This repository keeps a single+canonical agent instruction file for Claude Code, OpenCode, Codex, Cursor,+Gemini CLI, and other AGENTS-aware harnesses.-## What this project is--A self-contained Rust binary providing long-term memory for AI coding agents-(Claude Code, OpenAI Codex, OpenCode) over the Model Context Protocol.-Storage = markdown-in-git wiki (source of truth) + SQLite (derived index).-Capture = automatic via agent lifecycle hooks, never manual `write_note`.-Consolidation = Karpathy "LLM Wiki" pattern with versioned supersession.--Read [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) first for the-operational summary. Read [`docs/design-decisions.md`](docs/design-decisions.md)-for the full v1 spec. Read [`docs/research-karpathy-llm-wiki.md`](docs/research-karpathy-llm-wiki.md)-for what "Karpathy-faithful" means in practice.--## Stack (do not deviate without updating `docs/design-decisions.md` §4)--- **Runtime:** Rust 1.95 (pinned in `rust-toolchain.toml`), edition 2024,- resolver 3, async via `tokio`.-- **MCP:** `rmcp` (official `modelcontextprotocol/rust-sdk`).-- **Store:** `rusqlite` + `refinery` migrations, FTS5 in v1, `sqlite-vec` in- v0.2. **One file**, one writer actor, one read pool.-- **Wiki:** markdown on disk, `notify-debouncer-full` watcher with heartbeat- + reconciliation, `git2` for versioning.-- **HTTP:** `axum` for hook ingress + MCP HTTP/SSE.-- **LLM:** typed clients per provider (Anthropic, OpenAI, OpenAI-compat) via- `reqwest`. **Never** a generic gateway like LiteLLM (cognee #2840 lesson).-- **Config:** `figment`, one read at startup, passed by `&Arc<Config>`.-- **Logging:** `tracing` with module filters; never let the appender's own- module log at INFO+ (agentmemory #519 lesson).--## Repository layout--```-crates/- ai-memory-core/ # domain types, errors. NO IO.- ai-memory-store/ # SQLite, single-writer actor, migrations.- ai-memory-wiki/ # markdown read/write, watcher, git.- ai-memory-mcp/ # rmcp transport + tool router.- ai-memory-hooks/ # hook payload schemas + HTTP ingress.- ai-memory-llm/ # LlmProvider trait + 3 impls.- ai-memory-consolidate/ # Karpathy ingest/query/lint pipeline.- ai-memory-cli/ # `ai-memory` binary entry point.-hooks/ # vendored hook scripts per agent.-docker/ # Dockerfile + compose.-docs/ # research + design (DO NOT delete).-tests/ # workspace integration tests.-```--## Workflow rules--1. **Milestone by milestone.** Do not start M(n+1) until every "Done when"- bullet in M(n) passes. See [`docs/design-decisions.md`](docs/design-decisions.md)- for the milestone list. No mixing.-2. **No dead code, no half-built features.** If a feature is not finished,- it does not land. If you must stub something, document it as `M(n) TODO`- in the relevant module's doc-comment with the milestone number.-3. **Tests before claiming done.** Every milestone requires:- - `cargo fmt --all -- --check` (no diffs)- - `cargo clippy --workspace --all-targets -- -D warnings` (no warnings)- - `cargo test --workspace` (all green)- - Manual exercise of the new feature against a real agent CLI when applicable.-4. **Document the why in code, not the what.** No comments restating the line- above; only comments explaining a constraint, an incident, or a non-obvious- invariant.-5. **Add a unit test before the implementation, not after.** Especially for- parsers, ID derivation, and any retention/decay math.-6. **MCP tool surface changes must update every prompt surface.** When adding,- removing, or renaming an MCP tool, update `MEMORY_INSTRUCTIONS`,- `ai_memory_core::SNIPPET_BODY`, README/docs tool references, and regression- tests that assert every tool appears in both prompt surfaces.-7. **Don't refactor outside the milestone.** Touch only what the current- milestone requires; resist scope creep.--## Cross-cutting invariants (carved in, never violated)--These come straight from issue-tracker research on agentmemory, basic-memory-and cognee — every one of them is in `docs/design-decisions.md` §14 with-issue citations. **Treat any code review that violates one of these as a-blocking issue:**--1. One config-read path. Runtime behaviour (anything that touches the- Store, Wiki, MCP request path, hook router, or LLM call site) reads- from `Config` (loaded once at startup), never from- `std::env::var`. Render-time helpers (commands whose output is- `settings.json` / hook scripts / install snippets) and fast-path- subcommands whose own latency budget forbids `Config::load` (e.g.- `ai-memory hook`) MAY read their own scoped env vars directly,- but the read MUST carry an inline comment naming the var and the- reason, and the code MUST NOT own Store / Wiki state. The point of- the rule is one-source-of-truth for runtime values; install-time- and fast-path renderers don't threaten that.-2. Single-writer SQLite actor. All writes through one `mpsc` channel.-3. Indexes commit in the same transaction as the data. No- background-task-indexing-after-return.-4. Typed `(WorkspaceId, ProjectId, PagePath)` identity in every layer.-5. Hooks are fire-and-forget. Sub-second timeouts. Return 202 immediately,- or 429 when saturated.-6. Privacy strip is a typed boundary (`RawHookPayload → Sanitized<Observation>`).-7. JSON-schema structured outputs only. No XML, no `instructor`-style wrapping.-8. `{provider, model, dim}` stored next to every embedding. Refuse on mismatch.-9. Live-process check (`sysinfo`) before any destructive op.-10. Atomic file writes (tmp + rename + fsync). Watcher ignores own writes.-11. Default data dir is an absolute canonical platform path.- Logged loudly on startup.-12. No global singletons / `lazy_static` configs.-13. Zero-LLM default path. LLM features opt-in via env.-14. Tracing subscribers explicitly filter their own module- (implementation-detail level, but called out here because the- feedback-loop bug it prevents — agentmemory #519 — was load-bearing- enough to leave the project unbootable. New subsystems must repeat- the same `with_target_writer` pattern; see `crates/ai-memory-cli/- src/main.rs`).-15. **Every command + storage operation is namespaced by the- project's stable surrogate `(workspace_id, project_id)` — all- the way down to the on-disk wiki layout.** Two layers:-- a. **Surface (commands)**: the per-cwd router derives the project- name from `basename(cwd)`; bootstrap / lint / embed /- forget-sweep / purge-project / rename-project / consolidate /- write-page ALL resolve through `commands::resolve_project_name`- (or the router's `resolve_project_ids` on the server side). There- is no generic `scratch` fallback in the happy path — `scratch`- exists only as a defensive default for hook events that arrive- without a `cwd` (e.g. early startup or misconfigured agents).- Commands/handlers that bake in a `workspace_id`/`project_id` at- construction time MUST look up the session's actual project (via- `ReaderPool::session_project_ids`) before writing. The MCP read- tools have no cwd of their own (the protocol carries none), so they- resolve through `AiMemoryServer::effective_ids`: explicit `project`- arg → the hook-published `ActiveProject` (the cwd the agent is- working in, shared in-process between `/hook` and `/mcp`) → the- baked-in default. Never query a read tool against the static- `--project` alone — that re-introduces issue #2 (reads land in- `scratch` while hooks populate the real project).-- b. **Storage layout**: wiki files live at- `<wiki_root>/<workspace_id>/<project_id>/<page-path>`. The mutable- project NAME never appears in any disk path; the stable UUID- surrogate does. Consequences this rule enforces:- - Renaming a project is a single column update on- `projects.name`; no file moves ever.- - Purging a project is `std::fs::remove_dir_all(project_root)` —- atomic, no shared-file footgun.- - Two projects can have the same `pages.path` (e.g.- `decisions/0001.md`) without on-disk collision.- - `log.md` and `bootstrap.md` are per-project files inside the- project's namespaced dir, NOT shared at the wiki root.-- Every `Wiki` API call carries `(workspace_id, project_id)`- either as explicit args (read_page, delete_page) or via- `WritePageRequest`. No call ever reads/writes at- `<wiki_root>/<path>` directly; always go through- `Wiki::project_root(ws, proj).join(path)`. The filesystem- watcher parses the first two path segments of every event as- UUIDs and uses those to stamp the reindex — events outside the- namespaced layout are ignored.-16. **The server is the sole writer of Store / Wiki state. CLI- commands that mutate runtime state go through HTTP.** The rule- has two halves, stated as properties rather than an exception list- (the list kept growing as new subcommands landed):-- a. **Never open the underlying state from a CLI command.** No CLI- subcommand calls `Store::open`, `Wiki::new`, `build_provider`,- or `build_embedder`. The shared- `crate::http_client::{ServerEndpoint, get_json, post_json}`- plumbing is the only way to talk to the server, and every new- client subcommand uses it.-- b. **State mutation routes through `/admin/*`.** Any subcommand- whose effect would otherwise require writing to SQLite or the- wiki MUST POST to an admin route on the running server. Reads go- through MCP tools or `/admin/*` GETs.-- Subcommands that don't mutate runtime state (install / render /- pre-credential commands, the server itself, fast-path hook events,- and lifecycle ops that fundamentally require the server stopped- like `reset` / `restore` — both gated by `sysinfo` to refuse if any- sibling `ai-memory` is alive) are not bound by half (b), but still- must obey half (a): no opening Store / Wiki, no constructing- providers / embedders, no direct SQL.-17. **Wiki-structure changes require a migration.** Any change to the- on-disk wiki layout (path scheme, directory names, mass page rewrites)- MUST be accompanied by a `WikiMigration` implementation registered in- `crates/ai-memory-wiki/src/migrations/mod.rs`. The migration runs at- server startup (after refinery, before the watcher), is tracked in the- `wiki_migrations` SQL table, and runs at most once per data directory.- Rules:- - Migration names are `YYYY_MM_DDTHH_MM_<snake_case>` (UTC, chosen at- authoring time). Never change a name after it ships.- - Implementations must be idempotent: detect whether the work is already- done and return `Ok(())` immediately if so.- - No LLM calls and no destructive deletes without a graveyard step- (move to `<wiki_root>/_graveyard/<migration_name>/…` first).- - No direct SQL — use `WriterHandle` methods (single-writer invariant).- - Append to the registry; never reorder or remove entries.- See [`docs/wiki-migrations.md`](docs/wiki-migrations.md) for the full- guide and an example implementation.-18. **No shell spawn / child process in per-tool-call code paths.**- Lifecycle hooks (`/hook`, `ai-memory hook`), MCP tool dispatch, and- the hook router MUST NOT spawn shells or child processes- (`Command::new`, `bash -c`, `powershell.exe -Command`, …).- Everything they need is in the binary — `reqwest` for HTTP,- `sysinfo` for process info, `git2` for git. PR #84 measured- ~735 ms shell → ~150-205 ms native on Windows (3.5-5× per hook);- even on POSIX the spawn shows up as observable stall time across- an interactive session. Install-time / render-time helpers (the- code that *generates* hook command strings) are exempt — they're- the ones picking which native binary the host invokes.-19. **`CHANGELOG.md` `[Unreleased]` is part of every user-visible PR.**- Any PR that adds a flag, env var, endpoint, MCP tool, public API,- behaviour change, or observable bug fix MUST add an entry to- `[Unreleased]` under the correct Keep-a-Changelog section (Added /- Changed / Fixed / Removed / Breaking). `bin/release` migrates- `[Unreleased]` verbatim to the new version, so a missing entry- means the release tag ships with no release notes attached and the- operator has to backfill from `git log`. Treat a missing entry as- `[BLOCKING]` at PR review — push back to the author with the- suggested one-liner rather than batching the fix into a follow-up- `docs(changelog)` commit. The post-merge audit history shows this- is otherwise the single most-forgotten contributor obligation.--## Mistakes documented in the research — do NOT repeat--- [`docs/issues-agentmemory.md`](docs/issues-agentmemory.md): install/ops- landmines (iii-engine sidecar, distroless volumes, cwd-relative paths).-- [`docs/issues-basic-memory.md`](docs/issues-basic-memory.md): file watcher- pain, manual-capture friction, multi-workspace retrofit.-- [`docs/issues-cognee.md`](docs/issues-cognee.md): LiteLLM/instructor wire- drift, multi-store sync bugs, dependency landmines.--When in doubt about a design decision, search those files for the keyword.--## Quick commands--```bash-# Build everything.-cargo build --workspace--# Lint + format + test (run before every commit).-cargo fmt --all -- --check-cargo clippy --workspace --all-targets -- -D warnings-cargo test --workspace--# Auto-format.-cargo fmt --all--# Exercise the binary.-./target/debug/ai-memory --version-./target/debug/ai-memory init-AI_MEMORY_DATA_DIR=/tmp/x ./target/debug/ai-memory init-./target/debug/ai-memory status --json--# CI parity (requires cargo-deny + cargo-audit installed).-cargo install cargo-deny cargo-audit-cargo deny check-cargo audit-```--## What this project is NOT (v1 non-goals)--See [`docs/design-decisions.md`](docs/design-decisions.md) §13 for the full-list. Highlights: no multi-tenant auth, no web UI, no Postgres backend in v1,-no alternative vector backends, no remote sync (use `git remote` on the wiki-dir), no multimodal.--## Plan & status--The current execution plan is at-[`/home/akitaonrails/.claude/plans/cuddly-moseying-karp.md`](/home/akitaonrails/.claude/plans/cuddly-moseying-karp.md)-(local to the maintainer's `~/.claude/`).-Live progress is tracked via the TaskList tool inside Claude Code sessions.--<!-- ai-memory:start -->-## Long-term memory (ai-memory)--This project uses [ai-memory](https://github.com/akitaonrails/ai-memory)-for cross-session continuity.--**Default to the current project — always.** Every ai-memory tool-auto-scopes to the project resolved from your session's working-directory. **Do NOT pass `project` or `cwd` arguments unless the user-explicitly references a *different* project by name** (e.g. "what did we-decide in the `other-app` project?"). Phrases like "this project",-"here", "we", "our work", "where did we leave off" all mean the *current*-project — call the tool with no scoping args. If the user asks about a-handoff and the SessionStart auto-fetched block is already in your-context, just answer from it; do not re-call the tool to "find it again"-in another project.--**Lifecycle hooks already capture every prompt + tool call-automatically.** You never need to manually write routine notes; the-SessionStart hook auto-fetches pending handoffs, and on session end-ai-memory writes a session-summary page and a handoff.-LLM consolidation (compiling observations into topical wiki pages) runs-on PreCompact, on demand via `memory_consolidate`, and at session end-only when the server sets `AI_MEMORY_CONSOLIDATE_ON_SESSION_END`. Only-write a durable wiki page when the user explicitly asks to remember or-annotate something permanently.--### When to reach for each tool--The user can express any of the intents below in plain English —-match the intent to the tool. They do not need to name the tool.--| User says / situation | Tool |-|---|---|-| "have we discussed X?" / "search memory for Y" / before proposing architecture | `memory_query` (current project; `scopes` for named siblings; `global=true` to search every project) |-| "what's been going on" / "show recent activity" (light) | `memory_recent` |-| "is ai-memory healthy?" / "how big is the wiki?" | `memory_status` |-| "give me the stats" / structured snapshot for the agent to consume | `memory_briefing` |-| "catch me up" / "I've been away" / "what's important right now?" / open-ended exploration | `memory_explore` |-| "where did we leave off?" — and you see a `📥 ai-memory: pending handoff` block in your context | already done — answer from that block; do NOT re-call `memory_handoff_accept` |-| "where did we leave off?" — and no such block is visible | `memory_handoff_accept` (rare; the SessionStart hook usually got there first) |-| "save context for the next session" / wrapping up | `memory_handoff_begin` (single-use handoff; terse summary; put detail in `open_questions` + `next_steps` bullets) |-| "consolidate this session" / "compile what we learned" (also runs on PreCompact; at session end only if `AI_MEMORY_CONSOLIDATE_ON_SESSION_END` is set) | `memory_consolidate` |-| "remember this permanently" / "save a note" / "add an annotation" / durable project knowledge | `memory_write_page` (write a wiki page; do **not** use handoff for permanent notes) |-| "read the page about X" / "show me the full content of Y" / "open the page on Z" | `memory_read_page` (full body; pass a query to search or `path` for a direct lookup) |-| "audit the wiki" / "find contradictions" / "what rules should we add?" | `memory_lint` |-| "prune old pages" / "memory cleanup" | `memory_forget_sweep` |--`memory_explore` is the right default for the "I want to know what's-going on" use case — it returns a prose digest whose verbosity-scales automatically to how long it's been since the last activity-(< 1 h → one line; > 30 days → full catchup).--### When the current project comes up empty — broaden the search--`memory_query` searches only the **current** project by default. If a-search comes back empty or thin, the knowledge may live in a **sibling-project** — shared `infra`, `ops`, or a related app. Broaden instead of-concluding "we never recorded it":--- **Know which projects to check?** Re-run with explicit `scopes`, e.g.- `scopes: [{ "workspace": "default", "project": "infra" }]`.-- **Don't know where it lives?** Pass `global=true` to search **every**- project in every workspace at once; each hit is annotated with its- workspace + project. `global=true` cannot be combined with- `scopes`/`project`/`workspace`.--`memory_query` returns **snippets, not full page bodies** — an empty or-short snippet does **not** mean the page is empty (a large page can-match outside the snippet window). To read the whole page, use-`memory_read_page` (by `path`, or pass a `query` to fetch the top hit's-full body).--### When you write a project rule, write it here--If you're about to write a durable project rule ("always X", "never-Y", "all PRs must …"), this rules file (CLAUDE.md for Claude Code;-AGENTS.md for Codex / OpenCode / Cursor / Gemini CLI; whichever-convention your agent uses) is where it belongs. ai-memory's lint-pass surfaces the same hint automatically when a `kind: rule` page-lands in `_rules/`.--### Refreshing this snippet--This block is maintained by ai-memory. Two ways to refresh it with-the latest binary's recommended copy:--- **From the agent** (no terminal needed): ask "refresh the ai-memory- routing in this project" — the agent calls- `memory_install_self_routing`, picks the right filename for itself- (Claude Code → `CLAUDE.md`; Codex / OpenCode / Cursor / Gemini →- `AGENTS.md`), and uses its Write / Edit tool to land the block.-- **From the CLI**: `ai-memory install-instructions` (defaults to- `CLAUDE.md`; pass `--target AGENTS.md` for non-Claude agents).--Both are idempotent: re-runs replace the block bracketed by-`<!-- ai-memory:start -->` / `<!-- ai-memory:end -->` markers-without disturbing the rest of the file.-<!-- ai-memory:end -->+Do not duplicate project rules here. Update `AGENTS.md` instead.diff --git a/Cargo.lock b/Cargo.lockindex 3ceff21b..c4bddd72 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -78,6 +78,7 @@ dependencies = ["ai-memory-store","ai-memory-wiki","anyhow",+ "async-trait","git2","jiff","rusqlite",diff --git a/README.md b/README.mdindex 86d695e2..e6cc383f 100644--- a/README.md+++ b/README.md@@ -89,14 +89,14 @@ priors are at the [bottom](#influences-and-prior-art).session-aware current-project routing.- **Thin-client CLI.** `ai-memory status`, `bootstrap`, `checkpoints`,`restore-page`, `purge-project`, `rename-project`, `move-project`, `lint`,- `embed`, `forget-sweep`, `backup` are+ `auto-improve --dry-run`, `embed`, `forget-sweep`, `backup` areall HTTP clients of the running server - never touch SQLite orwiki files directly. `status` also reports passive LLM/embeddingprovider health from the last real provider call. Server is thesingle source of truth.- **LLM is opt-in.** Zero-LLM mode still gives you FTS5 search +rule-based summarisation. Add a provider when you want consolidated- pages and lint contradictions.+ pages, lint contradictions, or dry-run auto-improvement proposals.## Use cases@@ -128,6 +128,12 @@ priors are at the [bottom](#influences-and-prior-art).`git log`, README, `docs/`, module headers, project rules andone-shot-summarises them into seed wiki pages. Future sessionsbuild on top.+- **"What durable lesson did that session teach?"**+ `ai-memory auto-improve --dry-run --session-id <uuid>` reviews one completed+ session with the configured LLM and returns validated proposed wiki edits. It+ is report-only for now: no pending pages or durable wiki files are written.+ Agents can also call `memory_auto_improve` to review the latest completed+ session in the current project without knowing the session id.- **"Run one ai-memory for the whole household."** Stand the serverup on a homelab box at `0.0.0.0:49374` with a bearer token; everylaptop/desktop talks to it. Per-cwd routing keeps each project's@@ -269,8 +275,17 @@ use `--mcp-url` if you installed MCP with a custom endpoint, andMCP/hooks. Explicit `--server-url` flags still work, but are no longerrequired when the env vars are set. Any non-loopback server should usebearer auth.-- **Upgrades:** run `ai-memory upgrade` to refresh the wrapper, image,- and staged hook scripts. Redeploy remote servers separately.+- **Upgrades:** for Docker-wrapper installs, run `ai-memory upgrade` on each+ agent machine. It refreshes the local wrapper, pulls the latest image, and+ re-stages hook scripts under `~/.local/share/ai-memory/hooks/<agent>/`.+ Native package/source installs should rerun+ `ai-memory install-hooks --agent <agent> --apply` after upgrading the binary.+ Remote/homelab servers must still be redeployed separately; local wrapper+ upgrade only updates the client machine. Existing project prompt files keep+ working, but refresh the managed ai-memory routing block+ (`ai-memory install-instructions`, or `--target AGENTS.md` for AGENTS-based+ projects) when you want new tool guidance such as proactive retrieval and+ `memory_auto_improve`.For Codex, OpenCode, OMP, Cursor, Claude Desktop, Gemini CLI, Antigravity CLI,Grok Build CLI, OpenClaw, VS Code Copilot, curl-based hook installs, source builds,diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex 089a1eeb..c1ee87ea 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -79,6 +79,8 @@ pub enum Command {ForgetSweep(ForgetSweepArgs),/// Run the M8 lint pass (stale / duplicates + optional LLM contradiction).Lint(LintArgs),+ /// Dry-run an optional auto-improvement review for one completed session.+ AutoImprove(AutoImproveArgs),/// Compute + store embeddings for every latest page (M9).Embed(EmbedArgs),/// Generate a random hex bearer token for AI_MEMORY_AUTH_TOKEN.@@ -852,6 +854,45 @@ pub struct LintArgs {pub project: Option<String>,}+/// Arguments for `auto-improve`.+#[derive(Debug, Args)]+pub struct AutoImproveArgs {+ /// Required for now. Staging/apply will ship after pending proposal storage.+ #[arg(long)]+ pub dry_run: bool,+ /// Completed session UUID to review.+ #[arg(long)]+ pub session_id: String,+ /// Workspace name. Defaults to `default`.+ #[arg(long, default_value_t = crate::config::DEFAULT_WORKSPACE.to_string())]+ pub workspace: String,+ /// Project name. When omitted, auto-derived from the basename of+ /// the current git repo root (or CWD if no git repo).+ #[arg(long)]+ pub project: Option<String>,+ /// Override `[auto_improve].min_observations` for this run.+ #[arg(long)]+ pub min_observations: Option<usize>,+ /// Override `[auto_improve].min_session_duration_secs` for this run.+ #[arg(long)]+ pub min_session_duration_secs: Option<u64>,+ /// Override `[auto_improve].min_confidence` for this run.+ #[arg(long)]+ pub min_confidence: Option<f32>,+ /// Override `[auto_improve].max_input_tokens` for this run.+ #[arg(long)]+ pub max_input_tokens: Option<usize>,+ /// Override `[auto_improve].max_proposals_per_run` for this run.+ #[arg(long)]+ pub max_proposals: Option<usize>,+ /// Include raw fallback context when the reviewer supports it.+ #[arg(long)]+ pub include_raw_fallback: bool,+ /// Emit only the machine-readable JSON report.+ #[arg(long)]+ pub json: bool,+}+/// Arguments for `llm-test`.#[derive(Debug, Args)]pub struct LlmTestArgs {@@ -1152,6 +1193,28 @@ mod tests {assert_eq!(args.project.as_deref(), Some("explicit"));}+ #[test]+ fn auto_improve_dry_run_parses_required_session() {+ let cli = Cli::try_parse_from([+ "ai-memory",+ "auto-improve",+ "--dry-run",+ "--session-id",+ "00000000-0000-0000-0000-000000000000",+ "--max-proposals",+ "2",+ ])+ .expect("auto-improve dry-run parses");++ let Command::AutoImprove(args) = cli.command else {+ panic!("expected auto-improve command");+ };+ assert!(args.dry_run);+ assert_eq!(args.session_id, "00000000-0000-0000-0000-000000000000");+ assert_eq!(args.max_proposals, Some(2));+ assert_eq!(args.project, None);+ }+#[test]fn pi_hook_agent_aliases_parse_to_same_variant() {for alias in ["omp", "pi", "oh-my-pi"] {diff --git a/crates/ai-memory-cli/src/commands/auto_improve.rs b/crates/ai-memory-cli/src/commands/auto_improve.rsnew file mode 100644index 00000000..1f3b480f--- /dev/null+++ b/crates/ai-memory-cli/src/commands/auto_improve.rs@@ -0,0 +1,115 @@+//! `ai-memory auto-improve` — dry-run durable wiki edit proposals.++use ai_memory_consolidate::AutoImproveReport;+use anyhow::{Result, bail};+use serde::Serialize;++use crate::cli::AutoImproveArgs;+use crate::config::Config;+use crate::http_client::{ServerEndpoint, post_json};++/// Request sent to `POST /admin/auto-improve`.+#[derive(Serialize)]+struct AutoImproveRequest {+ workspace: String,+ project: String,+ session_id: String,+ dry_run: bool,+ min_observations: usize,+ min_session_duration_secs: u64,+ min_confidence: f32,+ max_input_tokens: usize,+ max_proposals_per_run: usize,+ include_raw_fallback: bool,+ proposal_actor: String,+ pending_path: String,+}++/// Run the `auto-improve` subcommand.+///+/// # Errors+/// Returns an error if the command is not explicitly dry-run, if the server is+/// unreachable, or if the server rejects the review request.+pub async fn run(config: &Config, args: AutoImproveArgs) -> Result<()> {+ if !args.dry_run {+ bail!(+ "auto-improve currently supports only --dry-run; pending proposal storage is not implemented yet"+ );+ }++ let endpoint = ServerEndpoint::from_config(config);+ let project = super::resolve_project_name(config, args.project.as_deref())?;+ let settings = &config.auto_improve;+ let request = AutoImproveRequest {+ workspace: args.workspace,+ project: project.clone(),+ session_id: args.session_id,+ dry_run: true,+ min_observations: args.min_observations.unwrap_or(settings.min_observations),+ min_session_duration_secs: args+ .min_session_duration_secs+ .unwrap_or(settings.min_session_duration_secs),+ min_confidence: args.min_confidence.unwrap_or(settings.min_confidence),+ max_input_tokens: args.max_input_tokens.unwrap_or(settings.max_input_tokens),+ max_proposals_per_run: args.max_proposals.unwrap_or(settings.max_proposals_per_run),+ include_raw_fallback: args.include_raw_fallback || settings.include_raw_fallback,+ proposal_actor: settings.proposal_actor.clone(),+ pending_path: settings.pending_path.clone(),+ };++ let report: AutoImproveReport = post_json(&endpoint, "/admin/auto-improve", &request).await?;+ if args.json {+ println!("{}", serde_json::to_string_pretty(&report)?);+ } else {+ print_human_report(&report, &project);+ println!("\n--- machine-readable ---");+ println!("{}", serde_json::to_string_pretty(&report)?);+ }+ Ok(())+}++fn print_human_report(report: &AutoImproveReport, project: &str) {+ println!(+ "\nAuto-improve dry-run for {project} session {}\n",+ report.session_id+ );+ println!("Summary: {}", report.summary);+ println!(+ "Input: {} observations, {}s span, ~{} tokens",+ report.observations_considered, report.session_duration_secs, report.estimated_input_tokens+ );+ println!(+ "Reviewer: {}/{}; min confidence {}",+ report.provider, report.model, report.min_confidence+ );+ println!(+ "Future staging: actor `{}`, path `{}`",+ report.proposal_actor, report.pending_path+ );++ if report.proposals.is_empty() {+ println!("\nValidated proposals: none");+ } else {+ println!("\nValidated proposals:");+ for proposal in &report.proposals {+ println!(+ " - {} [{}] confidence {:.2}: {}",+ proposal.path, proposal.kind, proposal.confidence, proposal.title+ );+ }+ }++ if !report.rejected_candidates.is_empty() {+ println!("\nRejected candidates:");+ for rejected in &report.rejected_candidates {+ println!(" - {}: {}", rejected.reason, rejected.evidence);+ }+ }++ if !report.warnings.is_empty() {+ println!("\nWarnings:");+ for warning in &report.warnings {+ println!(" - {warning}");+ }+ }+}diff --git a/crates/ai-memory-cli/src/commands/mod.rs b/crates/ai-memory-cli/src/commands/mod.rsindex 48edac85..10e167a9 100644--- a/crates/ai-memory-cli/src/commands/mod.rs+++ b/crates/ai-memory-cli/src/commands/mod.rs@@ -6,6 +6,7 @@ use crate::config::Config;pub mod apply_shared;pub mod auth;+pub mod auto_improve;pub mod backup;pub mod bootstrap;pub mod checkpoints;diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rsindex 991ef9b3..d07b857c 100644--- a/crates/ai-memory-cli/src/config.rs+++ b/crates/ai-memory-cli/src/config.rs@@ -29,6 +29,10 @@ pub const DEFAULT_SERVER_URL: &str = "http://127.0.0.1:49374";/// Default MCP endpoint URL rendered for client integrations.pub const DEFAULT_MCP_URL: &str = "http://127.0.0.1:49374/mcp";+/// Default confidence floor for staged auto-improvement proposals.+pub const DEFAULT_AUTO_IMPROVE_MIN_CONFIDENCE: f32 =+ ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MIN_CONFIDENCE;+/// Default workspace name used by the single-workspace v1 flow.pub const DEFAULT_WORKSPACE: &str = ai_memory_core::DEFAULT_WORKSPACE_NAME;@@ -101,6 +105,8 @@ pub struct Config {pub decay: ai_memory_store::DecayParams,/// Server-side scheduled maintenance. Jobs run outside hook latency.pub maintenance: MaintenanceSettings,+ /// Optional post-session auto-improvement reviewer. Off by default.+ pub auto_improve: AutoImproveSettings,/// Privacy-strip tuning. Built-in patterns always run; this section/// lets the operator extend or punch holes in them.pub sanitize: ai_memory_core::SanitizeConfig,@@ -342,6 +348,7 @@ impl Default for Config {embedding_base_url: None,decay: ai_memory_store::DecayParams::default(),maintenance: MaintenanceSettings::default(),+ auto_improve: AutoImproveSettings::default(),sanitize: ai_memory_core::SanitizeConfig::default(),auth: AuthSettings::default(),auto_scope: AutoScopeSettings::default(),@@ -353,6 +360,68 @@ impl Default for Config {}}+/// Write mode for the optional auto-improvement loop.+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]+#[serde(rename_all = "snake_case")]+pub enum AutoImproveMode {+ /// Report-only preview; no wiki or pending-proposal writes.+ #[default]+ DryRun,+ /// Store proposals for human approval. Intended default once storage ships.+ Stage,+ /// Future mode only: apply narrow high-confidence proposals automatically.+ AutoApply,+}++/// `[auto_improve]` optional post-session reviewer settings.+#[derive(Debug, Clone, Serialize, Deserialize)]+#[serde(default)]+pub struct AutoImproveSettings {+ /// Master switch. Defaults to false; manual dry-runs can still pass+ /// explicit CLI flags without enabling the session-end trigger.+ pub enabled: bool,+ /// Configured write mode. The first shipped command supports dry-run only.+ pub mode: AutoImproveMode,+ /// Whether SessionEnd should schedule a reviewer run. Defaults off so hooks+ /// stay cheap and fire-and-forget.+ pub on_session_end: bool,+ /// Minimum observations before a session is worth reviewing.+ pub min_observations: usize,+ /// Minimum span between first and last observation before review.+ pub min_session_duration_secs: u64,+ /// Minimum model confidence accepted by validation.+ pub min_confidence: f32,+ /// Approximate chars/4 prompt budget for review input.+ pub max_input_tokens: usize,+ /// Maximum validated proposals returned from one run.+ pub max_proposals_per_run: usize,+ /// Whether future reviewers may include raw observation fallback details.+ pub include_raw_fallback: bool,+ /// Synthetic actor used for autonomous proposal provenance.+ pub proposal_actor: String,+ /// Wiki-relative pending proposal folder once staging ships.+ pub pending_path: String,+}++impl Default for AutoImproveSettings {+ fn default() -> Self {+ Self {+ enabled: true,+ mode: AutoImproveMode::DryRun,+ on_session_end: false,+ min_observations: ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MIN_OBSERVATIONS,+ min_session_duration_secs:+ ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MIN_SESSION_DURATION_SECS,+ min_confidence: DEFAULT_AUTO_IMPROVE_MIN_CONFIDENCE,+ max_input_tokens: ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_INPUT_TOKENS,+ max_proposals_per_run: ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_PROPOSALS,+ include_raw_fallback: false,+ proposal_actor: ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_PROPOSAL_ACTOR.into(),+ pending_path: ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_PENDING_PATH.into(),+ }+ }+}+/// `[maintenance]` scheduled server jobs.#[derive(Debug, Clone, Serialize, Deserialize)]#[serde(default)]@@ -735,6 +804,20 @@ mod tests {assert_eq!(cfg.maintenance.forget_sweep_interval_secs, 86_400);assert_eq!(cfg.maintenance.lint_interval_secs, 86_400);assert_eq!(cfg.maintenance.embedding_backfill_interval_secs, 0);+ assert!(cfg.auto_improve.enabled);+ assert_eq!(cfg.auto_improve.mode, AutoImproveMode::DryRun);+ assert!(!cfg.auto_improve.on_session_end);+ assert_eq!(cfg.auto_improve.min_observations, 8);+ assert_eq!(cfg.auto_improve.min_session_duration_secs, 120);+ assert_eq!(+ cfg.auto_improve.min_confidence,+ DEFAULT_AUTO_IMPROVE_MIN_CONFIDENCE+ );+ assert_eq!(cfg.auto_improve.max_input_tokens, 24_000);+ assert_eq!(cfg.auto_improve.max_proposals_per_run, 5);+ assert!(!cfg.auto_improve.include_raw_fallback);+ assert_eq!(cfg.auto_improve.proposal_actor, "auto_improve");+ assert_eq!(cfg.auto_improve.pending_path, "_pending/auto-improve");}#[test]@@ -767,6 +850,19 @@ mod tests {[maintenance]enabled = falselint_interval_secs = 3600++ [auto_improve]+ enabled = true+ mode = "dry_run"+ on_session_end = true+ min_observations = 3+ min_session_duration_secs = 45+ min_confidence = 0.9+ max_input_tokens = 12000+ max_proposals_per_run = 2+ include_raw_fallback = true+ proposal_actor = "review_bot"+ pending_path = "_pending/review-bot""#,).unwrap();@@ -778,6 +874,17 @@ mod tests {assert_eq!(cfg.log_level, "debug");assert!(!cfg.maintenance.enabled);assert_eq!(cfg.maintenance.lint_interval_secs, 3600);+ assert!(cfg.auto_improve.enabled);+ assert_eq!(cfg.auto_improve.mode, AutoImproveMode::DryRun);+ assert!(cfg.auto_improve.on_session_end);+ assert_eq!(cfg.auto_improve.min_observations, 3);+ assert_eq!(cfg.auto_improve.min_session_duration_secs, 45);+ assert_eq!(cfg.auto_improve.min_confidence, 0.9);+ assert_eq!(cfg.auto_improve.max_input_tokens, 12_000);+ assert_eq!(cfg.auto_improve.max_proposals_per_run, 2);+ assert!(cfg.auto_improve.include_raw_fallback);+ assert_eq!(cfg.auto_improve.proposal_actor, "review_bot");+ assert_eq!(cfg.auto_improve.pending_path, "_pending/review-bot");}#[test]diff --git a/crates/ai-memory-cli/src/main.rs b/crates/ai-memory-cli/src/main.rsindex b7234ae6..2ca38f99 100644--- a/crates/ai-memory-cli/src/main.rs+++ b/crates/ai-memory-cli/src/main.rs@@ -75,6 +75,7 @@ async fn main() -> Result<()> {Command::LlmTest(args) => commands::llm_test::run(&config, args).await,Command::ForgetSweep(args) => commands::forget_sweep::run(&config, args).await,Command::Lint(args) => commands::lint::run(&config, args).await,+ Command::AutoImprove(args) => commands::auto_improve::run(&config, args).await,Command::Embed(args) => commands::embed::run(&config, args).await,Command::GenerateAuthToken(args) => commands::generate_auth_token::run(&config, args),Command::SetupAgent(args) => commands::setup_agent::run(&config, args),diff --git a/crates/ai-memory-consolidate/Cargo.toml b/crates/ai-memory-consolidate/Cargo.tomlindex 4f94c9cd..12c65e87 100644--- a/crates/ai-memory-consolidate/Cargo.toml+++ b/crates/ai-memory-consolidate/Cargo.toml@@ -24,6 +24,7 @@ tracing.workspace = truejiff.workspace = true[dev-dependencies]+async-trait.workspace = truetempfile.workspace = truerusqlite.workspace = truediff --git a/crates/ai-memory-consolidate/src/auto_improve.rs b/crates/ai-memory-consolidate/src/auto_improve.rsnew file mode 100644index 00000000..8ec9b877--- /dev/null+++ b/crates/ai-memory-consolidate/src/auto_improve.rs@@ -0,0 +1,1107 @@+//! Dry-run reviewer for optional auto-improvement proposals.+//!+//! This module is intentionally read-only. It inspects one completed session,+//! asks the configured LLM for structured wiki edit proposals, validates those+//! proposals, and returns a report. Staging and approval live in a later phase.++use std::collections::BTreeSet;++use ai_memory_core::{Observation, ObservationKind, PagePath, ProjectId, SessionId, WorkspaceId};+use ai_memory_llm::{ChatMessage, ChatRequest, LlmError, LlmProvider, Role, complete_structured};+use ai_memory_store::{BriefingPage, ReaderPool, StoredPageBody};+use schemars::JsonSchema;+use serde::{Deserialize, Serialize};+use thiserror::Error;++const CHARS_PER_TOKEN: usize = 4;+const PROMPT_RESERVE_TOKENS: usize = 1_000;+const MAX_PROPOSAL_BODY_CHARS: usize = 32_000;+const DEFAULT_REVIEW_MAX_TOKENS: u32 = 16_000;+const MAX_SESSION_PAGE_CHARS: usize = 32_000;+const MAX_OBSERVATION_BODY_CHARS: usize = 1_500;+const SAMPLE_LIMIT_WITH_SESSION_PAGE: usize = 48;+const SAMPLE_LIMIT_WITHOUT_SESSION_PAGE: usize = 72;+const EVEN_SAMPLE_BUCKETS: usize = 16;+const PROMPT_SCAFFOLD_RESERVE_CHARS: usize = 4_000;++/// Default confidence floor for staged auto-improvement proposals.+pub const DEFAULT_AUTO_IMPROVE_MIN_CONFIDENCE: f32 = 0.75;+/// Default minimum observation count before a session is reviewed.+pub const DEFAULT_AUTO_IMPROVE_MIN_OBSERVATIONS: usize = 8;+/// Default minimum session duration before a session is reviewed.+pub const DEFAULT_AUTO_IMPROVE_MIN_SESSION_DURATION_SECS: u64 = 120;+/// Default approximate input token budget for one review.+pub const DEFAULT_AUTO_IMPROVE_MAX_INPUT_TOKENS: usize = 24_000;+/// Default maximum validated proposals per review.+pub const DEFAULT_AUTO_IMPROVE_MAX_PROPOSALS: usize = 5;+/// Default synthetic actor name for autonomous proposal provenance.+pub const DEFAULT_AUTO_IMPROVE_PROPOSAL_ACTOR: &str = "auto_improve";+/// Default wiki-relative folder for future pending proposal markdown.+pub const DEFAULT_AUTO_IMPROVE_PENDING_PATH: &str = "_pending/auto-improve";++/// Configuration for one dry-run auto-improvement review.+#[derive(Debug, Clone)]+pub struct AutoImproveReviewConfig {+ /// Minimum observations before a session is worth reviewing.+ pub min_observations: usize,+ /// Minimum session duration before a session is worth reviewing.+ pub min_session_duration_secs: u64,+ /// Minimum model confidence accepted by validation.+ pub min_confidence: f32,+ /// Approximate input token budget, using chars/4.+ pub max_input_tokens: usize,+ /// Maximum validated proposals returned from one run.+ pub max_proposals_per_run: usize,+ /// Whether raw fallback content may be considered. Reserved for prompt+ /// visibility in this dry-run slice; hooks still provide raw observations.+ pub include_raw_fallback: bool,+ /// Synthetic actor name used for future proposal provenance.+ pub proposal_actor: String,+ /// Wiki-relative pending proposal folder once staging ships.+ pub pending_path: String,+}++/// Errors raised by the dry-run reviewer.+#[derive(Debug, Error)]+pub enum AutoImproveError {+ /// Underlying store error.+ #[error(transparent)]+ Store(#[from] ai_memory_store::StoreError),+ /// Underlying LLM error.+ #[error(transparent)]+ Llm(#[from] LlmError),+ /// Domain parsing error.+ #[error(transparent)]+ Memory(#[from] ai_memory_core::MemoryError),+ /// Session was not found.+ #[error("session not found: {0}")]+ SessionNotFound(SessionId),+ /// Session belongs to a different scope than the request selected.+ #[error("session {session_id} belongs to a different workspace/project")]+ SessionOutOfScope {+ /// Session that failed the scope check.+ session_id: SessionId,+ },+}++/// Result alias for auto-improvement review.+pub type AutoImproveResult<T> = Result<T, AutoImproveError>;++/// One evidence quote cited by a proposal.+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]+pub struct AutoImproveEvidence {+ /// Source page or observation label, such as `sessions/<id>.md`.+ pub page: String,+ /// Bounded quote supporting the proposed durable edit.+ pub quote: String,+}++/// One proposed wiki edit returned by the LLM and accepted by validation.+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]+pub struct AutoImproveProposal {+ /// Currently only `create_or_update` is supported.+ pub operation: String,+ /// Relative wiki path that would be created or updated.+ pub path: String,+ /// Human title for the proposed page.+ pub title: String,+ /// Semantic kind: gotcha, decision, concept, procedure, rule, fact, note, or slot.+ pub kind: String,+ /// Model confidence from 0.0 to 1.0.+ pub confidence: f32,+ /// Why the lesson is durable enough to propose.+ pub rationale: String,+ /// Evidence quotes that justify the proposal.+ #[serde(default)]+ pub evidence: Vec<AutoImproveEvidence>,+ /// Markdown body without frontmatter.+ pub body_markdown: String,+}++/// A candidate the reviewer or validator rejected.+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]+pub struct AutoImproveRejectedCandidate {+ /// Machine-readable-ish reason for rejection.+ pub reason: String,+ /// Evidence label or short detail.+ pub evidence: String,+}++/// Structured response requested from the LLM.+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]+pub struct AutoImproveLlmResponse {+ /// Short summary of the review.+ pub summary: String,+ /// Candidate edits.+ #[serde(default)]+ pub proposals: Vec<AutoImproveProposal>,+ /// Candidates the model chose not to promote.+ #[serde(default)]+ pub rejected_candidates: Vec<AutoImproveRejectedCandidate>,+}++/// Report returned by the dry-run reviewer.+#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct AutoImproveReport {+ /// Always true for this first implementation slice.+ pub dry_run: bool,+ /// Reviewed session id.+ pub session_id: String,+ /// Number of observations read from the session.+ pub observations_considered: usize,+ /// Approximate session span, first observation to last observation.+ pub session_duration_secs: u64,+ /// Approximate prompt tokens sent to the LLM, chars/4.+ pub estimated_input_tokens: usize,+ /// LLM provider name, or `none` when the preflight filter skipped the call.+ pub provider: String,+ /// LLM model, or `none` when the preflight filter skipped the call.+ pub model: String,+ /// Configured confidence floor used by validation.+ pub min_confidence: f32,+ /// Actor name reserved for future staged proposal provenance.+ pub proposal_actor: String,+ /// Wiki-relative pending path reserved for future staged proposal markdown.+ pub pending_path: String,+ /// Review summary.+ pub summary: String,+ /// Validated proposals. No wiki writes have occurred.+ pub proposals: Vec<AutoImproveProposal>,+ /// Model and validator rejections.+ pub rejected_candidates: Vec<AutoImproveRejectedCandidate>,+ /// Non-fatal validation or budget notes.+ pub warnings: Vec<String>,+}++/// Run a dry-run auto-improvement review for one session.+///+/// # Errors+/// Returns store, scope, or LLM errors. This function never writes wiki files or+/// SQLite rows.+pub async fn run_auto_improve_review(+ reader: &ReaderPool,+ llm: &(dyn LlmProvider + 'static),+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ session_id: SessionId,+ cfg: AutoImproveReviewConfig,+) -> AutoImproveResult<AutoImproveReport> {+ match reader.session_project_ids(session_id).await? {+ Some((session_ws, session_proj))+ if session_ws == workspace_id && session_proj == project_id => {}+ Some(_) => return Err(AutoImproveError::SessionOutOfScope { session_id }),+ None => return Err(AutoImproveError::SessionNotFound(session_id)),+ }++ let observations = reader.observations_for_session(session_id).await?;+ let duration = session_duration_secs(&observations);+ if let Some(rejection) = preflight_rejection(&observations, duration, &cfg) {+ return Ok(AutoImproveReport {+ dry_run: true,+ session_id: session_id.to_string(),+ observations_considered: observations.len(),+ session_duration_secs: duration,+ estimated_input_tokens: 0,+ provider: "none".into(),+ model: "none".into(),+ min_confidence: cfg.min_confidence,+ proposal_actor: cfg.proposal_actor,+ pending_path: cfg.pending_path,+ summary: "session skipped by preflight filters".into(),+ proposals: Vec::new(),+ rejected_candidates: vec![rejection],+ warnings: Vec::new(),+ });+ }++ let briefing = reader+ .briefing_for_project(workspace_id, project_id, 100)+ .await?;+ let session_page_path = format!("sessions/{session_id}.md");+ let session_page = reader+ .page_body_by_ids(workspace_id, project_id, &session_page_path)+ .await?;+ let existing_index = ExistingPageIndex::from_pages(&briefing.recent_pages);+ let prompt_input = build_prompt_input(+ session_id,+ &observations,+ duration,+ session_page.as_ref(),+ &briefing.recent_pages,+ &cfg,+ );+ let estimated_input_tokens = estimate_tokens(&prompt_input.prompt);+ let request = ChatRequest {+ system: Some(AUTO_IMPROVE_SYSTEM_PROMPT.to_string()),+ messages: vec![ChatMessage {+ role: Role::User,+ content: prompt_input.prompt,+ }],+ max_tokens: DEFAULT_REVIEW_MAX_TOKENS,+ temperature: Some(0.1),+ };+ let raw: AutoImproveLlmResponse = complete_structured(llm, request).await?;+ let (proposals, mut rejected_candidates, mut warnings) =+ validate_response(raw, &cfg, &existing_index);+ rejected_candidates.extend(prompt_input.rejected_candidates);+ warnings.extend(prompt_input.warnings);++ Ok(AutoImproveReport {+ dry_run: true,+ session_id: session_id.to_string(),+ observations_considered: observations.len(),+ session_duration_secs: duration,+ estimated_input_tokens,+ provider: llm.name().to_string(),+ model: llm.model().to_string(),+ min_confidence: cfg.min_confidence,+ proposal_actor: cfg.proposal_actor,+ pending_path: cfg.pending_path,+ summary: if proposals.is_empty() {+ "review completed; no validated proposals".into()+ } else {+ format!(+ "review completed; {} proposal(s) validated",+ proposals.len()+ )+ },+ proposals,+ rejected_candidates,+ warnings,+ })+}++struct PromptInput {+ prompt: String,+ rejected_candidates: Vec<AutoImproveRejectedCandidate>,+ warnings: Vec<String>,+}++#[derive(Debug, Default)]+struct ExistingPageIndex {+ paths: BTreeSet<String>,+ titles: BTreeSet<String>,+}++impl ExistingPageIndex {+ fn from_pages(pages: &[BriefingPage]) -> Self {+ Self {+ paths: pages.iter().map(|page| page.path.clone()).collect(),+ titles: pages+ .iter()+ .map(|page| normalize_title(&page.title))+ .filter(|title| !title.is_empty())+ .collect(),+ }+ }++ fn contains_path(&self, path: &str) -> bool {+ self.paths.contains(path)+ }++ fn contains_title(&self, title: &str) -> bool {+ let normalized = normalize_title(title);+ !normalized.is_empty() && self.titles.contains(&normalized)+ }+}++fn normalize_title(title: &str) -> String {+ title+ .split_whitespace()+ .collect::<Vec<_>>()+ .join(" ")+ .to_lowercase()+}++fn build_prompt_input(+ session_id: SessionId,+ observations: &[Observation],+ duration_secs: u64,+ session_page: Option<&StoredPageBody>,+ recent_pages: &[BriefingPage],+ cfg: &AutoImproveReviewConfig,+) -> PromptInput {+ let mut warnings = Vec::new();+ let mut rejected_candidates = Vec::new();+ let usable_tokens = cfg.max_input_tokens.saturating_sub(PROMPT_RESERVE_TOKENS);+ let usable_chars = usable_tokens.saturating_mul(CHARS_PER_TOKEN);++ let recent = render_recent_pages(recent_pages);+ let session_page_budget = session_page+ .map(|_| usable_chars / 3)+ .unwrap_or(0)+ .min(MAX_SESSION_PAGE_CHARS);+ let session_page_section =+ render_session_page(session_page, session_page_budget, &mut warnings);+ let observation_budget = usable_chars+ .saturating_sub(recent.len())+ .saturating_sub(session_page_section.len())+ .saturating_sub(PROMPT_SCAFFOLD_RESERVE_CHARS);+ let (rendered_observations, selected_count) = render_sampled_observations(+ observations,+ session_page.is_some(),+ observation_budget,+ &mut warnings,+ );++ if selected_count < observations.len() {+ rejected_candidates.push(AutoImproveRejectedCandidate {+ reason: "input_budget_sampled".into(),+ evidence: format!(+ "selected {selected_count} of {} observations for scalable review",+ observations.len()+ ),+ });+ }++ let prompt = format!(+ "Review one completed ai-memory session and propose only durable wiki edits.\n\+ Session: {session_id}\n\+ Observation count: {}\n\+ Session duration seconds: {duration_secs}\n\+ Minimum confidence: {}\n\+ Max proposals: {}\n\+ Include raw fallback: {}\n\+ Pending path for future staging: {}\n\n\+ Existing project pages, for duplicate avoidance. Do not target these existing paths or titles; diff-based update proposals are a later phase:\n{recent}\n\n\+ Consolidated session page, primary source when present:\n{session_page_section}\n\n\+ Selected observations, sampled for scale and supporting evidence:\n{rendered_observations}\n\n\+ Return proposals only for durable lessons. Prefer gotchas/, decisions/, concepts/, procedures/, _rules/, _slots/current-focus.md, or notes/. Use _rules/ exactly for rules; never rules/. Body markdown must begin with '# <title>'. Reject no-activity sessions, smoke tests, release markers, one-off task narratives, transient failures, generic routing snippets, and agent instruction text unless the session explicitly changed project policy.",+ observations.len(),+ cfg.min_confidence,+ cfg.max_proposals_per_run,+ cfg.include_raw_fallback,+ cfg.pending_path,+ );++ PromptInput {+ prompt,+ rejected_candidates,+ warnings,+ }+}++fn render_session_page(+ page: Option<&StoredPageBody>,+ max_chars: usize,+ warnings: &mut Vec<String>,+) -> String {+ let Some(page) = page else {+ return "(none; relying on sampled observations)".into();+ };+ if max_chars == 0 {+ warnings.push("session page exists but input budget left no room for it".into());+ return "(omitted by input budget)".into();+ }+ let (body, truncated) = truncate_with_marker(&page.body, max_chars, "[session page truncated]");+ if truncated {+ warnings.push(format!(+ "session page body truncated to {max_chars} chars before review"+ ));+ }+ format!(+ "title: {}\ntier: {}\npinned: {}\nbody:\n{}\n",+ page.title, page.tier, page.pinned, body+ )+}++fn render_sampled_observations(+ observations: &[Observation],+ has_session_page: bool,+ max_chars: usize,+ warnings: &mut Vec<String>,+) -> (String, usize) {+ if observations.is_empty() {+ return ("(none)".into(), 0);+ }+ if max_chars == 0 {+ warnings.push("observation sample omitted because session page and page index filled the input budget".into());+ return ("(omitted by input budget)".into(), 0);+ }++ let limit = if has_session_page {+ SAMPLE_LIMIT_WITH_SESSION_PAGE+ } else {+ SAMPLE_LIMIT_WITHOUT_SESSION_PAGE+ };+ let indices = select_observation_indices(observations, limit);+ let mut rendered = String::new();+ let mut kept = 0usize;++ for idx in indices {+ let Some(obs) = observations.get(idx) else {+ continue;+ };+ let chunk = render_observation(idx, observations.len(), obs);+ if !rendered.is_empty() && rendered.len().saturating_add(chunk.len()) > max_chars {+ warnings.push(format!(+ "observation sample stopped after {kept} selected observations to stay under max_input_tokens"+ ));+ break;+ }+ rendered.push_str(&chunk);+ kept += 1;+ }++ if kept < observations.len() {+ warnings.push(format!(+ "observation input sampled {kept} of {} observations for scalable review",+ observations.len()+ ));+ }++ if rendered.is_empty() {+ rendered.push_str("(none fit the input budget)");+ }+ (rendered, kept)+}++fn select_observation_indices(observations: &[Observation], limit: usize) -> Vec<usize> {+ if observations.len() <= limit {+ return (0..observations.len()).collect();+ }+ let even = even_sample_indices(observations.len());+ let mut scored: Vec<(i32, usize)> = observations+ .iter()+ .enumerate()+ .map(|(idx, obs)| {+ let mut score = observation_score(obs, idx, observations.len());+ if even.contains(&idx) {+ score += 40;+ }+ (score, idx)+ })+ .collect();+ scored.sort_by(|a, b| b.0.cmp(&a.0).then_with(|| a.1.cmp(&b.1)));++ let selected: BTreeSet<usize> = scored.into_iter().take(limit).map(|(_, idx)| idx).collect();+ selected.into_iter().collect()+}++fn even_sample_indices(total: usize) -> BTreeSet<usize> {+ let mut out = BTreeSet::new();+ if total == 0 {+ return out;+ }+ if total == 1 {+ out.insert(0);+ return out;+ }+ let buckets = EVEN_SAMPLE_BUCKETS.min(total);+ for bucket in 0..buckets {+ let idx = bucket.saturating_mul(total - 1) / (buckets - 1).max(1);+ out.insert(idx);+ }+ out+}++fn observation_score(obs: &Observation, idx: usize, total: usize) -> i32 {+ let mut score = i32::from(obs.importance);+ score += match obs.kind {+ ObservationKind::UserPrompt => 80,+ ObservationKind::SessionEnd => 70,+ ObservationKind::Stop => 55,+ ObservationKind::PreCompact => 45,+ ObservationKind::PostToolUse => 30,+ ObservationKind::Notification => 25,+ ObservationKind::SessionStart => 20,+ ObservationKind::Other => 15,+ ObservationKind::PreToolUse => 5,+ };+ if idx == 0 || idx + 1 == total {+ score += 100;+ }++ let body_prefix = obs.body.chars().take(4_000).collect::<String>();+ let text = format!("{}\n{}", obs.title, body_prefix).to_ascii_lowercase();+ for keyword in [+ "root cause",+ "fix",+ "fixed",+ "failed",+ "failure",+ "error",+ "bug",+ "regression",+ "decision",+ "decided",+ "gotcha",+ "rule",+ "always",+ "never",+ "migration",+ "scope",+ "workspace",+ "project",+ "auth",+ "test",+ "clippy",+ "release",+ ] {+ if text.contains(keyword) {+ score += 15;+ }+ }+ if obs.body.contains("```") {+ score += 8;+ }+ if text.contains("long-term memory (ai-memory)")+ || text.contains("install ai-memory routing")+ || text.contains("memory_query searches only one project")+ {+ score -= 80;+ }+ score+}++fn render_recent_pages(pages: &[BriefingPage]) -> String {+ if pages.is_empty() {+ return "(none)".into();+ }+ let mut out = String::new();+ for page in pages {+ out.push_str(&format!(+ "- {} | {} | {} | updated {}\n",+ page.path, page.title, page.kind, page.updated_at+ ));+ }+ out+}++fn render_observation(idx: usize, total: usize, obs: &Observation) -> String {+ let (body, _) = truncate_with_marker(+ &obs.body,+ MAX_OBSERVATION_BODY_CHARS,+ "[observation truncated]",+ );+ format!(+ "\n--- observation {}/{} {} ---\nkind: {}\ntitle: {}\nimportance: {}\ncreated_at: {}\nbody:\n{}\n",+ idx + 1,+ total,+ obs.id,+ obs.kind.as_str(),+ obs.title,+ obs.importance,+ obs.created_at,+ body+ )+}++fn truncate_with_marker(input: &str, max_bytes: usize, marker: &str) -> (String, bool) {+ if input.len() <= max_bytes {+ return (input.to_string(), false);+ }+ let mut end = max_bytes.min(input.len());+ while end > 0 && !input.is_char_boundary(end) {+ end -= 1;+ }+ let mut out = input[..end].to_string();+ out.push('\n');+ out.push_str(marker);+ (out, true)+}++fn preflight_rejection(+ observations: &[Observation],+ duration_secs: u64,+ cfg: &AutoImproveReviewConfig,+) -> Option<AutoImproveRejectedCandidate> {+ if observations.len() < cfg.min_observations {+ return Some(AutoImproveRejectedCandidate {+ reason: "too_few_observations".into(),+ evidence: format!(+ "{} observations below configured minimum {}",+ observations.len(),+ cfg.min_observations+ ),+ });+ }+ if duration_secs < cfg.min_session_duration_secs {+ return Some(AutoImproveRejectedCandidate {+ reason: "session_too_short".into(),+ evidence: format!(+ "{duration_secs}s below configured minimum {}s",+ cfg.min_session_duration_secs+ ),+ });+ }+ None+}++fn validate_response(+ raw: AutoImproveLlmResponse,+ cfg: &AutoImproveReviewConfig,+ existing_index: &ExistingPageIndex,+) -> (+ Vec<AutoImproveProposal>,+ Vec<AutoImproveRejectedCandidate>,+ Vec<String>,+) {+ let mut proposals = Vec::new();+ let mut rejected = raw.rejected_candidates;+ let mut warnings = Vec::new();++ for mut proposal in raw.proposals {+ if proposals.len() >= cfg.max_proposals_per_run {+ rejected.push(AutoImproveRejectedCandidate {+ reason: "max_proposals_exceeded".into(),+ evidence: proposal.path,+ });+ continue;+ }+ normalize_proposal(&mut proposal, &mut warnings);+ match validate_proposal(&proposal, cfg, existing_index) {+ Ok(()) => proposals.push(proposal),+ Err(reason) => rejected.push(AutoImproveRejectedCandidate {+ reason,+ evidence: proposal.path,+ }),+ }+ }++ if raw.summary.trim().is_empty() {+ warnings.push("LLM returned an empty review summary".into());+ }++ (proposals, rejected, warnings)+}++fn normalize_proposal(proposal: &mut AutoImproveProposal, warnings: &mut Vec<String>) {+ if proposal.body_markdown.trim_start().starts_with("# ") {+ return;+ }+ let title = proposal.title.trim();+ let body = proposal.body_markdown.trim_start();+ if title.is_empty() || body.is_empty() {+ return;+ }+ proposal.body_markdown = format!("# {title}\n\n{body}");+ warnings.push(format!(+ "proposal {} body lacked an H1; prepended title as H1 before validation",+ proposal.path+ ));+}++fn validate_proposal(+ proposal: &AutoImproveProposal,+ cfg: &AutoImproveReviewConfig,+ existing_index: &ExistingPageIndex,+) -> Result<(), String> {+ if proposal.operation != "create_or_update" {+ return Err("unsupported_operation".into());+ }+ if proposal.confidence < cfg.min_confidence {+ return Err("confidence_below_threshold".into());+ }+ if proposal.rationale.trim().is_empty() {+ return Err("missing_rationale".into());+ }+ if proposal.evidence.is_empty()+ || proposal+ .evidence+ .iter()+ .any(|e| e.page.trim().is_empty() || e.quote.trim().is_empty())+ {+ return Err("missing_evidence".into());+ }+ if proposal.body_markdown.trim().is_empty() {+ return Err("empty_body".into());+ }+ if proposal.body_markdown.len() > MAX_PROPOSAL_BODY_CHARS {+ return Err("body_too_large".into());+ }+ if !proposal.body_markdown.trim_start().starts_with("# ") {+ return Err("body_missing_h1".into());+ }+ let path = PagePath::new(proposal.path.clone()).map_err(|_| "invalid_path".to_string())?;+ if !allowed_target_path(path.as_str()) {+ return Err("unsupported_path_prefix".into());+ }+ if path.as_str() != "_slots/current-focus.md" && existing_index.contains_path(path.as_str()) {+ return Err("duplicate_existing_path".into());+ }+ if path.as_str() != "_slots/current-focus.md" && existing_index.contains_title(&proposal.title)+ {+ return Err("duplicate_existing_title".into());+ }+ if !kind_matches_path(&proposal.kind, path.as_str()) {+ return Err("kind_path_mismatch".into());+ }+ Ok(())+}++fn allowed_target_path(path: &str) -> bool {+ path.starts_with("gotchas/")+ || path.starts_with("decisions/")+ || path.starts_with("concepts/")+ || path.starts_with("procedures/")+ || path.starts_with("_rules/")+ || path.starts_with("notes/")+ || path == "_slots/current-focus.md"+}++fn kind_matches_path(kind: &str, path: &str) -> bool {+ match kind {+ "gotcha" => path.starts_with("gotchas/"),+ "decision" => path.starts_with("decisions/"),+ "concept" => path.starts_with("concepts/"),+ "procedure" => path.starts_with("procedures/"),+ "rule" => path.starts_with("_rules/"),+ "slot" => path.starts_with("_slots/"),+ "fact" | "note" => path.starts_with("notes/") || path.starts_with("concepts/"),+ _ => false,+ }+}++fn session_duration_secs(observations: &[Observation]) -> u64 {+ let (Some(first), Some(last)) = (observations.first(), observations.last()) else {+ return 0;+ };+ let diff_us = last+ .created_at+ .as_microsecond()+ .saturating_sub(first.created_at.as_microsecond());+ u64::try_from(diff_us / 1_000_000).unwrap_or(0)+}++fn estimate_tokens(text: &str) -> usize {+ text.len().div_ceil(CHARS_PER_TOKEN)+}++const AUTO_IMPROVE_SYSTEM_PROMPT: &str = r#"You are ai-memory's dry-run auto-improvement reviewer.++Return structured JSON matching the schema. You are proposing wiki edits, not applying them.++Only propose durable, future-useful knowledge:+- gotchas: reproducible pitfalls with a root cause and mitigation+- decisions: choices with rationale and consequences+- concepts: stable architecture or domain knowledge+- procedures: reusable multi-step workflows+- rules: explicit always/never instructions+- notes: useful facts that do not fit stronger categories++Reject transient setup failures, smoke tests, release markers, one-off task narratives, broad negative tool claims, and failures that were resolved without a reusable lesson.++Every proposal must include bounded evidence quotes, confidence, rationale, a valid path, and markdown beginning with an H1. Rule paths must start with `_rules/`, not `rules/`. Do not target sessions/ or _pending/. Treat the consolidated session page as primary when present; selected observations are supporting context. Do not promote ai-memory routing snippets, AGENTS.md/CLAUDE.md instructions, or generic agent tool guidance unless the session explicitly changed project policy."#;++#[cfg(test)]+mod tests {+ use super::*;+ use ai_memory_core::{AgentKind, NewObservation, NewSession, ObservationId, ObservationKind};+ use ai_memory_llm::{ChatResponse, LlmResult};+ use ai_memory_store::Store;+ use jiff::Timestamp;+ use tempfile::TempDir;++ struct FakeLlm;++ #[async_trait::async_trait]+ impl LlmProvider for FakeLlm {+ fn name(&self) -> &'static str {+ "fake"+ }++ fn model(&self) -> &str {+ "fake-model"+ }++ async fn complete(&self, _request: ChatRequest) -> LlmResult<ChatResponse> {+ Ok(ChatResponse {+ text: "unused".into(),+ usage: None,+ model: "fake-model".into(),+ })+ }++ async fn complete_structured_raw(+ &self,+ _request: ChatRequest,+ _schema: serde_json::Value,+ ) -> LlmResult<serde_json::Value> {+ Ok(serde_json::json!({+ "summary": "found one durable procedure",+ "proposals": [{+ "operation": "create_or_update",+ "path": "procedures/release.md",+ "title": "Release Procedure",+ "kind": "procedure",+ "confidence": 0.91,+ "rationale": "The session repeated a release workflow with verification.",+ "evidence": [{"page": "sessions/test.md", "quote": "run the full gate before release"}],+ "body_markdown": "# Release Procedure\n\nRun the full gate before release."+ }],+ "rejected_candidates": []+ }))+ }+ }++ fn cfg() -> AutoImproveReviewConfig {+ AutoImproveReviewConfig {+ min_observations: 3,+ min_session_duration_secs: 60,+ min_confidence: 0.75,+ max_input_tokens: 24_000,+ max_proposals_per_run: 2,+ include_raw_fallback: false,+ proposal_actor: "auto_improve".into(),+ pending_path: "_pending/auto-improve".into(),+ }+ }++ fn proposal(path: &str, kind: &str, confidence: f32) -> AutoImproveProposal {+ AutoImproveProposal {+ operation: "create_or_update".into(),+ path: path.into(),+ title: "Test".into(),+ kind: kind.into(),+ confidence,+ rationale: "durable lesson".into(),+ evidence: vec![AutoImproveEvidence {+ page: "sessions/abc.md".into(),+ quote: "quote".into(),+ }],+ body_markdown: "# Test\n\nBody".into(),+ }+ }++ fn obs(+ idx: usize,+ kind: ObservationKind,+ title: &str,+ body: &str,+ importance: u8,+ ) -> Observation {+ Observation {+ id: ObservationId::new(),+ workspace_id: WorkspaceId::new(),+ project_id: ProjectId::new(),+ session_id: SessionId::new(),+ kind,+ extension: None,+ source_event: None,+ title: title.into(),+ body: body.into(),+ importance,+ created_at: Timestamp::from_microsecond(idx as i64 * 1_000_000)+ .expect("test timestamp is valid"),+ }+ }++ #[tokio::test]+ async fn reviewer_returns_validated_llm_proposals_without_writes() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "proj", None)+ .await+ .unwrap();+ let session_id = ai_memory_core::SessionId::new();+ store+ .writer+ .begin_session(NewSession {+ id: session_id,+ workspace_id: ws,+ project_id: proj,+ agent_kind: AgentKind::Other,+ cwd: None,+ })+ .await+ .unwrap();+ for i in 0..3 {+ store+ .writer+ .insert_observation(NewObservation {+ session_id,+ workspace_id: ws,+ project_id: proj,+ kind: if i == 0 {+ ObservationKind::SessionStart+ } else {+ ObservationKind::UserPrompt+ },+ extension: None,+ source_event: None,+ title: format!("event {i}"),+ body: "run the full gate before release".into(),+ importance: 5,+ })+ .await+ .unwrap();+ }++ let report = run_auto_improve_review(+ &store.reader,+ &FakeLlm,+ ws,+ proj,+ session_id,+ AutoImproveReviewConfig {+ min_session_duration_secs: 0,+ ..cfg()+ },+ )+ .await+ .unwrap();++ assert!(report.dry_run);+ assert_eq!(report.provider, "fake");+ assert_eq!(report.model, "fake-model");+ assert_eq!(report.proposals.len(), 1);+ assert_eq!(report.proposals[0].path, "procedures/release.md");+ assert!(report.rejected_candidates.is_empty());+ }++ #[test]+ fn validation_accepts_procedure_pages() {+ let raw = AutoImproveLlmResponse {+ summary: "ok".into(),+ proposals: vec![proposal("procedures/release.md", "procedure", 0.91)],+ rejected_candidates: Vec::new(),+ };+ let (accepted, rejected, warnings) =+ validate_response(raw, &cfg(), &ExistingPageIndex::default());+ assert_eq!(accepted.len(), 1);+ assert!(rejected.is_empty());+ assert!(warnings.is_empty());+ }++ #[test]+ fn prompt_uses_session_page_and_samples_high_signal_long_sessions() {+ let session_id = SessionId::new();+ let mut observations: Vec<Observation> = (0..200)+ .map(|idx| {+ obs(+ idx,+ ObservationKind::PostToolUse,+ "routine",+ "boring output",+ 3,+ )+ })+ .collect();+ observations[180] = obs(+ 180,+ ObservationKind::PostToolUse,+ "root cause found",+ "root cause was a stale scope cache; fixed by re-resolving project scope after write errors",+ 10,+ );+ let page = StoredPageBody {+ title: "Large Session Summary".into(),+ body: "# Large Session Summary\n\nThe session audited scalable project isolation."+ .into(),+ frontmatter_json: "{}".into(),+ tier: "episodic".into(),+ pinned: false,+ };++ let prompt = build_prompt_input(+ session_id,+ &observations,+ 3_600,+ Some(&page),+ &[],+ &AutoImproveReviewConfig {+ max_input_tokens: 8_000,+ ..cfg()+ },+ );++ assert!(prompt.prompt.contains("Large Session Summary"));+ assert!(prompt.prompt.contains("root cause was a stale scope cache"));+ assert!(prompt.warnings.iter().any(|w| w.contains("sampled")));+ assert!(+ prompt+ .rejected_candidates+ .iter()+ .any(|r| r.reason == "input_budget_sampled")+ );+ }++ #[test]+ fn validation_prepends_title_when_body_is_missing_h1() {+ let mut candidate = proposal("gotchas/missing-h1.md", "gotcha", 0.91);+ candidate.body_markdown = "Body without a heading.".into();+ let raw = AutoImproveLlmResponse {+ summary: "ok".into(),+ proposals: vec![candidate],+ rejected_candidates: Vec::new(),+ };++ let (accepted, rejected, warnings) =+ validate_response(raw, &cfg(), &ExistingPageIndex::default());+ assert_eq!(accepted.len(), 1);+ assert!(rejected.is_empty());+ assert!(accepted[0].body_markdown.starts_with("# Test\n\n"));+ assert!(warnings.iter().any(|w| w.contains("prepended title")));+ }++ #[test]+ fn validation_rejects_existing_path_duplicates() {+ let existing = ExistingPageIndex::from_pages(&[BriefingPage {+ path: "gotchas/existing.md".into(),+ title: "Existing Lesson".into(),+ kind: "gotcha".into(),+ updated_at: "2026-06-15T00:00:00Z".into(),+ }]);+ let raw = AutoImproveLlmResponse {+ summary: "ok".into(),+ proposals: vec![+ proposal("gotchas/existing.md", "gotcha", 0.91),+ AutoImproveProposal {+ title: "Existing Lesson".into(),+ ..proposal("gotchas/same-title.md", "gotcha", 0.91)+ },+ ],+ rejected_candidates: Vec::new(),+ };++ let (accepted, rejected, _warnings) = validate_response(raw, &cfg(), &existing);+ assert!(accepted.is_empty());+ assert_eq!(rejected.len(), 2);+ assert_eq!(rejected[0].reason, "duplicate_existing_path");+ assert_eq!(rejected[1].reason, "duplicate_existing_title");+ }++ #[test]+ fn validation_rejects_low_confidence_and_bad_prefix() {+ let raw = AutoImproveLlmResponse {+ summary: "ok".into(),+ proposals: vec![+ proposal("gotchas/good.md", "gotcha", 0.2),+ proposal("sessions/new.md", "fact", 0.9),+ ],+ rejected_candidates: Vec::new(),+ };+ let (accepted, rejected, _warnings) =+ validate_response(raw, &cfg(), &ExistingPageIndex::default());+ assert!(accepted.is_empty());+ assert_eq!(rejected.len(), 2);+ assert_eq!(rejected[0].reason, "confidence_below_threshold");+ assert_eq!(rejected[1].reason, "unsupported_path_prefix");+ }++ #[test]+ fn validation_caps_proposal_count() {+ let raw = AutoImproveLlmResponse {+ summary: "ok".into(),+ proposals: vec![+ proposal("gotchas/one.md", "gotcha", 0.9),+ proposal("decisions/two.md", "decision", 0.9),+ proposal("concepts/three.md", "concept", 0.9),+ ],+ rejected_candidates: Vec::new(),+ };+ let (accepted, rejected, _warnings) =+ validate_response(raw, &cfg(), &ExistingPageIndex::default());+ assert_eq!(accepted.len(), 2);+ assert_eq!(rejected.len(), 1);+ assert_eq!(rejected[0].reason, "max_proposals_exceeded");+ }+}diff --git a/crates/ai-memory-consolidate/src/lib.rs b/crates/ai-memory-consolidate/src/lib.rsindex 391afc17..004fb68f 100644--- a/crates/ai-memory-consolidate/src/lib.rs+++ b/crates/ai-memory-consolidate/src/lib.rs@@ -8,12 +8,21 @@//!//! M7b extends this to multi-page atomic fan-out.+pub mod auto_improve;pub mod bootstrap;pub mod consolidator;pub mod lint;pub mod sweep;pub mod types;+pub use auto_improve::{+ AutoImproveError, AutoImproveEvidence, AutoImproveLlmResponse, AutoImproveProposal,+ AutoImproveRejectedCandidate, AutoImproveReport, AutoImproveReviewConfig,+ DEFAULT_AUTO_IMPROVE_MAX_INPUT_TOKENS, DEFAULT_AUTO_IMPROVE_MAX_PROPOSALS,+ DEFAULT_AUTO_IMPROVE_MIN_CONFIDENCE, DEFAULT_AUTO_IMPROVE_MIN_OBSERVATIONS,+ DEFAULT_AUTO_IMPROVE_MIN_SESSION_DURATION_SECS, DEFAULT_AUTO_IMPROVE_PENDING_PATH,+ DEFAULT_AUTO_IMPROVE_PROPOSAL_ACTOR, run_auto_improve_review,+};pub use bootstrap::{Bootstrap, BootstrapConfig, BootstrapError, BootstrapOutcome, BootstrapSource,DEFAULT_CHUNK_INPUT_TOKENS, ProjectNameStrategy, SourceCounts, SourceKind, collect_sources,diff --git a/crates/ai-memory-consolidate/src/types.rs b/crates/ai-memory-consolidate/src/types.rsindex 5d0242e5..2825741b 100644--- a/crates/ai-memory-consolidate/src/types.rs+++ b/crates/ai-memory-consolidate/src/types.rs@@ -43,6 +43,8 @@ pub enum PageKind {/// "Claude Code's session-end fires twice when /exit is typed/// during a tool call".Gotcha,+ /// A reusable multi-step workflow or operating procedure.+ Procedure,/// Anything that doesn't fit a stronger category. The default —/// keeps existing call sites that don't classify explicitly/// working unchanged.@@ -58,6 +60,7 @@ impl PageKind {Self::Rule => "rule",Self::Decision => "decision",Self::Gotcha => "gotcha",+ Self::Procedure => "procedure",Self::Fact => "fact",}}diff --git a/crates/ai-memory-core/src/routing_snippet.rs b/crates/ai-memory-core/src/routing_snippet.rsindex 129c511b..e47b0df4 100644--- a/crates/ai-memory-core/src/routing_snippet.rs+++ b/crates/ai-memory-core/src/routing_snippet.rs@@ -70,6 +70,7 @@ match the intent to the tool. They do not need to name the tool.| "save context for the next session" / wrapping up / ending this session | `memory_handoff_begin` (session-end only; do **not** use for status/briefing; single-use handoff; terse summary; put detail in `open_questions` + `next_steps` bullets; pass `workspace` + `project` together only for a named sibling workspace/project) || "discard that handoff" / "I created a handoff by mistake" | `memory_handoff_cancel` (requires exact `handoff_id` from `memory_handoff_begin`; marks it expired before the next session sees it) || "consolidate this session" / "compile what we learned" (also runs on PreCompact; at session end only if `AI_MEMORY_CONSOLIDATE_ON_SESSION_END` is set) | `memory_consolidate` |+| "what did we learn from this session?" / "what memory should we add?" / explicit wrap-up learning review | `memory_auto_improve` (dry-run only; omit `session_id` for latest completed session; show proposals and evidence; do **not** apply/write them unless the user explicitly approves) || "remember this permanently" / "save a note" / "add an annotation" / durable project knowledge | `memory_write_page` (write a wiki page; do **not** use handoff for permanent notes; put the title as a `# H1` on the first line of `body` and omit the `title` arg — ai-memory derives it from the H1) || "read the page about X" / "show me the full content of Y" / "open the page on Z" | `memory_read_page` (full body; pass a query to search or `path` for a direct lookup; pass `workspace` + `project` together only for a named sibling workspace/project) || "delete the page X" / "remove that note" | `memory_delete_page` (by exact `path`; idempotent; pass `workspace` + `project` together only for a named sibling workspace/project) |@@ -102,12 +103,41 @@ match outside the snippet window). To read the whole page, usefull body; add `workspace` + `project` together only when the user namesa sibling workspace/project).+### Use Retrieved Memory As Operating Guidance++When `memory_query` or `memory_recent` returns `_rules/`, `gotchas/`,+`procedures/`, or `decisions/` pages that match the current task, treat+them as actionable context, not trivia:++- Read full pages with `memory_read_page` when the snippet looks relevant.+- Apply `_rules/` as constraints.+- Check `gotchas/` as preflight warnings before editing the same subsystem.+- Follow `procedures/` as checklists for releases, PR reviews, deploys,+ migrations, and other repeatable workflows.+- Use `decisions/` as prior architecture unless the user explicitly asks+ to revisit them.++Before non-trivial coding, debugging, deployment, release, auth, scope,+migration, PR-review, or data-preservation work, search memory for the+subsystem and task type first. If the first query is thin, broaden or+query specific error/subsystem terms before designing a fix.++### Learning Review++`memory_auto_improve` is a dry-run learning reviewer. Use it when the+user asks what durable lessons this session suggests, or at explicit+wrap-up when reviewing proposed memory would be useful. It returns+proposed wiki edits with evidence and never writes pages or pending+proposals. Do not apply proposals with `memory_write_page` unless the+user explicitly approves.+### When you write a project rule, write it hereIf you're about to write a durable project rule ("always X", "never-Y", "all PRs must …"), this rules file (CLAUDE.md for Claude Code;-AGENTS.md for Codex / OpenCode / Cursor / Gemini CLI; whichever-convention your agent uses) is where it belongs. ai-memory's lint+Y", "all PRs must …"), write it in the project's canonical agent+instruction file. Many projects use CLAUDE.md for Claude Code and+AGENTS.md for Codex / OpenCode / Cursor / Gemini CLI, but if the+project says one file is canonical, use that file. ai-memory's lintpass surfaces the same hint automatically when a `kind: rule` pagelands in `_rules/`.@@ -122,7 +152,8 @@ the latest binary's recommended copy:(Claude Code → `CLAUDE.md`; Codex / OpenCode / Cursor / Gemini →`AGENTS.md`), and uses its Write / Edit tool to land the block.- **From the CLI**: `ai-memory install-instructions` (defaults to- `CLAUDE.md`; pass `--target AGENTS.md` for non-Claude agents).+ `CLAUDE.md`; pass `--target AGENTS.md` for non-Claude agents or+ projects that use `AGENTS.md` as the canonical instruction file).Both are idempotent: re-runs replace the block bracketed by`<!-- ai-memory:start -->` / `<!-- ai-memory:end -->` markersdiff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex 2fee59e5..92415a7b 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -4,6 +4,7 @@//! - `POST /admin/backup` — snapshot db + wiki into a gzip tarball (binary response).//! - `POST /admin/bootstrap` — ingest a pre-collected source bundle//! into seed wiki pages via the configured LLM provider.+//! - `POST /admin/auto-improve` — dry-run durable wiki edit proposals for one session.//! - `GET /admin/status` — lifetime counts + server data-dir info.//! - `GET /admin/search?q=` — FTS5 hits against the wiki index.//! - `POST /admin/reorg` — retro-fit sessions to per-cwd projects.@@ -31,8 +32,8 @@ use std::io::Seek;use std::path::PathBuf;use ai_memory_consolidate::{- Bootstrap, BootstrapConfig, BootstrapOutcome, BootstrapSource, SourceCounts,- prune_sources_to_budget, run_lint, run_sweep,+ AutoImproveReviewConfig, Bootstrap, BootstrapConfig, BootstrapOutcome, BootstrapSource,+ SourceCounts, prune_sources_to_budget, run_auto_improve_review, run_lint, run_sweep,};use ai_memory_core::{ActiveProject, Capability, DEFAULT_PROJECT_NAME, DEFAULT_WORKSPACE_NAME, PagePath, ProjectId,@@ -149,9 +150,79 @@ fn default_chunk_input_tokens() -> usize {ai_memory_consolidate::DEFAULT_CHUNK_INPUT_TOKENS}+/// JSON request body for `POST /admin/auto-improve`.+#[derive(Deserialize)]+struct AutoImproveRequest {+ /// Workspace name (must already exist).+ #[serde(default = "default_workspace")]+ workspace: String,+ /// Project name (must already exist).+ #[serde(default = "default_project")]+ project: String,+ /// Completed session to review.+ session_id: SessionId,+ /// Required for the first implementation slice. Live staging/apply is not+ /// available until pending proposal storage ships.+ #[serde(default)]+ dry_run: bool,+ /// Minimum observations before the LLM review runs.+ #[serde(default = "default_auto_improve_min_observations")]+ min_observations: usize,+ /// Minimum session span before the LLM review runs.+ #[serde(default = "default_auto_improve_min_session_duration_secs")]+ min_session_duration_secs: u64,+ /// Minimum proposal confidence accepted by validation.+ #[serde(default = "default_auto_improve_min_confidence")]+ min_confidence: f32,+ /// Approximate chars/4 prompt budget.+ #[serde(default = "default_auto_improve_max_input_tokens")]+ max_input_tokens: usize,+ /// Maximum validated proposals returned.+ #[serde(default = "default_auto_improve_max_proposals")]+ max_proposals_per_run: usize,+ /// Whether future raw fallback details may be considered.+ #[serde(default)]+ include_raw_fallback: bool,+ /// Synthetic actor reserved for future staged proposal provenance.+ #[serde(default = "default_auto_improve_proposal_actor")]+ proposal_actor: String,+ /// Pending proposal folder reserved for future staging.+ #[serde(default = "default_auto_improve_pending_path")]+ pending_path: String,+}++fn default_auto_improve_min_observations() -> usize {+ ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MIN_OBSERVATIONS+}++fn default_auto_improve_min_session_duration_secs() -> u64 {+ ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MIN_SESSION_DURATION_SECS+}++fn default_auto_improve_min_confidence() -> f32 {+ ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MIN_CONFIDENCE+}++fn default_auto_improve_max_input_tokens() -> usize {+ ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_INPUT_TOKENS+}++fn default_auto_improve_max_proposals() -> usize {+ ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_PROPOSALS+}++fn default_auto_improve_proposal_actor() -> String {+ ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_PROPOSAL_ACTOR.into()+}++fn default_auto_improve_pending_path() -> String {+ ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_PENDING_PATH.into()+}+/// Build the admin axum [`Router`]. Mounts:/// - `POST /admin/backup`/// - `POST /admin/bootstrap`+/// - `POST /admin/auto-improve`/// - `GET /admin/status`/// - `GET /admin/search`/// - `GET /admin/read-page`@@ -173,6 +244,7 @@ pub fn admin_router(state: AdminState) -> Router {let operational = Router::new().route("/admin/backup", post(handle_backup)).route("/admin/bootstrap", post(handle_bootstrap))+ .route("/admin/auto-improve", post(handle_auto_improve)).route("/admin/status", get(handle_status)).route("/admin/search", get(handle_search)).route("/admin/read-page", get(handle_read_page))@@ -835,6 +907,69 @@ fn dry_run_outcome())}+// ---------------------------------------------------------------------+// auto-improve dry-run reviewer+// ---------------------------------------------------------------------++async fn handle_auto_improve(+ State(state): State<Arc<AdminState>>,+ Json(req): Json<AutoImproveRequest>,+) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {+ if !req.dry_run {+ return Err((+ StatusCode::UNPROCESSABLE_ENTITY,+ Json(serde_json::json!({+ "error": "auto-improve currently supports --dry-run only; pending proposal storage is not implemented yet"+ })),+ ));+ }++ let (ws, proj) = lookup_ws_proj_no_create(&state, &req.workspace, &req.project).await?;+ let Some(llm) = state.llm.as_ref().cloned() else {+ return Err((+ StatusCode::SERVICE_UNAVAILABLE,+ Json(serde_json::json!({+ "error": "LLM provider not configured on server"+ })),+ ));+ };++ let cfg = AutoImproveReviewConfig {+ min_observations: req.min_observations,+ min_session_duration_secs: req.min_session_duration_secs,+ min_confidence: req.min_confidence,+ max_input_tokens: req.max_input_tokens,+ max_proposals_per_run: req.max_proposals_per_run,+ include_raw_fallback: req.include_raw_fallback,+ proposal_actor: req.proposal_actor,+ pending_path: req.pending_path,+ };++ run_auto_improve_review(&state.reader, &*llm, ws, proj, req.session_id, cfg)+ .await+ .map(|report| {+ (+ StatusCode::OK,+ Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),+ )+ })+ .map_err(auto_improve_error_response)+}++fn auto_improve_error_response(+ e: ai_memory_consolidate::AutoImproveError,+) -> (StatusCode, Json<serde_json::Value>) {+ use ai_memory_consolidate::AutoImproveError;+ let status = match &e {+ AutoImproveError::SessionNotFound(_) => StatusCode::NOT_FOUND,+ AutoImproveError::SessionOutOfScope { .. } => StatusCode::UNPROCESSABLE_ENTITY,+ AutoImproveError::Llm(_) => StatusCode::BAD_GATEWAY,+ AutoImproveError::Memory(_) => StatusCode::BAD_REQUEST,+ AutoImproveError::Store(_) => StatusCode::INTERNAL_SERVER_ERROR,+ };+ (status, Json(serde_json::json!({ "error": e.to_string() })))+}+// ---------------------------------------------------------------------// reorg// ---------------------------------------------------------------------@@ -3454,6 +3589,68 @@ mod tests {assert_eq!(json["project"], "audit");}+ #[tokio::test]+ async fn auto_improve_rejects_non_dry_run_for_now() {+ let (_tmp, router) = read_page_test_router();++ let resp = router+ .oneshot(+ Request::builder()+ .method("POST")+ .uri("/admin/auto-improve")+ .header("content-type", "application/json")+ .body(Body::from(+ serde_json::to_vec(&serde_json::json!({+ "workspace": "default",+ "project": "audit",+ "session_id": "00000000-0000-0000-0000-000000000000",+ "dry_run": false+ }))+ .unwrap(),+ ))+ .unwrap(),+ )+ .await+ .unwrap();++ assert_eq!(resp.status(), StatusCode::UNPROCESSABLE_ENTITY);+ let body = to_bytes(resp.into_body(), usize::MAX).await.unwrap();+ let json: serde_json::Value = serde_json::from_slice(&body).unwrap();+ assert!(+ json["error"]+ .as_str()+ .unwrap_or_default()+ .contains("dry-run")+ );+ }++ #[tokio::test]+ async fn auto_improve_missing_scope_does_not_fall_back_before_llm_check() {+ let (_tmp, router) = read_page_test_router();++ let resp = router+ .oneshot(+ Request::builder()+ .method("POST")+ .uri("/admin/auto-improve")+ .header("content-type", "application/json")+ .body(Body::from(+ serde_json::to_vec(&serde_json::json!({+ "workspace": "missing",+ "project": "missing",+ "session_id": "00000000-0000-0000-0000-000000000000",+ "dry_run": true+ }))+ .unwrap(),+ ))+ .unwrap(),+ )+ .await+ .unwrap();++ assert_eq!(resp.status(), StatusCode::NOT_FOUND);+ }+#[tokio::test]async fn read_page_missing_path_returns_404() {let (_tmp, router) = read_page_test_router();@@ -4026,6 +4223,16 @@ mod tests {"dry_run": true}),),+ (+ "POST",+ "/admin/auto-improve",+ serde_json::json!({+ "workspace": "default",+ "project": "scratch",+ "session_id": "00000000-0000-0000-0000-000000000000",+ "dry_run": true+ }),+ ),("GET", "/admin/status", serde_json::Value::Null),("GET", "/admin/search?q=test", serde_json::Value::Null),(diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex 75467581..5dd4bd51 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -4,7 +4,9 @@ use std::collections::HashMap;use std::str::FromStr;use std::sync::Arc;-use ai_memory_consolidate::{Consolidator, run_lint, run_sweep};+use ai_memory_consolidate::{+ AutoImproveReviewConfig, Consolidator, run_auto_improve_review, run_lint, run_sweep,+};use ai_memory_core::{ActiveProject, AgentKind, HandoffId, HandoffState, NewHandoff, PageId, PagePath, ProjectId,SessionId, Tier, WorkspaceId,@@ -88,6 +90,12 @@ the conversation calls for them:\n\- `memory_consolidate` — when the user asks to compile session \observations into wiki pages. Also runs on PreCompact, and at \session end only when AI_MEMORY_CONSOLIDATE_ON_SESSION_END is set.\n\+- `memory_auto_improve` — when the user asks what durable lessons \+ should be proposed from a completed session, or at explicit wrap-up \+ when learning review is useful. Dry-run only for now: it reads the \+ latest completed session by default, returns proposed wiki edits with \+ evidence, and never writes pages or pending proposals. Do NOT apply \+ proposals with memory_write_page unless the user explicitly approves.\n\- `memory_write_page` — when the user explicitly asks to remember, \save, or annotate durable project knowledge. This writes a wiki page; \do NOT use `memory_handoff_begin` for permanent annotations. \@@ -134,6 +142,17 @@ window); to read the whole page use `memory_read_page` (by `path`, \or a `query` for the top hit's body; add `workspace` + `project` \together only for a named sibling workspace/project).\n\\n\+**Use retrieved memory as operating guidance, not trivia.** When \+`memory_query` or `memory_recent` returns `_rules/`, `gotchas/`, \+`procedures/`, or `decisions/` pages relevant to the task, read the \+full page with `memory_read_page` before acting. Treat `_rules/` as \+constraints, `gotchas/` as preflight warnings, `procedures/` as \+checklists, and `decisions/` as settled architecture unless the user \+explicitly asks to revisit them. Before non-trivial coding, debugging, \+deployment, release, auth, scope, migration, PR-review, or \+data-preservation work, search memory for the subsystem and task type \+first.\n\+\n\The routing snippet this very text comes from can also be installed \into the project's CLAUDE.md / AGENTS.md so the guidance survives \across sessions. From the agent: ask 'install ai-memory routing'. \@@ -317,6 +336,45 @@ struct ConsolidateArgs {multi_page: Option<bool>,}+#[derive(Debug, Serialize, Deserialize, schemars::JsonSchema)]+struct AutoImproveArgs {+ /// Completed session UUID to review. Omit to review the latest completed+ /// session in the resolved current project.+ #[serde(default)]+ session_id: Option<String>,+ /// Must be true or omitted. The MCP surface is dry-run only until pending+ /// proposal storage and approval tools exist.+ #[serde(default)]+ dry_run: Option<bool>,+ /// Project to review. Omit to target the project you're currently working+ /// in (resolved from recent hook activity). **Omit unless the user+ /// explicitly names a different project.**+ #[serde(default)]+ project: Option<String>,+ /// Workspace to review together with `project`. Omit for the+ /// current/default workspace resolution chain.+ #[serde(default)]+ workspace: Option<String>,+ /// Override the minimum observation count for this run.+ #[serde(default)]+ min_observations: Option<usize>,+ /// Override the minimum session span for this run.+ #[serde(default)]+ min_session_duration_secs: Option<u64>,+ /// Override the proposal confidence floor for this run.+ #[serde(default)]+ min_confidence: Option<f32>,+ /// Override the approximate chars/4 input token budget for this run.+ #[serde(default)]+ max_input_tokens: Option<usize>,+ /// Override the maximum validated proposal count for this run.+ #[serde(default)]+ max_proposals: Option<usize>,+ /// Include raw fallback context when the reviewer supports it.+ #[serde(default)]+ include_raw_fallback: Option<bool>,+}+#[derive(Debug, Serialize, Deserialize, schemars::JsonSchema)]struct HandoffBeginArgs {/// Short prose summary of where the session left off.@@ -1080,6 +1138,77 @@ impl AiMemoryServer {}}+ /// Dry-run durable wiki edit proposals for a completed session.+ #[tool(+ description = "Run a DRY-RUN auto-improvement review for one completed session. Use when the user asks what durable lessons should be proposed, what memory pages this session suggests, or at explicit wrap-up when a learning review is useful. Omit `session_id` to review the latest completed session in the current project. This is read-only: it never writes wiki files, pending proposals, or handoffs. Do NOT apply proposals with memory_write_page unless the user explicitly approves."+ )]+ async fn memory_auto_improve(+ &self,+ Parameters(args): Parameters<AutoImproveArgs>,+ Extension(parts): Extension<axum::http::request::Parts>,+ ) -> Result<CallToolResult, McpError> {+ if args.dry_run == Some(false) {+ return Err(McpError::invalid_params(+ "memory_auto_improve currently supports dry-run only",+ None,+ ));+ }+ let aps_actor = Self::actor_key_from_parts(Some(&parts));+ let (ws, proj) = self+ .effective_ids_for_read_args_with_actor(+ args.workspace.as_deref(),+ args.project.as_deref(),+ &aps_actor,+ )+ .await?;+ let Some(llm) = self.llm.as_ref() else {+ return Err(McpError::internal_error(+ "memory_auto_improve not configured (set AI_MEMORY_LLM_PROVIDER on the server)",+ None,+ ));+ };+ let session_id = match args.session_id.as_deref() {+ Some(raw) => SessionId::from_str(raw)+ .map_err(|e| McpError::invalid_params(e.to_string(), None))?,+ None => self+ .reader+ .latest_completed_session_for_project(ws, proj)+ .await+ .map_err(|e| McpError::internal_error(e.to_string(), None))?+ .ok_or_else(|| {+ McpError::internal_error(+ "no completed session found for the resolved project",+ None,+ )+ })?,+ };+ let cfg = AutoImproveReviewConfig {+ min_observations: args+ .min_observations+ .unwrap_or(ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MIN_OBSERVATIONS),+ min_session_duration_secs: args+ .min_session_duration_secs+ .unwrap_or(ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MIN_SESSION_DURATION_SECS),+ min_confidence: args+ .min_confidence+ .unwrap_or(ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MIN_CONFIDENCE),+ max_input_tokens: args+ .max_input_tokens+ .unwrap_or(ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_INPUT_TOKENS),+ max_proposals_per_run: args+ .max_proposals+ .unwrap_or(ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MAX_PROPOSALS),+ include_raw_fallback: args.include_raw_fallback.unwrap_or(false),+ proposal_actor: ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_PROPOSAL_ACTOR.into(),+ pending_path: ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_PENDING_PATH.into(),+ };++ let report = run_auto_improve_review(&self.reader, &**llm, ws, proj, session_id, cfg)+ .await+ .map_err(|e| McpError::internal_error(e.to_string(), None))?;+ ok_json(&report)+ }+/// Write or update a durable wiki page.#[tool(description = "Write or update a durable wiki page for the \current project. Use this when the user explicitly asks to \@@ -1993,6 +2122,7 @@ mod tests {"memory_handoff_begin","memory_handoff_cancel","memory_consolidate",+ "memory_auto_improve","memory_write_page","memory_read_page","memory_delete_page",@@ -2099,6 +2229,62 @@ mod tests {}}+ #[test]+ fn prompts_treat_retrieved_memory_as_actionable_guidance() {+ for prompt in [MEMORY_INSTRUCTIONS, ai_memory_core::SNIPPET_BODY] {+ let lower = prompt.to_ascii_lowercase();+ assert!(+ prompt.contains("_rules/")+ && prompt.contains("gotchas/")+ && prompt.contains("procedures/")+ && prompt.contains("decisions/"),+ "prompt must name actionable page families"+ );+ assert!(+ lower.contains("constraints")+ && lower.contains("preflight")+ && lower.contains("checklists"),+ "prompt must teach how to use rules/gotchas/procedures"+ );+ assert!(+ lower.contains("before non-trivial")+ && lower.contains("auth")+ && lower.contains("migration"),+ "prompt must make proactive retrieval the default for risky work"+ );+ }+ }++ #[tokio::test]+ async fn prompts_expose_auto_improve_as_dry_run_only() {+ for prompt in [MEMORY_INSTRUCTIONS, ai_memory_core::SNIPPET_BODY] {+ let lower = prompt.to_ascii_lowercase();+ assert!(prompt.contains("memory_auto_improve"));+ assert!(lower.contains("dry-run") || lower.contains("dry run"));+ assert!(+ lower.contains("never writes") || lower.contains("never write"),+ "prompt must state auto-improve review is non-mutating"+ );+ assert!(+ lower.contains("explicitly approves") || lower.contains("explicitly approve"),+ "prompt must require explicit approval before applying proposals"+ );+ }++ let (_tmp, _store, server, _ws, _pj) = setup_server().await;+ let tools = server.tool_router.list_all();+ let auto_improve = tools+ .iter()+ .find(|t| t.name == "memory_auto_improve")+ .expect("memory_auto_improve must be registered");+ let desc = auto_improve+ .description+ .as_deref()+ .expect("memory_auto_improve must carry a description");+ assert!(desc.contains("DRY-RUN") || desc.contains("dry-run"));+ assert!(desc.contains("never writes"));+ }+#[test]fn prompts_teach_cross_workspace_handoff_scope() {for prompt in [MEMORY_INSTRUCTIONS, ai_memory_core::SNIPPET_BODY] {@@ -3975,6 +4161,62 @@ mod tests {);}+ #[tokio::test]+ async fn memory_auto_improve_rejects_non_dry_run() {+ let (_tmp, _store, server, _ws, _pj) = setup_server().await;+ let err = server+ .memory_auto_improve(+ Parameters(AutoImproveArgs {+ session_id: None,+ dry_run: Some(false),+ project: None,+ workspace: None,+ min_observations: None,+ min_session_duration_secs: None,+ min_confidence: None,+ max_input_tokens: None,+ max_proposals: None,+ include_raw_fallback: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ )+ .await+ .expect_err("auto-improve MCP tool must be dry-run only");+ let msg = format!("{err:?}");+ assert!(+ msg.contains("dry-run"),+ "error should mention dry-run: {msg}"+ );+ }++ #[tokio::test]+ async fn memory_auto_improve_without_provider_errors_cleanly() {+ let (_tmp, _store, server, _ws, _pj) = setup_server().await;+ let err = server+ .memory_auto_improve(+ Parameters(AutoImproveArgs {+ session_id: Some("00000000-0000-0000-0000-000000000000".into()),+ dry_run: Some(true),+ project: None,+ workspace: None,+ min_observations: None,+ min_session_duration_secs: None,+ min_confidence: None,+ max_input_tokens: None,+ max_proposals: None,+ include_raw_fallback: None,+ }),+ rmcp::handler::server::tool::Extension(test_parts_default()),+ )+ .await+ .expect_err("must reject when no LLM provider is configured");+ let msg = format!("{err:?}");+ assert!(+ msg.contains("not configured"),+ "error should mention configuration: {msg}",+ );+ }+/// `memory_lint` reads the wiki to build its candidate set. With/// no wiki wired, it must error cleanly.#[tokio::test]diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rsindex 21655025..4e9a3eeb 100644--- a/crates/ai-memory-store/src/lib.rs+++ b/crates/ai-memory-store/src/lib.rs@@ -723,6 +723,47 @@ mod tests {assert!(hits[0].snippet.contains("<mark>zebra</mark>"));}+ #[tokio::test]+ async fn latest_completed_session_for_project_ignores_open_sessions() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "ai-memory", None)+ .await+ .unwrap();+ let first = SessionId::new();+ let open = SessionId::new();+ for id in [first, open] {+ store+ .writer+ .begin_session(NewSession {+ id,+ workspace_id: ws,+ project_id: proj,+ agent_kind: AgentKind::OpenCode,+ cwd: None,+ })+ .await+ .unwrap();+ }+ store.writer.end_session(first, None).await.unwrap();++ assert_eq!(+ store+ .reader+ .latest_completed_session_for_project(ws, proj)+ .await+ .unwrap(),+ Some(first)+ );+ }+#[tokio::test]async fn list_projects_with_stats_returns_aggregates() {let tmp = TempDir::new().unwrap();diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rsindex f43aa5d7..284f7960 100644--- a/crates/ai-memory-store/src/reader.rs+++ b/crates/ai-memory-store/src/reader.rs@@ -918,6 +918,35 @@ impl ReaderPool {.await}+ /// Return the latest completed session for a project.+ ///+ /// Used by read-only review tools that need a natural default when the user+ /// asks what the project just learned without naming a session id.+ ///+ /// # Errors+ /// Propagates any SQL or pool error.+ pub async fn latest_completed_session_for_project(+ &self,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ ) -> StoreResult<Option<SessionId>> {+ self.with_conn(move |conn| {+ let row_opt: Option<Vec<u8>> = conn+ .query_row(+ "SELECT id FROM sessions \+ WHERE workspace_id = ?1 AND project_id = ?2 AND ended_at IS NOT NULL \+ ORDER BY ended_at DESC, started_at DESC LIMIT 1",+ params![workspace_id.as_bytes(), project_id.as_bytes()],+ |row| row.get(0),+ )+ .optional()?;+ row_opt+ .map(|bytes| SessionId::from_slice(&bytes).map_err(StoreError::from))+ .transpose()+ })+ .await+ }+/// Look up the `(workspace_id, project_id)` a session belongs to./// Returns `None` when no such session row exists.///diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 3ff0a0ce..d93c83ee 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -225,14 +225,14 @@ crates/├── ai-memory-hooks/ payload schemas, sanitiser, /hook ingress.├── ai-memory-llm/ provider auth boundary + LlmProvider / Embedder traits.├── ai-memory-consolidate/ Karpathy ingest / lint / sweep pipeline.-└── ai-memory-cli/ `ai-memory` binary entry point + 17 subcommands.+└── ai-memory-cli/ `ai-memory` binary entry point + thin HTTP subcommands.```Each crate has a single responsibility and exposes a typed API. Nocircular deps. Inter-crate boundaries enforce the cross-cuttinginvariants below.-## MCP tool surface (15 tools)+## MCP tool surface (16 tools)| Tool | Hint | Purpose ||---|---|---|@@ -246,6 +246,7 @@ invariants below.| `memory_handoff_accept` | destructive | Fetch + ack the latest open handoff (auto-cwd-matched by default). Optional `workspace` + `project` targets a named sibling workspace/project. || `memory_handoff_cancel` | destructive | Mark an exact open handoff id expired when it was created by mistake. || `memory_consolidate` | destructive | LLM-driven page rewrite. `multi_page=true` for atomic fan-out. |+| `memory_auto_improve` | read-only | Dry-run durable wiki edit proposals for a completed session. Defaults to the latest completed session in the resolved current project and never writes pages or pending proposals. || `memory_write_page` | destructive | Write durable wiki knowledge when the user explicitly asks to remember/annotate something permanent. || `memory_delete_page` | destructive | Delete a single page by exact `path`. Fires the admission chain (op=delete); idempotent. || `memory_forget_sweep` | destructive | M8 retention pass. `dry_run=true` for preview. |@@ -253,8 +254,8 @@ invariants below.| `memory_install_self_routing` | read-only | Return the canonical routing snippet for CLAUDE.md / AGENTS.md. |`memory_briefing`, `memory_explore`, `memory_write_page`,-`memory_install_self_routing`, `memory_read_page`, `memory_delete_page`, and-`memory_handoff_cancel`+`memory_install_self_routing`, `memory_read_page`, `memory_delete_page`,+`memory_handoff_cancel`, and `memory_auto_improve`post-date the original "narrow on purpose" cut (§10 of`design-decisions.md`): briefing/explore separate the structured vs.prose halves of "what's going on", `memory_write_page` covers explicit@@ -263,7 +264,8 @@ durable annotations without abusing single-use handoffs,must re-write its own routing rules into a project's `CLAUDE.md` /`AGENTS.md`, `memory_read_page` complements `memory_query` for the"I need the full page, not a snippet" case (e.g. opening a decision page-end-to-end), and `memory_delete_page` is the exact-path destructive pair+end-to-end), `memory_auto_improve` exposes a safe default-on learning review+without mutation, and `memory_delete_page` is the exact-path destructive pairneeded by admission-aware mirrors. `memory_handoff_cancel` is the safety valvefor mistaken handoff creation. The narrow-surface discipline still holds —every new tool has to earn its slot — but the v1 count is 15, not 10.@@ -276,14 +278,16 @@ cwd parameters use their canonical names.```init status search-write-page serve reset-backup restore install-hooks-install-mcp commit llm-test-forget-sweep lint embed-generate-auth-token setup-agent bootstrap-install-instructions reorg purge-project-rename-project move-project uninstall-auth+read-page write-page delete-page+serve reset backup+restore reindex install-hooks+hook install-mcp commit+checkpoints restore-page llm-test+forget-sweep lint auto-improve+embed generate-auth-token setup-agent+bootstrap install-instructions reorg+purge-project rename-project move-project+uninstall auth user```Run `ai-memory --help` for the full tree.diff --git a/docs/auto-improvement-loop.md b/docs/auto-improvement-loop.mdnew file mode 100644index 00000000..f54db66b--- /dev/null+++ b/docs/auto-improvement-loop.md@@ -0,0 +1,458 @@+# Optional Auto-Improvement Loop Research++> Status: research plus phased implementation notes. The dry-run reviewer is+> implemented for CLI/admin/MCP use and is safe to expose by default because it+> does not mutate wiki files or pending proposals. Pending proposal storage,+> approval, session-end triggers, and auto-apply remain proposed future work.++## Executive Summary++An ai-memory equivalent of Hermes Agent's self-improvement loop is worth+building as a default-available dry-run review path, with staged review required+before any write behavior. The current wiki already+captures useful durable knowledge: decisions, gotchas, concepts, rules, notes,+and session summaries. The missing piece is not more capture. It is a careful+post-session reviewer that can identify durable lessons and propose small wiki+patches without mutating the active agent context or silently promoting weak+session residue into rules.++The safe product shape is:++1. Keep automatic observation capture and session consolidation as they are.+2. Add an optional background review pass that creates pending wiki edits.+3. Require approval by default before applying those edits.+4. Keep a separate slow maintenance pass for deduplication, stale-page review,+ and lifecycle cleanup.++Do not copy Hermes' agent-local skill system directly. ai-memory's durable unit+is the project wiki page, not a `SKILL.md` package. The analogous targets are+`gotchas/`, `decisions/`, `concepts/`, `procedures/`, `_rules/`, small+`_slots/` state pages, and pending review pages under `_pending/`.++## Hermes Findings++Hermes has two distinct learning loops.++### Post-Turn Review++The immediate loop runs after a successful turn when cadence counters trip.+Memory review is based on user turns. Skill review is based on tool-call+iterations. The observed defaults are 10 user turns for memory review and 10+tool iterations for skill review.++Important implementation properties:++| Property | Hermes behavior | Lesson for ai-memory |+|---|---|---|+| Active context | The review runs after the response is delivered. | Never compete with the user's active task. |+| Prompt mutation | Mid-session writes update disk but do not mutate the cached active prompt. | Background learning must not rewrite the current agent context. |+| Runtime inheritance | The fork inherits provider, model, auth, cached system prompt, session id, and toolset config. | Avoid model/cache drift when spawning auxiliary review work. |+| Tool restriction | The fork keeps the parent tool schema for prefix-cache parity, then enforces a runtime whitelist for memory and skill tools. | Safety should be enforced mechanically at dispatch/write time, not only by prompt text. |+| External memory plugins | The fork is created with `skip_memory=True` so it does not prefetch/sync external providers. | Do not let the review harness pollute independent memory systems. |+| Dangerous approvals | Background review installs an auto-deny approval callback. | A daemon review must never block on an interactive prompt. |+| Compression | Review compression is disabled. | The review should not race the parent session's lifecycle. |+| Visibility | Successful review actions are summarized to the user as self-improvement review output. | Autonomous memory changes need explicit provenance. |++The post-turn prompts are intentionally aggressive about capturing reusable+procedures, user corrections, and non-trivial techniques. They also include+negative filters: do not encode transient setup failures, negative claims that a+tool is broken, one-off task narratives, or failures that resolved before the+conversation ended.++### Write Approval++Hermes has an optional write-approval gate for persistent memory and skills.+The default is off, preserving existing behavior. When enabled:++| Case | Behavior |+|---|---|+| Foreground memory, interactive CLI | Prompt inline when possible. |+| Foreground memory, no prompt channel | Stage to pending storage. |+| Background memory | Stage to pending storage. |+| Skill writes | Always stage, because skill files can be large. |+| User denies inline memory write | Block, do not stage. |+| Prompt machinery fails | Stage rather than silently dropping the write. |++Validation runs before staging, so invalid writes are rejected immediately+instead of being queued for approval and failing later.++This maps strongly to ai-memory. Wiki edits are closer to Hermes skills than to+small memory entries: they can be large, durable, and project-shaping. Staging+should be the default for autonomous ai-memory learning writes.++### Curator++Hermes' slower curator is a maintenance loop for agent-created skills. It is+triggered by inactivity rather than a cron daemon. Defaults observed in code and+docs:++| Setting | Default |+|---|---:|+| `interval_hours` | 168 hours, 7 days |+| `min_idle_hours` | 2 hours |+| `stale_after_days` | 30 days |+| `archive_after_days` | 90 days |++First-run behavior is deliberately conservative. A fresh install seeds+`last_run_at` and defers the first real pass by a full interval. Users can run a+manual dry-run first.++Important curator properties:++| Property | Hermes behavior | Lesson for ai-memory |+|---|---|---|+| Managed scope | Primarily agent-created skills, tracked in `.usage.json`. | Separate user-authored pages from autonomous pages. |+| Destructive limit | Archive is the maximum automatic destructive action. No auto-delete. | Prefer supersession or soft deletion. |+| Pinned objects | Pinned skills bypass automatic transitions. | Pinned pages and invariant slots must be protected. |+| Reports | Writes machine-readable `run.json` and human `REPORT.md`. | Every maintenance run should leave an audit artifact. |+| Backups | Takes snapshots before mutating runs and supports rollback. | Wiki git commits help, but approval reports should still be explicit. |+| Dry run | Produces report-only preview. | Dry-run should be first-class. |+| Consolidation | Merges narrow skills into umbrellas with structured summary. | ai-memory should consolidate duplicate/narrow pages separately from fresh lesson capture. |++## Live ai-memory Wiki Findings++The deployed homelab wiki was sampled on 2026-06-15. At the time of sampling it+contained 1 workspace, 38 projects, and 204 latest pages.++Page distribution by path prefix:++| Prefix | Count | Assessment |+|---|---:|---|+| `sessions/` | 57 | Useful episodic history, but also the main noise source. |+| `gotchas/` | 40 | High signal; concrete failure modes and fixes. |+| `decisions/` | 37 | High signal; durable rationale. |+| `concepts/` | 36 | High signal; architecture and domain knowledge. |+| `notes/` | 17 | Mixed; includes useful facts and smoke markers. |+| `_rules/` | 8 | High signal when concise and current. |+| `bootstrap.md` | 7 | Useful seed summary. |+| `_slots/` | 2 | Useful for current state, but stale risk is real. |++Representative high-signal pages:++| Page | Why it is useful |+|---|---|+| `ai-memory/gotchas/cli-is-always-http-client.md` | Captures a durable architectural rule, why it exists, exceptions, and prior-art failure modes. |+| `ai-memory/concepts/karpathy-wiki-pattern.md` | Explains the conceptual model behind the product. |+| `.config/notes/marvin-server-nfs-drop-rootcause.md` | Concrete root cause and fix with enough detail to prevent rediscovery. |+| `nes-to-sms/gotchas/vram-budget.md` | Domain-specific constraint that will matter across future work. |+| `akitaonrails-hugo/decisions/blog-content-sourcing.md` | Short decision with rationale and implementation guidance. |+| `llm-coding-benchmark/gotchas/hallucinated-apis.md` | Detailed, verified gotcha with examples and corrections. |++Representative low-signal pages:++| Page | Why it should not be promoted |+|---|---|+| `.config/sessions/0b9f6071-...md` | Three-second no-activity session. |+| `.config/sessions/1f8ffad8-...md` | Single `echo claude-bash-ok` test with no captured output. |+| `.config/sessions/cf81e9c3-...md` | Repeated bash smoke attempts; useful as diagnostics history only. |+| `.config/sessions/914f9f80-...md` | User prompt was only `config`; no substantive work. |+| `sabadell/sessions/8feda9e6-...md` | Heuristic session-end page with one observation. |+| `ai-memory/notes/livetest-v011-release.md` | Valid release smoke marker, but not a general lesson. |++The current system is already creating the right durable page families. The+auto-improvement opportunity is therefore selective promotion and cleanup, not a+new memory substrate.++## Recommendation++Build auto-improvement as a default-available review path, but keep the default+mode read-only. Do not let it write directly to the wiki without review at+first.++The initial feature should be a stage-only learning reviewer:++1. Dry-run review is enabled by default when an LLM provider is configured;+ CLI/admin/MCP dry-runs still require that provider and can be invoked without+ enabling any session-end trigger.+2. Reads a completed session, recent pages, and relevant existing wiki pages.+3. Produces a structured proposal containing small page creates or updates.+4. Stores the proposal in a pending-review queue with evidence and diffs.+5. Applies approved proposals through `Wiki::apply_batch`, admission webhooks,+ auth capabilities, audit logging, and the single writer actor.++Auto-apply can be considered later for narrow, high-confidence updates, but the+first version should earn trust through dry-runs and pending approvals.++## Proposed Page Targets++| Target | Use for | Notes |+|---|---|---|+| `gotchas/<topic>.md` | Reproducible pitfalls, root causes, tool quirks, failed approaches with a durable fix. | Require evidence and a correction or mitigation. |+| `decisions/<topic>.md` | Choices that changed architecture, workflow, dependencies, deployment, or policy. | Include decision, rationale, consequences. |+| `concepts/<topic>.md` | Stable domain or project architecture knowledge. | Prefer synthesis over task chronology. |+| `procedures/<topic>.md` | Reusable workflows, operating procedures, and repeated multi-step patterns. | Use when the value is the sequence, not only the root cause or rationale. |+| `_rules/<topic>.md` | Explicit always/never instructions for future agents. | Should also trigger the existing lint hint to update `AGENTS.md` or `CLAUDE.md`. |+| `_slots/current-focus.md` | Mutable short-term project state. | Treat as state, not durable truth; overwrite rather than append. |+| `notes/<topic>.md` | Useful facts that do not fit the above. | Avoid using notes as a dumping ground. |+| `_pending/auto-improve/<id>.md` | Human-reviewable staged proposals and diffs. | This is proposal storage, not approved durable knowledge. |++Do not create new session pages from the auto-improvement loop. Session pages+already come from session-end consolidation.++## Negative Filters++The review prompt should explicitly reject these as durable learning:++| Filter | Why |+|---|---|+| No-activity sessions | They add retrieval noise. |+| Single-command smoke tests | Usually operational evidence, not reusable knowledge. |+| Release markers | Keep as notes if needed, but do not promote to rules/gotchas. |+| Transient missing binaries, credentials, or setup state | These become stale false constraints. |+| Broad negative tool claims | `tool X is broken` hardens into future refusals after the tool is fixed. |+| One-off task narratives | Session pages already preserve chronology. |+| Resolved transient failures | Capture the retry or fix pattern, not the temporary failure. |+| User-visible status only | Use handoff or `_slots/current-focus.md`, not durable semantic pages. |++## Safety Invariants++Any implementation should preserve these invariants:++1. Off by default.+2. Stage by default.+3. Never mutate the active session prompt or already-prepended handoff context.+4. Never run inside hook latency. Hooks remain fire-and-forget and bounded.+5. Never bypass workspace/project isolation. Use `ScopeResolver` or its explicit+ helpers for every read and write path.+6. Never bypass auth. Use `AuthLevel::authorize(Capability::...)` for all admin+ and write surfaces.+7. Never write wiki files directly from a handler or background worker. Use+ `Wiki::write_page`, `Wiki::apply_batch`, or existing destructive helpers.+8. Never auto-delete semantic pages. Use supersession, pending proposals, or the+ existing retention sweep for episodic pages.+9. Never rewrite pinned pages or invariant slots unless the proposal cites a+ direct contradiction and is explicitly approved.+10. Include source evidence for every proposed edit.+11. Attribute autonomous proposals to a distinct `auto_improve` actor so audit+ logs, admission webhooks, and review screens can distinguish machine-suggested+ changes from user/root writes.+12. Bound model cost, input size, output size, and number of proposed page+ mutations per run.+13. Write a human-readable and machine-readable report for each run.++## Existing User Upgrade Contract++Default-available auto-improvement must not surprise existing installs:++1. Dry-run review may be exposed by default, but it must not write wiki files,+ pending proposal pages, handoffs, or audit rows.+2. Session-end triggering stays off until a bounded background scheduler and+ proposal storage exist; hooks must not gain LLM latency as a side effect of+ upgrade.+3. No database migration is required for the dry-run-only phase. Future pending+ proposal storage must use additive, idempotent migrations that preserve all+ existing wiki files and session/observation rows.+4. Existing installed `CLAUDE.md`/`AGENTS.md` blocks remain valid. Operators pick+ up newer proactive retrieval guidance by running `ai-memory install-instructions`+ or asking an agent to refresh the ai-memory routing block. The marker-based+ replacement must remain idempotent.+5. Future staged/apply modes must default to reviewable staging before any+ mutation and must keep approval attribution separate from the autonomous+ `auto_improve` proposal actor.++## Configuration Sketch++The exact names can change, but the shape should be explicit and conservative:++```toml+[auto_improve]+enabled = true+mode = "dry_run" # dry_run | stage | auto_apply, auto_apply future only+on_session_end = false # opt in separately from manual runs+min_observations = 8+min_session_duration_secs = 120+min_confidence = 0.75 # tune from dry-runs before any auto_apply mode+max_input_tokens = 24000+max_proposals_per_run = 5+include_raw_fallback = false+proposal_actor = "auto_improve"+pending_path = "_pending/auto-improve"++[auto_improve.maintenance]+enabled = false+interval_hours = 168+min_idle_hours = 2+dry_run_first = true+```++`mode = "auto_apply"` should not ship until staged proposals have enough real+usage to calibrate prompt quality and false-positive rates. The confidence+threshold should remain configurable because real projects vary; initial values+should be chosen from dry-runs against existing deployed wikis, not from prompt+intuition alone.++## Proposal Format++The LLM output should be structured JSON, validated before anything is staged:++```json+{+ "summary": "short human summary",+ "proposals": [+ {+ "operation": "create_or_update",+ "path": "gotchas/example.md",+ "title": "Example gotcha",+ "kind": "gotcha",+ "confidence": 0.82,+ "rationale": "why this is durable",+ "evidence": [+ {"page": "sessions/abc.md", "quote": "bounded quote"}+ ],+ "body_markdown": "# Example gotcha\n\n..."+ }+ ],+ "rejected_candidates": [+ {+ "reason": "single-command smoke test",+ "evidence": "sessions/xyz.md"+ }+ ]+}+```++Validation should reject proposals with missing evidence, wrong path prefix,+oversized bodies, attempts to mutate protected pages, unsupported operations,+or confidence below the configured threshold.++## Pending Review UX++The first useful UX can be simple. The dry-run command is implemented; staging+and approval commands remain future work. The MCP dry-run tool is also+implemented so agents can ask for a learning review without shelling out.++| Command or route | Purpose |+|---|---|+| `ai-memory auto-improve --dry-run` | Preview proposals for a project/session. |+| `memory_auto_improve` | MCP dry-run preview for the latest completed session or a named session. |+| `ai-memory auto-improve --stage` | Store pending proposals without applying. |+| `ai-memory pending-writes list` | Show staged wiki changes. |+| `ai-memory pending-writes diff <id>` | Show markdown diff. |+| `ai-memory pending-writes approve <id>` | Apply through the normal wiki mutation path. |+| `ai-memory pending-writes reject <id>` | Discard proposal with audit trail. |++Pending proposals should be visible as markdown under `_pending/auto-improve/`+so humans can review them in the wiki/Obsidian workflow. SQLite can still hold+proposal state, approval status, evidence metadata, and audit rows, but the+review artifact itself should be inspectable and versioned like the rest of the+wiki.++Because this is now an MCP tool surface, the standard prompt snippets and+regression tests assert `memory_auto_improve` appears in both prompt surfaces.+Existing installed `CLAUDE.md`/`AGENTS.md` snippets update idempotently when the+operator runs `ai-memory install-instructions` or asks an agent to refresh the+ai-memory routing block.++## Maintenance Loop Shape++Keep the curator analogue separate from the post-session learning reviewer.++The maintenance loop should handle:++1. Duplicate or near-duplicate titles.+2. Narrow pages that should be merged into a broader concept/gotcha.+3. Stale `_slots/current-focus.md` state.+4. Episodic pages that the retention formula marks cold.+5. Broken cross-references and contradiction candidates already surfaced by+ `memory_lint`.++The maintenance loop should start as report-only. Later it can stage merge or+supersession proposals. It should not auto-delete semantic pages.++## Implementation Phases++### Phase 1: Dry-Run Reviewer++Status: implemented for explicit CLI/admin/MCP dry-runs.++Add a library-level reviewer that consumes one completed session plus existing+wiki context and returns validated proposals. No writes except an optional run+report. The initial shipped surface requires `--dry-run` and an explicit+`--session-id`; it refuses staging/apply until pending proposal storage exists.++The implemented reviewer is designed for existing projects with large histories:+it treats the consolidated `sessions/<id>.md` page as the primary source when it+exists, then adds a bounded deterministic sample of raw observations selected+from start/end context, user prompts, high-importance events, error/fix/decision+keywords, and evenly spaced checkpoints. Validation rejects missing evidence,+unsupported paths, low confidence, oversized bodies, duplicate existing paths or+titles, and normalizes a missing H1 by prepending the proposal title before final+validation.++Tests:++1. Empty/no-activity sessions produce no proposals.+2. Single-command smoke sessions produce no proposals.+3. A session with a durable root cause produces one gotcha proposal.+4. A session with an explicit user rule produces one `_rules/` proposal.+5. Missing evidence rejects the proposal.++### Phase 2: Pending Wiki Writes++Add durable pending proposal storage under `_pending/auto-improve/`,+list/diff/approve/reject commands, and audit rows. Approval applies through+`Wiki::apply_batch` and existing admission hooks with the `auto_improve` actor+preserved in proposal provenance.++Tests:++1. Pending proposals survive restart.+2. Approval writes files and index rows atomically.+3. Rejection never writes a wiki file.+4. Protected page proposals are rejected before staging.+5. Cross-workspace partial scopes fail closed.+6. Pending proposal markdown is created under `_pending/auto-improve/` and never+ indexed as approved durable knowledge.+7. Approval/audit metadata preserves `auto_improve` proposal attribution and the+ approving actor separately.++### Phase 3: Optional Session-End Trigger++Add a background trigger behind config. It should run after the normal session+page is written and never block the hook response.++Tests:++1. Disabled config does nothing.+2. Enabled config stages proposals after session-end.+3. Saturated or failed review leaves normal session-end behavior intact.+4. Reports include model/provider, scope, proposals, rejections, and errors.++### Phase 4: Maintenance Curator++Add a separate scheduled report that uses existing lint, access counters,+retention scoring, links, and page metadata to propose merges/supersessions.++Tests:++1. First run defers or dry-runs before mutating behavior is possible.+2. Pinned pages and invariant slots are skipped.+3. Semantic pages are never hard-deleted.+4. Proposed merges identify source and destination pages with evidence.++## Resolved Design Choices++1. Pending proposals should be a first-class wiki structure under `_pending/`,+ with SQLite retaining state and audit metadata.+2. Procedural lessons should have a `procedures/` page family instead of being+ forced into `gotchas/` or `concepts/`.+3. Autonomous proposals should be attributed to a distinct `auto_improve` actor,+ with approval attribution tracked separately.+4. The minimum confidence threshold should be configurable and calibrated with+ dry-runs on real projects before any future auto-apply mode is considered.++## Remaining Open Question++Should approval be CLI/admin-only at first, or exposed to agents through MCP?++## 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+knowledge while keeping active task execution isolated.++For ai-memory, the next correct step after the dry-run reviewer is pending+proposal storage under `_pending/auto-improve/` plus approval/rejection commands.+Direct autonomous wiki mutation should remain out of scope until staged proposals+prove high signal in real deployments.diff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex 61c0aefd..f1f85bc8 100644--- a/docs/design-decisions.md+++ b/docs/design-decisions.md@@ -137,6 +137,14 @@ Three scheduled MCP operations:Decay/forget runs as a separate `memory_forget_sweep` job: applies the retention formula; soft-deletes via `is_latest=false` + `superseded_at`; hard-deletes only after 180 days *and* zero accesses. Never silently destroys anything user-pinned.+Auto-improvement work stays separate from normal session consolidation. The+dry-run reviewer notes and proposed staged design are in+[`docs/auto-improvement-loop.md`](auto-improvement-loop.md). The short version:+learning review is default-available when an LLM provider is configured, but the+default mode is read-only and reviewable; staged/apply behavior must remain+explicit, scoped through the shared resolver/auth paths, and must not mutate the+active agent context mid-turn.+## 9. Cross-agent handoffA first-class typed protocol, shared state:@@ -175,6 +183,7 @@ basic-memory has ~25 tools, agentmemory has 53. Both have user confusion as a re| `memory_handoff_accept` | Fetch + ack the latest open handoff | destructive || `memory_handoff_cancel` | Mark an exact mistakenly-created open handoff expired | destructive || `memory_consolidate` | LLM-driven page rewrite (`multi_page=true` for atomic fan-out) | destructive |+| `memory_auto_improve` | Dry-run learning review that proposes durable wiki edits with evidence; no writes | read-only || `memory_write_page` | Write durable wiki knowledge on explicit user request | destructive || `memory_read_page` | Read a full page body by exact path or top search hit | read-only || `memory_delete_page` | Delete a single exact-path page with admission hooks | destructive |diff --git a/docs/install.md b/docs/install.mdindex a11e2a72..f86542d6 100644--- a/docs/install.md+++ b/docs/install.md@@ -65,11 +65,19 @@ ai-memory install-mcp --client claude-code --applyai-memory install-hooks --agent claude-code --apply```-The CLI commands (`bootstrap`, `status`, `search`, `lint`, etc.) inherit the-two env vars automatically. So do `install-mcp`, `install-hooks`, and+The CLI commands (`bootstrap`, `status`, `search`, `lint`, `auto-improve+--dry-run`, etc.) inherit the two env vars automatically. So do `install-mcp`,+`install-hooks`, and`setup-agent`: with `AI_MEMORY_SERVER_URL` set, `install-mcp` derives the`/mcp` endpoint and `install-hooks` uses the bare server origin.+After upgrading ai-memory, refresh the managed routing block in existing+projects so Claude Code/OpenCode/Codex/Gemini pick up new tool guidance and+proactive retrieval rules. From an agent, ask "refresh the ai-memory routing in+this project"; from the terminal, run `ai-memory install-instructions` (or pass+`--target AGENTS.md` for non-Claude prompt files). The update is idempotent and+only replaces the `<!-- ai-memory:start -->` / `<!-- ai-memory:end -->` block.+---## Configuring the CLI URL and authdiff --git a/docs/mcp-install.md b/docs/mcp-install.mdindex 943a72a2..a5937d7c 100644--- a/docs/mcp-install.md+++ b/docs/mcp-install.md@@ -36,7 +36,7 @@ endpoint. The trade-off:| | What you get | What you don't get ||---|---|---|-| **MCP only** | LLM can query the wiki, accept handoffs, run memory_consolidate | No automatic session-end summaries; no auto-handoff at session boundaries |+| **MCP only** | LLM can query the wiki, accept handoffs, run memory_consolidate, and dry-run `memory_auto_improve` learning reviews | No automatic session-end summaries; no auto-handoff at session boundaries || **MCP + hooks** | All of the above *plus* every prompt/tool-call captured automatically; handoffs surface at SessionStart with no human prompting | - |For MCP-only use, you can still cover the session-boundary gap by asking@@ -488,7 +488,7 @@ You: List the MCP tools you can call. Use one of them to checkModel (any client): I can call: memory_query, memory_recent,memory_status, memory_briefing, memory_explore,memory_handoff_accept, memory_handoff_begin, memory_handoff_cancel,- memory_consolidate, memory_write_page, memory_read_page, memory_delete_page,+ memory_consolidate, memory_auto_improve, memory_write_page, memory_read_page, memory_delete_page,memory_lint, memory_forget_sweep, memory_install_self_routing.memory_status reports: 0 pages, 0 observations, 0 sessions.```diff --git a/docs/usage.md b/docs/usage.mdindex 6e1487ef..7f37bd1e 100644--- a/docs/usage.md+++ b/docs/usage.md@@ -54,11 +54,18 @@ the wiki without you naming tools explicitly.| "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. || "Consolidate this session" | `memory_consolidate` | Manually runs LLM consolidation. Also runs on PreCompact, and at session end only when `AI_MEMORY_CONSOLIDATE_ON_SESSION_END` is set (off by default; session end otherwise writes a rule-based summary page). |+| "What did we learn from this session?" / "what memory should we add?" | `memory_auto_improve` | Dry-run learning review. Reviews the latest completed session by default, returns proposed wiki edits with evidence, and writes nothing. || "Remember this permanently" / "add an annotation" | `memory_write_page` | Writes durable wiki knowledge; not a single-use handoff. || "Delete this page" / "remove the note about X" | `memory_delete_page` | Removes a page by exact path. Pass `workspace` + `project` together when the page lives in a sibling workspace, so a project name shared between workspaces never silently routes the delete to the wrong slot. || "Audit the wiki" / "any contradictions?" | `memory_lint` | Runs stale-page, contradiction, and rule-suggestion checks. || "How big is the wiki?" / "stats?" | `memory_status`, `memory_briefing` | Counts and recent activity windows; `memory_briefing` is read-only. |+Agents should treat retrieved memory as operating guidance. When search returns+matching `_rules/`, `gotchas/`, `procedures/`, or `decisions/` pages, read the+full page before acting: rules are constraints, gotchas are preflight warnings,+procedures are checklists, and decisions are settled architecture unless the+user explicitly asks to revisit them.+## Install the routing snippetFrom an agent, say: