Skip to content

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.md
index 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 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. 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 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
+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 lint
pass surfaces the same hint automatically when a `kind: rule` page
lands 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 -->` markers
without 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, supported
platforms, 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.md
index 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`) now
propagate the authenticated actor (from the auth middleware's
diff --git a/CLAUDE.md b/CLAUDE.md
index 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.lock
index 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.md
index 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` are
all HTTP clients of the running server - never touch SQLite or
wiki files directly. `status` also reports passive LLM/embedding
provider health from the last real provider call. Server is the
single 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 and
one-shot-summarises them into seed wiki pages. Future sessions
build 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 server
up on a homelab box at `0.0.0.0:49374` with a bearer token; every
laptop/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, and
MCP/hooks. Explicit `--server-url` flags still work, but are no longer
required when the env vars are set. Any non-loopback server should use
bearer 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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 = false
lint_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.rs
index 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.toml
index 4f94c9cd..12c65e87 100644
--- a/crates/ai-memory-consolidate/Cargo.toml
+++ b/crates/ai-memory-consolidate/Cargo.toml
@@ -24,6 +24,7 @@ tracing.workspace = true
jiff.workspace = true
[dev-dependencies]
+async-trait.workspace = true
tempfile.workspace = true
rusqlite.workspace = true
diff --git a/crates/ai-memory-consolidate/src/auto_improve.rs b/crates/ai-memory-consolidate/src/auto_improve.rs
new file mode 100644
index 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.rs
index 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.rs
index 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.rs
index 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, use
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 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
+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 lint
pass surfaces the same hint automatically when a `kind: rule` page
lands 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 -->` markers
diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rs
index 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.rs
index 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.rs
index 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.rs
index 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.md
index 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. No
circular deps. Inter-crate boundaries enforce the cross-cutting
invariants 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 pair
needed by admission-aware mirrors. `memory_handoff_cancel` is the safety valve
for 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.md
new file mode 100644
index 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.md
index 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 handoff
A 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.md
index a11e2a72..f86542d6 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -65,11 +65,19 @@ ai-memory install-mcp --client claude-code --apply
ai-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 auth
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index 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 check
Model (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.md
index 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 snippet
From an agent, say: