Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: remove three orphaned/superseded docs before 2.3.0
AkitaOnRails02a1ac50c8c2
diff --git a/docs/auto-improve-skillopt-roadmap.md b/docs/auto-improve-skillopt-roadmap.mddeleted file mode 100644index b9151706..00000000--- a/docs/auto-improve-skillopt-roadmap.md+++ /dev/null@@ -1,295 +0,0 @@-# Auto-Improve SkillOpt-Inspired Roadmap--This is the ongoing implementation plan for borrowing the best safety ideas from-SkillOpt without turning ai-memory into a workflow manager, benchmark harness, or-agent orchestration platform.--## Boundary--ai-memory remains a memory substrate:--- automatic capture from lifecycle hooks;-- markdown wiki as the source of truth;-- SQLite as the derived index and audit store;-- small, auditable wiki proposals through pending-writes;-- optional LLM review outside hook latency.--This roadmap does **not** add a spec-driven workflow, mandatory task scoring,-agent replay engine, skill router, code graph, or benchmark registry.--## Why this work matters--The current auto-improvement loop validates proposals structurally: path, kind,-confidence, evidence, size, duplicate checks, and approval policy. That is useful-but not enough for high-impact pages such as `_rules/` and `procedures/`, where a-bad edit can shape future agent behavior. The biggest wins are to make proposed-changes smaller, easier to review, harder to repeat after rejection, and optionally-measurable when a project supplies its own scoring command.--## Invariants--- Existing full-page `create_or_update` proposals must continue to validate,- stage, diff, approve, reject, and audit.-- New behavior must be additive migrations/config; existing installs keep the- same defaults.-- Target wiki mutations must still pass through `Wiki::write_page`,- `Wiki::apply_batch`, or existing approval helpers.-- Server/admin/MCP paths must preserve `ScopeResolver` and- `AuthLevel::authorize(Capability::...)` boundaries.-- Hooks must remain fire-and-forget and must not run LLM review, patching, or- evaluation gates.-- No new public MCP tool surface unless the existing `memory_auto_improve` and- pending-writes surface cannot express the workflow.--## Phase 1 — Structured Patch Proposals With Minimal Budgets--Add patch proposals as a backwards-compatible extension to the existing proposal-shape. Full-page bodies remain supported forever, especially for new pages.--Preferred update mode for `_rules/` and `procedures/` should become small-structured patches, but only when the reviewer has enough target-page context to-name stable anchors. Full-page proposals still must not overwrite existing-semantic/procedural pages; patch proposals require an existing target page.--```json-{- "edit_mode": "patch",- "edits": [- {"op": "append", "anchor": "## Release process", "content": "..."},- {"op": "replace_section", "anchor": "## Gotchas", "content": "..."}- ]-}-```--Initial supported operations:--- `add_section`-- `append`-- `replace_section` only with section hash/context verification--`delete_section` is deferred. If it is later added, it must either be excluded-from auto-approval or force manual approval even when global auto-approve is-enabled.--Patch semantics:--- Anchors use exact markdown heading text, including marker, e.g.- `## Release process`.-- Anchors must be unique after normalized whitespace comparison; duplicate- anchors reject.-- H1 replacement/deletion is not supported.-- A section span starts at the anchor heading and ends before the next heading of- equal or higher level. Child subsections are included in `replace_section`.-- `append` inserts content at the end of the anchored section before the next- equal-or-higher heading, preserving a blank-line boundary.-- `add_section` inserts a new sibling section after the anchored section span.-- `replace_section` requires a pre-edit section hash or exact context and- rejects if the section changed.-- Final materialized bodies must still pass the normal H1, path, kind, and size- validation.--Minimum Phase 1 budget caps:--- max edits per proposal;-- max content chars per edit;-- max changed chars per proposal;-- max final body size.--Implementation notes:--- Materialize patches into final `body_markdown` for compatibility with the- existing approval flow, but close the materialize-to-stage race by passing an- expected base hash into staging and rejecting if the current target hash- differs. Materialization may also move inside the same writer transaction if- that proves cleaner.-- Store original patch JSON for audit/diff/debug.-- Store `edit_mode`, original `patch_json`, expected base hash, materialized- base hash, and final body metadata through an additive migration. Existing- rows default to full-page mode.-- Include bounded target page bodies or heading outlines for patchable `_rules/`- and `procedures/` pages in the reviewer prompt. Do not request patches for- pages whose anchors were not provided.-- Store target page hash at staging and reject approval if the page changed.-- Use markdown heading anchors and context/hash checks, not line-number patches.--Required tests:--- old full-page proposals still work;-- each patch operation materializes correctly;-- invalid/missing anchors reject cleanly;-- target hash conflict blocks approval;-- page changes between materialization and staging reject;-- old pending proposals remain readable and approvable after migration;-- duplicate anchors reject;-- patch to missing target rejects;-- full-page proposal to an existing non-slot page still rejects;-- destructive operations cannot auto-approve if added later;-- `_rules/` and `procedures/` reviewer instructions prefer patch mode.--## Phase 2 — Bounded Edit Budgets--Phase 1 absorbed the minimum per-proposal caps needed to ship patch proposals-safely: patchable page/context bounds, edits per proposal, edit content chars,-changed chars per proposal, and global final body chars. Phase 2 adds the-remaining run-level and page-class budgets. Defer cosine decay or maturity-schedules until there is real operational data.--Proposed config shape:--```toml-[auto_improve]-max_proposals_per_run = 5-max_patch_edits_per_proposal = 4-max_patch_edits_per_run = 8-max_changed_chars_per_proposal = 4000-max_rule_page_tokens = 2000-max_procedure_page_tokens = 2000-```--Validation rejects proposals that exceed the run-level patch edit budget or-procedural/rule final-page budgets. The earlier Phase 1 validators continue to-enforce per-proposal edit count, changed-char, edit-content, and global final-body limits.--Required tests:--- per-run patch edit limits;-- `_rules/` / `procedures/` page-budget enforcement;-- existing non-patch behavior remains unchanged except existing global limits.--## Phase 3 — Rejected Proposal Buffer--Status: implemented.--Persist useful rejection memory and feed a bounded summary into future reviewer-prompts so the model does not repeat failed edit patterns.--Proposed table:--```text-auto_improve_rejections-- id-- workspace_id-- project_id-- target_path-- kind-- operation/edit_mode-- reason-- normalized_fingerprint-- summary-- evidence_json-- source_run_id-- source_proposal_id nullable-- created_at-```--Populate from:--- validator rejects;-- human pending-writes rejects;-- approval conflicts;-- admission failures;-- future eval-gate failures.--Prompt context should include only a bounded recent subset, e.g. latest 50 per-project or 180 days. Do not add embeddings initially.--Implementation notes:--- `V24__auto_improve_rejections.sql` adds `auto_improve_rejections` with- workspace/project pairing enforcement plus recent, fingerprint, and path- indexes.-- Human rejects, admission failures, and approval conflicts write rejection- records in the same decision transaction.-- Validator/model rejected candidates are persisted at run staging when a reason- is present; target path/kind/operation/edit-mode are stored when the rejection- carries that metadata.-- Reviewer prompts include recent same-scope rejection summaries bounded by- `max_rejection_context` and `rejection_context_days`.--Required tests:--- human rejection creates a reusable rejection record;-- validator rejection creates a record when enough metadata is available;-- future prompts include relevant prior rejections;-- workspace/project isolation is preserved;-- old pending proposals remain approvable/rejectable.--## Phase 4 — Optional Executable Evaluation Gate--Status: implemented.--Only run when a project explicitly supplies a scoring command. Disabled means the-current validation + approval behavior is unchanged.--Proposed config:--```toml-[auto_improve.eval]-enabled = false-command = "./scripts/score-auto-improve-proposal"-timeout_secs = 120-targets = ["_rules", "procedures"]-min_delta = 0.0-```--Contract:--- ai-memory does not build a benchmark registry, replay harness, scoring DSL, or- agent simulator;-- the external command is executed directly (not through a shell) with JSON on- stdin containing proposal metadata plus before/after bodies;-- the command returns JSON such as- `{ "score_before": 0.72, "score_after": 0.76, "passed": true }`;-- when scores are present, `score_after - score_before` must meet `min_delta`;-- failed, timed-out, errored, or invalid-JSON evaluations fail closed for targeted- proposals and are recorded as rejected candidates with reasons such as- `eval_gate_failed`, `eval_gate_timeout`, or `eval_gate_error`.--If every proposal in a run fails eval, ai-memory stages the run with zero-proposals and the eval rejections so the rejection buffer still learns from the-attempt. Non-targeted proposals bypass eval even when the gate is enabled. Hook-paths remain fire-and-forget and never run the eval command.--Non-goals:--- no replay orchestration;-- no benchmark/task registry;-- no scoring DSL;-- no agent simulator.--Required tests:--- eval disabled preserves current behavior;-- passing eval allows staging/approval;-- failing eval rejects and records rejection;-- timeout/error fail closed for eval-targeted proposals;-- eval never runs from hook paths.--## Phase 5 — Slow / Meta Update Later--Status: report-only step implemented; `_meta` update and cross-project-optimizer memory not started.--Defer the rest until patch proposals, edit budgets, rejections, and optional-evals produce enough data.--First version should be report-only. `auto_improve_telemetry.rs` ships this:-a structured `AutoImproveTelemetryReport` (terminal rates, bounded findings,-blind spots) built from persisted proposal outcomes, staged and approved like-any other report — approval writes the report page only and performs no-learning-memory changes, and it explicitly does not edit rules, procedures,-notes, or `_meta` pages.--Later, a protected `_meta` section can be updated through a normal pending-proposal, never directly by a per-session review. Cross-project optimizer-memory is explicitly out of scope until there is evidence it helps ai-memory-users. Neither has been started.--## Completion Criteria--This roadmap is complete when phases 1–4 are implemented with docs, migrations,-tests, and changelog entries, and phase 5 has either a report-only design or a-documented deferral with evidence requirements. Phases 1–4 and phase 5's-report-only step are done; the `_meta` update and cross-project optimizer-memory remain deferred pending evidence.diff --git a/docs/testing/codex-provider.tdd.md b/docs/testing/codex-provider.tdd.mddeleted file mode 100644index 391f6a85..00000000--- a/docs/testing/codex-provider.tdd.md+++ /dev/null@@ -1,84 +0,0 @@-# Codex provider TDD evidence--Date: 2026-09-11--Development started as a local validation branch with no issue, PR, or-`CHANGELOG.md` reference. After the local smokes passed, issue #716 was opened-and the real reference was added to `CHANGELOG.md` before publication.--## RED--Commit after rebasing onto v2.1.2: `6a375344 test: add codex provider-configuration reproducers`--Command:--```text-cargo test -p ai-memory-llm codex_auth_round_trips_only_resolved_paths --no-default-features-```--Expected failure observed: Rust reported that `ProviderAuth::codex`,-`AuthRequirement::CodexAuthFile`, and `ProviderChoice::Codex` did not exist.--## GREEN--Focused commands after implementation:--```text-cargo test -p ai-memory-llm codex::tests --no-default-features-cargo test -p ai-memory-llm openai_oauth::tests --no-default-features-cargo test -p ai-memory-cli codex --no-default-features-```--Observed results:--- Codex unit/recovery suite: 10 passed.-- Existing openai-oauth regression suite: 18 passed.-- Codex-related CLI/config tests: 20 passed after rebasing onto v2.1.2.--The recovery suite compiles a fake Codex executable from Rust source. It runs-without network access or a real home directory and covers handshake messages,-interleaved notifications, wrong IDs, invalid and oversized output, stderr-limits, premature process exit (both zero and non-zero status), timeout,-process cleanup, and auth-file rotation. HTTP mocks cover account headers,-model, reasoning, SSE, structured output, reload-before-retry, and the-one-retry ceiling.--### Non-zero recovery exit follow-up--- RED commit: `76cfc1b6 test: reproduce non-zero Codex recovery exit`.-- RED command: `cargo test -p ai-memory-llm- rust_fake_codex_exercises_recovery_and_defensive_failures -- --nocapture`.-- RED result: the new `exit-nonzero` mode timed out because the fake executable- did not yet implement it.-- GREEN implementation: the fake executable now exits with status 17, proving- that an app-server failure before a JSON-RPC reply is rejected as a- sanitized premature-exit error.--## Local gates and smoke--- `cargo fmt --all -- --check`: passed.-- `git diff --check`: passed.-- `TAILWIND_SKIP=1 cargo clippy --workspace --all-targets -- -D warnings`:- passed.-- `cargo deny --all-features check`: passed (`advisories`, `bans`, `licenses`,- `sources`).-- `TAILWIND_SKIP=1 cargo test --workspace`: provider and downstream suites- passed until two unrelated `ai-memory-core::routing_skills` assertions hit- CRLF bytes in the existing Windows checkout. Neither the embedded skill- assets nor their tests are changed by this branch.-- The complementary run excluding `ai-memory-core`, followed by all other- `ai-memory-core` tests with only those two checkout-sensitive assertions- skipped, passed. The standalone companion importer suite also passed (19- tests).-- `cargo llvm-cov` was unavailable locally, so the 80% target was not measured;- the new parser, HTTP/retry path, structured output, protocol limits, native- process recovery, failure cleanup, and concurrent recovery are directly- exercised.-- Live text smoke (`gpt-5.6-luna`, effort `medium`): returned- `AI_MEMORY_CODEX_TEXT_OK`.-- Live structured smoke (`gpt-5.6-luna`, effort `medium`): returned- `{"answer":"AI_MEMORY_CODEX_STRUCTURED_OK"}`.-- The Codex auth-file SHA-256 was identical before and after both smokes, and- `codex login status` remained authenticated. The digest itself is omitted- from this repository artifact.diff --git a/docs/v0.3-roadmap.md b/docs/v0.3-roadmap.mddeleted file mode 100644index dc3c4b77..00000000--- a/docs/v0.3-roadmap.md+++ /dev/null@@ -1,135 +0,0 @@-# v0.3 roadmap--Captured items deferred from v0.2 and ideas surfaced post-M10.-Nothing here is committed to a milestone yet; this is a parking lot.--## Bigger features--### Rule-vs-fact disambiguation in consolidation--**Problem.** Users sometimes type durable project rules into the-agent - "don't forget to never add a new function without a unit-test", "we always run lint before merging", "memory mustn't store-PII". These end up as ordinary observations in ai-memory. But they'd-be more useful as instructions in the project's `CLAUDE.md` /-`AGENTS.md`, because:--- Rules need to fire on every relevant action; ai-memory queries- fire when the agent thinks to call them.-- Project-instruction files are checked into version control and- visible to the whole team.--**Sketch.** Extend the consolidator's structured-output schema to-classify each surfaced observation into `{decision, fact, rule,-gotcha}`. Rule-tagged items land in a separate page-`wiki/_rules/uncommitted.md` AND surface a lint finding:--> "This rule isn't in your project's CLAUDE.md — consider adding it-> there so the agent sees it on every turn, not just when it-> searches memory."--Detection heuristics: starts with `always`, `never`, `don't`,-`remember to`, `before X always`, `as a rule`, or contains-`(rule|policy|convention)`. Easy, ~50 lines plus the lint surface.--The output is a *suggestion only* - ai-memory never auto-edits a-user's CLAUDE.md / AGENTS.md / project instructions file.--### Bootstrap an existing project's history into the wiki--**Problem.** Today ai-memory starts empty for any project. For-existing projects with months of decisions in `git log`, `docs/`,-`README.md`, code comments - that's a lot of warm context the user-already paid for once, and we throw it away.--**Sketch.** A `ai-memory bootstrap` one-shot subcommand. Inputs:--- `git log --oneline -p` filtered to commits with substantive- messages (e.g. > 100 chars body, conventional-commit prefix, or- matching `^(feat|fix|refactor|design):`).-- README + `docs/*.md` + `CLAUDE.md` if present.-- Module-level doc-comments from the codebase (`find . -name- "*.rs" | xargs head -30`, language-aware).--LLM consolidates these into:--- `wiki/concepts/<topic>.md` per recurring theme-- `wiki/decisions/0001-…md` per ADR-shaped commit-- A bootstrap handoff page summarising "what I learned about this- project"--Bootstrap pages get `tier: bootstrap` in their frontmatter so the-lint pass treats them as lower-confidence than session-grown pages,-and they participate normally in the decay sweep.--**Risk.** LLM-fabricated detail polluting the wiki. Mitigations:-the user reviews + commits the wiki tree before keeping (it's a git-repo); bootstrap pages are explicitly tagged so a `forget-sweep` can-target them; the LLM is instructed to mark uncertain claims with a-`(needs verification)` suffix.--### CI matrix tightening--Currently `ci.yml` runs fmt + clippy + test + cargo-deny + cargo--audit + gitleaks on `ubuntu-latest` only. Worth adding:--- macOS runner (catches stat / SELinux-label assumptions)-- A `cargo build --release` step so we don't ship code that fails- release-mode optimisation-- A docker-build smoke step that confirms `docker run --rm- $IMAGE --version` works after every push--## Smaller polish--### Hook scripts as a generated artefact — tried, dropped--A `bin/regen-hooks` templating the scripts from one flat-agent × event matrix existed and was removed. The premise stopped-holding: the bundles are no longer identical. Agents carry their own-event vocabularies (`CLAUDE_CODE_EVENTS`, `KIMI_CODE_EVENTS`,-`KIRO_CLI_V*_EVENTS`, Devin's `post-compaction`, …), each `.sh` has a-`.ps1` peer, the bodies delegate to `hooks/_lib.sh` /-`hooks/lib/ai-memory-hook.ps1`, and several carry per-agent behaviour-(Claude Code's `hookSpecificOutput` wrapper, Antigravity's gated-startup handoff). A generator faithful to that is `render_shared.rs`-rewritten in bash.--The drift it was meant to prevent is covered instead by-`bundled_posix_and_powershell_hooks_stay_in_parity`, which enumerates-every bundle under `hooks/` and asserts each `.sh` has a `.ps1` peer-posting the same `event=`/`agent=`. Adding an event means adding both-files plus the entry in the agent's event array in-`crates/ai-memory-cli/src/commands/render_shared.rs`.--### Consolidator prompt templating--Both `build_batch_request` and `build_request` in-`crates/ai-memory-consolidate/src/consolidator.rs` `push_str` their-way to a prompt. Constants are fine for two prompts. If the count-grows to four+ a small templating helper would earn its keep.--### `Handoff` field grouping — done--Shipped in #457: the struct's 18 public fields are now grouped into-`HandoffScope`, `HandoffOrigin`, `HandoffContent`, and-`HandoffLifecycle` sub-structs, each `#[serde(flatten)]`ed so the MCP-wire JSON is unchanged.--### `cargo install ai-memory` + `mise use -g github:akitaonrails/ai-memory`--Status: mise half done, no code needed; cargo install half blocked.--`mise use -g github:akitaonrails/ai-memory` already works today against-the existing tagged GitHub Releases — mise's GitHub backend matches the-`ai-memory-<os>-<arch>.tar.gz` asset naming convention with no plugin or-registry entry required, and verifies checksum, artifact attestation, and-SLSA provenance before extracting. Documented in `docs/install.md`.--`cargo install ai-memory` cannot ship as scoped: the crate name `ai-memory`-is already taken on crates.io by an unrelated project, and so is-`ai-memory-core`, the workspace's foundational internal crate that every-other crate here depends on. Publishing would require picking a new-registry name for at least `ai-memory-core` (keeping the `ai_memory_core`-Rust path via `package = "..."` in dependents, so no source churn) — a-naming decision for whoever owns crates.io publishing to make, not-something to pick unilaterally. Parked until that's decided.