Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs(routing): repo-native decision records own the why, keep them out of capture (#700)
Oliver Zehentleitner AIgentb4fbc426d416
diff --git a/AGENTS.md b/AGENTS.mdindex 155e13b1..f215a6d2 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -32,6 +32,10 @@ forget sweep, and a TTL outranks `pinned`. ai-memory is the cross-harness memoryrecord for this project: if the harness you run in has its own local memory feature,do not keep durable project facts there in parallel — a harness-local store isinvisible to every other agent and fragments continuity, so capture them here instead.+A reviewed decision record kept in the repository (an ADR directory, a Keep the Why+`context/` tree) is not a harness-local store: when the project keeps one, record+decisions there under the project's convention; ai-memory keeps recall, handoffs and+session history and does not duplicate that record as a page.For ranking diagnosis, opt-in query explanations add bounded score provenanceto project/scopes hits. Cross-project search uses a distinct FTS-only rankerdiff --git a/CHANGELOG.md b/CHANGELOG.mdindex 48c56588..e2a9160e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Changed+- The managed routing snippet distinguishes a reviewed decision record kept in+ the repository (an ADR directory, a Keep the Why `context/` tree) from a+ harness-local memory store: decisions go into the repo's record under its+ convention, ai-memory keeps recall, handoffs and session history and does not+ duplicate the record as a page. `docs/usage.md` ("Repo-native decision+ records") and `docs/marker-file.md` say to list such a directory in+ `[capture] ignore_paths`, and why (#700).- The managed routing snippet now states that Claude Code loads `CLAUDE.md` anddoes not read `AGENTS.md`: a project whose canonical instruction file is`AGENTS.md` needs a bare `@AGENTS.md` import line in `CLAUDE.md`, or the rulesdiff --git a/crates/ai-memory-core/src/routing_snippet.rs b/crates/ai-memory-core/src/routing_snippet.rsindex 5ee57156..78d208c6 100644--- a/crates/ai-memory-core/src/routing_snippet.rs+++ b/crates/ai-memory-core/src/routing_snippet.rs@@ -60,6 +60,10 @@ forget sweep, and a TTL outranks `pinned`. ai-memory is the cross-harness memoryrecord for this project: if the harness you run in has its own local memory feature,do not keep durable project facts there in parallel — a harness-local store isinvisible to every other agent and fragments continuity, so capture them here instead.+A reviewed decision record kept in the repository (an ADR directory, a Keep the Why+`context/` tree) is not a harness-local store: when the project keeps one, record+decisions there under the project's convention; ai-memory keeps recall, handoffs and+session history and does not duplicate that record as a page.For ranking diagnosis, opt-in query explanations add bounded score provenanceto project/scopes hits. Cross-project search uses a distinct FTS-only rankerdiff --git a/docs/marker-file.md b/docs/marker-file.mdindex f07c833f..331c5cd4 100644--- a/docs/marker-file.md+++ b/docs/marker-file.md@@ -201,6 +201,14 @@ below to keep recognized file-tool activity under matching paths out of capture:ignore_paths = ["private/**", "~/personal-notes/**"]```+A repository that keeps its decision records in the tree — an ADR directory,+a [Keep the Why](https://github.com/oliver-zehentleitner/keep-the-why)+`context/` tree — belongs here too: `ignore_paths = ["docs/adr/**"]` or+`["context/**"]`. The repo owns that record; without the exclusion an agent's+read of it is captured and consolidation compiles it into wiki pages that do+not follow the repo, so the copy is stale the moment the record is superseded+(see the "Repo-native decision records" section of [`usage.md`](usage.md)).+The **nearest** `.ai-memory.toml` is authoritative; marker sections do notmerge. A missing `[capture]` section or `ignore_paths = []` is inactive andpreserves current behavior. `[capture]` accepts only `ignore_paths`: unknowndiff --git a/docs/usage.md b/docs/usage.mdindex 6403d8c9..b2b49529 100644--- a/docs/usage.md+++ b/docs/usage.md@@ -484,30 +484,48 @@ ai-memory never edits the rules file on its own. The lint suggestion isthe whole workflow: copy the rule if it should apply every turn, ignoreit if it was temporary context.-## Architecture Decision Records (ADRs)+## Repo-native decision records-Two facts frame how ADRs and ai-memory interact:+Some projects keep the reasoning behind the code in the repository itself: an+ADR directory such as `docs/adr/`, maintained by hand or by a dedicated ADR+tool/MCP server (e.g. [joshrotenberg/adrs](https://github.com/joshrotenberg/adrs)),+or a [Keep the Why](https://github.com/oliver-zehentleitner/keep-the-why)+`context/` tree (decisions, rejected alternatives, constraints, reviewed in+pull requests). Three facts frame how such a record and ai-memory interact:1. **ai-memory never touches files in your repository.** Its wiki livesin the server's data dir; the background jobs (consolidation,curation, retention decay, auto-improvement) read and write wiki- pages only. A `docs/adr/` directory in the repo — maintained by hand- or by a dedicated ADR tool/MCP server (e.g.- [joshrotenberg/adrs](https://github.com/joshrotenberg/adrs)) — is- categorically outside ai-memory's write surface. Run both side by- side without ceremony: the ADR tool owns the canonical log, ai-memory- owns cross-session recall.--2. **Wiki pages marked `pinned: true` are immutable to automation.**+ pages only. A decision-record directory in the repo is categorically+ outside ai-memory's write surface. Run both side by side without+ ceremony: the repo owns the canonical record, ai-memory owns+ cross-session recall.++2. **Keep the record directory out of capture.** An agent reading the+ record is captured like any other file read, and consolidation compiles+ what it saw into wiki pages — including a `decisions/` page that says+ "active" long after the repo has superseded it, ranked first by+ `memory_query` because it matches the topic. List the directory in the+ marker's `[capture]` section so the copy is never made:++ ```toml+ [capture]+ ignore_paths = ["docs/adr/**"] # or ["context/**"] for Keep the Why+ ```++ The repo owns that record; a compiled copy goes stale the moment the+ repo moves. Details and bounds in [`docs/marker-file.md`](marker-file.md).++3. **Wiki pages marked `pinned: true` are immutable to automation.**Retention decay and curation skip them, and the auto-improvementapply path hard-refuses to rewrite them (the proposal is recorded asa conflict with the reason). Unpinning is the explicit opt-out.-For decisions recorded *in* the wiki, the managed durable-pages Agent-Skill teaches agents the recipe: `decisions/<slug>.md`, ADR structure-(Status / Context / Decision / Consequences, including rejected-alternatives), `pinned: true`, and supersede-by-new-page instead of-editing history. Ask an agent to "record this as an architectural+For a project without a repo-side record, decisions go *in* the wiki, and+the managed durable-pages Agent Skill teaches agents the recipe:+`decisions/<slug>.md`, ADR structure (Status / Context / Decision /+Consequences, including rejected alternatives), `pinned: true`, and+supersede-by-new-page instead of editing history. Ask an agent to "record this as an architecturaldecision" and the skill does the rest; the structured shape alsoretrieves noticeably better through `memory_query` than free-formprose.