Skip to content

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.md
index 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 memory
record 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 is
invisible 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 provenance
to project/scopes hits. Cross-project search uses a distinct FTS-only ranker
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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` and
does 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 rules
diff --git a/crates/ai-memory-core/src/routing_snippet.rs b/crates/ai-memory-core/src/routing_snippet.rs
index 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 memory
record 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 is
invisible 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 provenance
to project/scopes hits. Cross-project search uses a distinct FTS-only ranker
diff --git a/docs/marker-file.md b/docs/marker-file.md
index 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 not
merge. A missing `[capture]` section or `ignore_paths = []` is inactive and
preserves current behavior. `[capture]` accepts only `ignore_paths`: unknown
diff --git a/docs/usage.md b/docs/usage.md
index 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 is
the whole workflow: copy the rule if it should apply every turn, ignore
it 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 lives
in 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-improvement
apply path hard-refuses to rewrite them (the proposal is recorded as
a 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 architectural
decision" and the skill does the rest; the structured shape also
retrieves noticeably better through `memory_query` than free-form
prose.