Memoria

The review flow

Watch one change go through. A commit edits login.rs, and Memoria marks the README that describes it as pending: it needs a look. Then it shows the diff and records the fix.

documents

README.mdcurrent

AGENTS.mdcurrent

src/auth/README.mdcurrent

code

src/main.rs

src/db/pool.rs

src/auth/login.rs

terminal

Folder scopes

A README covers its own folder and everything below it. One edit to auth/login.rs, and three ways the root README can treat auth/:

1 · says nothing

The root still covers auth/, so both READMEs are flagged.

./├─ README.md     pending├─ app.rs└─ auth/   ├─ README.md  pending   └─ login.rs   edited

2 · links auth/

The link hands auth/ to its own README. Only that one is flagged.

./├─ README.md     current├─ app.rs└─ auth/   ├─ README.md  pending   └─ login.rs   edited

3 · reuses its summary

The root reuses the auth/ summary, so it waits for that review.

./├─ README.md     waits  ◂─┐├─ app.rs                 │└─ auth/                  │   ├─ README.md  pending ─┘   └─ login.rs   edited

Every README.md is tracked. Other Markdown files join when they contain a Memoria comment. A plain link never tracks a file.
A link hands a folder over. Remove the link later, and the root covers that folder again.
Reused summaries set the order. A doc that reuses a summary is reviewed after the doc it comes from.

Document markers

Folders do most of the work. Plain HTML comments add the rest: which part of a doc describes which code, and which summary other docs reuse. Nothing else in your Markdown changes.

src/auth/README.md

1# Authtracked · covers src/auth/ and below

2

3export · a summary other docs reuse

4Auth signs users in with a password or a passkey.

5

6

7section · maps src/auth/**

8## Sessions

9A session lasts 15 minutes, then the user signs in again.

10

every change runs the same loop

─▸

README pendingmemoria status

─▸

read the diffmemoria review

─▸

fix the READMEyou or your agent

─▸

README currentmemoria ack

◂──── the next change starts it again ─────

An ack only counts for the exact files you read. If anything changed after you saved the review, Memoria refuses the ack instead of approving code nobody looked at. A passing memoria check means every doc was checked against its current code. Whether the prose is good is still up to you.

Exports and imports

Mark a summary in one doc and reuse it in others. memoria render copies it into place, so five READMEs never drift apart.

The source is reviewed first, so nobody checks a half-finished copy. Render only rewrites the marked copy and leaves the rest of the file alone. Change the summary once, and every doc that reuses it is queued for review in the right order.

Project guidance

Write your documentation rules once in memoria.toml. Every review lists them, and memoria guidance prints them for any doc.

memoria.toml · project guidance

[documentation]
guidance = [
  "Explain the operational workflow before implementation details.",
]
guidance_files = ["docs/writing-guidance.md"]

AGENTS.md · section guide

<!-- memoria:section id="boundaries"
     guidance="docs/templates/agent-rules.md" -->
## Boundaries
…
<!-- /memoria:section -->

terminal

$ memoria guidance src/README.md   # the rules for one document
$ memoria guidance --changed       # reviewed documents that saw older wording

Advice, not a trigger. Rules never decide which files a doc covers, and never flag a doc on their own.
Changing a rule flags nothing. The review plan notes the change, memoria check still passes, and you decide which docs deserve a fresh look.
Narrow rules stay narrow. Rules for one kind of section only reach the sections that name them. Project rules win any conflict.

When to use Memoria

Four jobs it does well, from one stale file to a blocked merge.

Find every doc a feature change touchesEach doc that covers a changed file is flagged, in the order to review them.

Block a merge until the docs are checkedmemoria check fails in CI while any review is pending.

Keep AGENTS.md and CLAUDE.md honestBoth are tracked, and shared writing rules apply to each section that names them.

Re-check docs after a decision, not a diffmemoria invalidate asks for a review and records your reason.

Design principles

Memoria proves that someone checked. It never writes your docs or grades them.

never writes

The only text it ever changes is a summary copy you marked, and only when you run memoria render.

never judges

Whether an explanation is clear or true is for you or your agent to decide.

never decides

You choose what each doc is about. Memoria works with whatever you choose.

Onboard your agent

One command gets an agent started. memoria onboard explains Memoria, reads where your project stands, and names the next step. Nothing to install.

tell your agent

Run `memoria onboard` (the Memoria CLI) and follow the next step it gives.

terminal

$ memoria onboard
Memoria 0.9.2 — CI for your docs

When code changes, Memoria marks the documents that explain it as pending and
shows exactly what changed. `memoria check` fails your build until someone has
reviewed them. You and your agents write every word; Memoria never edits prose.

How it works
  1. Code changes, and every document that covers the changed file becomes pending.
  2. `memoria review` shows what changed and what the review must read.
  3. You or an agent update the document. `memoria ack` records the review.
  4. `memoria check` in CI passes only when no document is pending.

This project  ~/code/shop
  Memoria       4 documents · 1 pending
  Agent skill   not installed     → memoria agent install --target claude
  CI check      not installed     → memoria integrations github install

Next: memoria review
  1 document needs a review. `memoria onboard review` walks through it.

Go deeper
  memoria onboard review     review a pending document, step by step
  memoria onboard agent      let an agent keep your docs current
  memoria onboard ci         block merges while docs are pending

optional integrations

memoria agent install --target claudethe review skill for Claude Code or Codex

memoria agent hook install --target claudea Stop hook that reports docs needing review

memoria integrations github installa GitHub check that fails while a doc is pending

Each one can be removed again, and none of them reviews a doc for you. memoria onboard agent and memoria onboard ci walk through them.

Start with one README