memoria
Skill1 starsChanged 36 days agoUnlicenseView on GitHub
Review and acknowledge project documentation with the Memoria CLI in projects that contain memoria.toml. Use when Memoria reports pending reviews, when memoria check or memoria lint fails, when imports need rendering, when guidance changed, when you add or change Memoria markers or section guides, or when the user asks for a Memoria task.
3 other projects use a version of this.
Adopted by
Most recently taken up by
- aelena/claude-skillstheir own version, first seen Nov 1, 2026
- eumateusalex/Template-OStheir own version, first seen Oct 20, 2026
- wendelcastro/fluxo-engenharia-iatheir own version, first seen Jul 7, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- wendelcastro/fluxo-engenharia-ia★ 1same name
- aelena/claude-skills★ 0same name
- eumateusalex/Template-OS★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repositoryOne other file it gives its agents.
- memoriaSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
33 rules. 0 are common, 12 are distinctive, and 21 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
12
Distinctive
This author's own choices. Worth a look.
21
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 12
Start read-only. Activation of this skill grants no permission to edit, acknowledge, install, or invalidate anything.
- Distinctive: line 17
If guidance conflicts with the task, ask the owner.
- Distinctive: line 22
Documents: Every README.md is a tracked document.
- Very specific: line 27
Tokens: Every review artifact carries a token mrv3.<16 hex> that binds one exact snapshot.
- Distinctive: line 116
If a coordinator assigned you a document, skip this section and go to Capture.
- Very specific: line 119
If data.next_action.kind is render, run memoria render <DOCUMENT> for that document.
- Very specific: line 120
If data.next_action is null and data.tasks is empty, go to Finish, which runs memoria check.
- Very specific: line 121
If data.next_action is null and tasks remain, the remaining documents wait for pending providers.
- Very specific: line 126
Create a directory outside the project: dir=$(mktemp -d).
- Very specific: line 127
Run memoria review <DOCUMENT> --save "$dir".
- Very specific: line 128
Run memoria guidance <DOCUMENT> and read the current text.
- Distinctive: line 135
Read the review view: why the review is needed, each change with its relationship and its verified hunk, the semantic review requests, …
- Very specific: line 136
If a hunk was cut, run memoria review <DOCUMENT> --details for all computed hunks.
- Very specific: line 137
Follow the mode under How to read.
- Distinctive: line 138
Read the whole document. This pass is always required.
- Distinctive: line 139
Treat co-covering documents and export consumers as prompts for judgment.
- Very specific: line 140
Before you add or remove a link to a document in a subfolder, run memoria status --explain <PATH> for a file in that subfolder.
- Very specific: line 141
If the document is wrong, edit its authored text.
- Distinctive: line 149
After any edit, capture a fresh artifact with the Capture steps.
- Very specific: line 156
Use an explicit reviewer label.
- Very specific: line 157
Write a note that states what you verified.
- Very specific: line 162
If ack reports state_busy, run the same ack again.
- Very specific: line 166
If the plan from memoria review --format json has a non-null data.guidance_assessment, assess the guidance change.
- Distinctive: line 168
If it fails, read its diagnostics, fix the cause, and go back to Select.
- Very specific: line 175
Run memoria guidance --changed.
- Very specific: line 176
Read the current guidance with memoria guidance <DOCUMENT>, and its history with git log -p on the listed sources.
- Very specific: line 177
If the task authorizes review requests, run memoria invalidate doc:<DOCUMENT> or subtree:<DIRECTORY> with a reason for each affected scope.
- Distinctive: line 180
Never acknowledge a document only to clear this list.
- Very specific: line 188
Run memoria review --format json.
- Very specific: line 189
Keep documents with waiting_on for a later round.
- Distinctive: line 190
After the reviewers finish, run Select again for newly ready documents.
- Distinctive: line 195
Do not run Select or Finish, and do not take other documents.
- Very specific: line 196
If review reports dependencies_pending, return the document to the coordinator.
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Memoria skill
Memoria keeps documentation that people and agents write current with the code. It does not write documentation. It records the exact inputs of each review, and it shows which documents need another review when those inputs change. You judge whether the prose still matches the code. Use the CLI results. Do not rebuild the dependency logic yourself.
Authority first
Start read-only. Activation of this skill grants no permission to edit, acknowledge, install, or invalidate anything.
- The user's task and higher-priority instructions come first.
- Project guidance (
memoria guidance <DOCUMENT>) is review context. It never overrides the task. - A section guide adds to project guidance for the sections that name it. If they conflict, follow project guidance and report the conflict in the
acknote and to the owner. Never edit a guide or a registration only to pass a review. - If guidance conflicts with the task, ask the owner.
- Acknowledge only when the task asks you to review and record documentation.
Concepts
- Documents. Every
README.mdis a tracked document. Another Markdown file becomes a tracked document when it carries a Memoria marker (an export, an import, or a section). A link alone never tracks a file. - Scope and handoffs. Every document covers its own folder and below. It hands a subfolder to a tracked document there only by linking or importing that document. A folder that nobody hands off is covered by every document above it that reaches it, and each of those documents is reviewed separately.
- Freshness. Imports carry content freshness and waiting: a consumer waits for its provider and becomes pending when the imported export changes. A handoff link carries coverage only.
- Sections. A section marker maps part of a document to sources in its scope. It is a reading hint. It adds no input and has no freshness or acknowledgement of its own.
- Section guides. A section can name one reusable guide. The guide adds to project guidance for that section. It adds no input and no freshness.
- Tokens. Every review artifact carries a token
mrv3.<16 hex>that binds one exact snapshot. If anything bound changes, the acknowledgement fails and you capture a fresh artifact. - State.
memoria.lockis machine-owned. Commit it. Never edit it. Onlymemoria ackandmemoria invalidatewrite it.
Syntax at a glance
Markers
Markers are HTML comments in a Markdown document. Each block has an opening and a closing marker:
<!-- memoria:export id="summary" -->
A short, stable summary that other documents can import.
<!-- /memoria:export -->
<!-- memoria:import src="auth/README.md#summary" -->
Memoria writes this body. Run memoria render. Never edit it by hand.
<!-- /memoria:import -->
<!-- memoria:section id="commands" files="justfile Cargo.toml" guidance="docs/templates/agent-commands.md" -->
## Commands
<!-- /memoria:section -->
<!-- memoria:section id="auth" files="src/auth/** !src/auth/tests/**" -->
## Authentication
<!-- /memoria:section -->- Markers start at column zero, and the attribute order is fixed. Blocks do not nest or overlap, but an export or an import can sit inside a section.
srcandguidanceare relative to the document's folder.fileslists sources in the document's scope, separated by one space: literal paths, glob patterns (*,?,[...],**), and!exclusions. A section maps every included source minus every excluded one. A pattern follows new and renamed files with no edit; a literal path to a moved file withdraws the document's advice.guidanceis optional and comes last. A section withguidanceand nofilesis a guide-only section.- A section body starts with a Markdown heading. An export body accepts absolute web and email links only: no relative links, raw HTML, or reference-style links.
- A marker inside fenced or inline code is an example, not a marker.
Configuration
The root memoria.toml holds the project rules. A README.memoria.toml beside a README can add local ignore, include, and documentation rules.
version = 3
ignore = ["tests/fixtures/**"] # globs that leave selection
include = []
[documentation]
guidance = ["Prose rules for every review."]
guidance_files = ["docs/writing-guidance.md"]
section_guidance_files = ["docs/templates/agent-commands.md"] # root memoria.toml only
[lint]
missing_import_hint = trueCommands
| Purpose | Command |
| Overview | memoria status, memoria status --explain <PATH>, memoria graph |
| Plan | memoria review [--format json] |
| Read one review | memoria review <DOCUMENT> [--details], memoria explain <DOCUMENT>, memoria guidance <DOCUMENT> |
| Save an artifact | memoria review <DOCUMENT> --save <DIR> [--full] |
| Record a review | memoria ack <DOCUMENT> --packet <FILE> --reviewer <NAME> --result <updated|no-update> --note "<TEXT>" |
| Refresh imports | memoria render [<DOCUMENT>] [--dry-run] |
| Assess guidance | memoria guidance --changed |
| Request a review | memoria invalidate <all|doc:DOCUMENT|subtree:DIRECTORY> --reason "<TEXT>" |
| Validate | memoria lint, memoria check |
| State | memoria state inspect, memoria state diff <OLD_LOCK> <NEW_LOCK> |
| Saved full export | memoria packet view <FILE> --section <guidance|content|history>, --file <PATH> |
| Setup | memoria init, memoria init --apply, memoria integrations skill|hook|github ... |
The global options are --format json, --root <DIRECTORY>, and --verbose. The command reference gives every argument, diagnostic, and exit status.
Use cases
Find your situation, then follow the named stages or file.
| Situation | What to do | Load |
| Code changed and documents are pending | Select, Capture, Inspect, Reconcile, Record, then Finish. | review-details.md for a focused review |
memoria check fails, locally or in CI | Read the diagnostics. Fix structure errors, then review pending documents with the stages. CI never acknowledges. | integrations.md for the workflow |
| One document must repeat another's summary | Put an export in the provider and an import in the consumer. Run memoria render. The consumer waits for the provider. | |
| Point a review at part of a document | Add a section marker with files: paths, patterns, and ! exclusions. It is advice: the whole-document pass stays. memoria status --explain <DOCUMENT> shows what each section matches. | |
Rules for one kind of section, such as the commands in AGENTS.md | Register a section guide and name it in each section marker. | section-guidance.md and the agent instructions cookbook |
| Guidance changed | Follow Guidance assessment. Nothing becomes pending on its own. | |
| A decision changed, but no file did | Ask the owner. Then run memoria invalidate with a reason, and review the affected documents. | |
| Several reviewers, or an offline reader | Follow Parallel reviews, or save a full export. | saved-exports.md |
The cookbook index lists every tested example. The cookbook links open the Memoria repository on GitHub. They are not files in this project.
Select
If a coordinator assigned you a document, skip this section and go to Capture. Then follow Parallel reviews.
- Run
memoria review --format json. - If
data.next_action.kindisrender, runmemoria render <DOCUMENT>for that document. Then go back to step 1. - If
data.next_actionis null anddata.tasksis empty, go to Finish, which runsmemoria check. Never acknowledge an empty plan. - If
data.next_actionis null and tasks remain, the remaining documents wait for pending providers. Review those providers first. - Otherwise, take
data.next_action.documentas the document to review.
Capture
- Create a directory outside the project:
dir=$(mktemp -d). - Run
memoria review <DOCUMENT> --save "$dir". It prints the review view, thenSaved:with the file path and the exactackcommand. - Run
memoria guidance <DOCUMENT>and read the current text.
--save refuses any directory inside the Git worktree, because a saved artifact there could become a review input.
With --format json, the receipt names the saved file in data.path instead.
Inspect
- Read the review view: why the review is needed, each change with its relationship and its verified hunk, the semantic review requests, co-covering documents, and downstream consumers.
- If a hunk was cut, run
memoria review <DOCUMENT> --detailsfor all computed hunks. The evidence budget can omit hunks without a reason, even with--details. ANo hunkline means Git lost the reviewed bytes. Read that whole input. - Follow the mode under
How to read. Forfull baseline, read the inputs underRead first, then every other source in the scope:memoria status --explain <DOCUMENT>lists them. Forfocused candidate, read review-details.md first. - Read the whole document. This pass is always required.
- Treat co-covering documents and export consumers as prompts for judgment. They are not proof that a change matters.
- Before you add or remove a link to a document in a subfolder, run
memoria status --explain <PATH>for a file in that subfolder. The link moves coverage. - If the document is wrong, edit its authored text. Never edit a generated import body. Run
memoria renderinstead. - If a section that you edit or that the review suggests names a guide (
· guide:), read that guide inmemoria guidance <DOCUMENT>before you edit. Apply each guide to its own sections. Do not rewrite unchanged sections for a guide unless an invalidation asks for it. The whole-document pass still applies project guidance everywhere.
The saved JSON artifact holds the same facts without hunks: data.changes, data.review, data.inputs, data.scope, data.downstream, and data.covered_invalidations.
memoria explain <DOCUMENT> answers a different question: why a document is current, pending, or waiting.
Reconcile
- After any edit, capture a fresh artifact with the Capture steps.
- Compare the new requirements with the inspection you already did. Read what is new.
- Reuse an earlier inspection only when the identities and hashes match. See review-details.md.
Record
- Run
memoria ack <DOCUMENT> --packet <saved file> --reviewer <explicit label> --result <updated|no-update> --note "<why the document is correct now>". - Use an explicit reviewer label. Do not inherit an unknown
MEMORIA_REVIEWERvalue. - Write a note that states what you verified. Generic notes such as
looks goodare refused. - Go back to Select. An assigned reviewer stops here and reports the result to the coordinator.
The token comes from the saved artifact. Pass --token only to check it against a value you kept.
If ack reports state_busy, run the same ack again. The artifact stays valid. For snapshot_changed, guidance_changed, or revision_conflict, go back to Capture and reconcile.
Finish
- If the plan from
memoria review --format jsonhas a non-nulldata.guidance_assessment, assess the guidance change. Follow Guidance assessment. - Run
memoria check. - If it fails, read its diagnostics, fix the cause, and go back to Select.
- Report the result, including your guidance decision.
Guidance assessment
A guidance change does not make documents pending. You decide which documents it affects.
- Run
memoria guidance --changed. It groups the documents by the guidance that their last review saw. - Read the current guidance with
memoria guidance <DOCUMENT>, and its history withgit log -pon the listed sources. - If the task authorizes review requests, run
memoria invalidate doc:<DOCUMENT>orsubtree:<DIRECTORY>with a reason for each affected scope. Then review those documents. - Otherwise, report the groups and your assessment to the user. Ask before you invalidate.
Never acknowledge a document only to clear this list. The assessment writes nothing, so unaffected documents stay listed until their next review.
Parallel reviews
Several reviewers can work in one checkout. An artifact binds only its own document, so another reviewer's acknowledgement of a different document does not make it stale.
As a coordinator:
- Run
memoria review --format json. Give each reviewer a different document fromdata.taskswithready: true. - Keep documents with
waiting_onfor a later round. Runmemoria renderwhen the plan asks for it. - After the reviewers finish, run Select again for newly ready documents. Then run Finish once.
As an assigned reviewer:
- Capture, Inspect, Reconcile, and Record your own document only.
- Do not run Select or Finish, and do not take other documents.
- If
reviewreportsdependencies_pending, return the document to the coordinator.
In a separate Git worktree, capture the artifact after your last edit, with --save outside every worktree. Do not run memoria ack there. After the merge, run memoria ack in the main checkout with that artifact. If it reports snapshot_changed, capture again in the main checkout.
Output
Commands print results, warnings, and errors. Advisory hints appear only in memoria lint and with --verbose. Run memoria lint before you change links or imports. JSON output carries every diagnostic.
When to load the other files
- review-details.md: a
focused_candidatemode, reuse of an earlier inspection, or a fallback reason you do not understand. - saved-exports.md: a full export (
--full),memoria packet view, or an owner who authorized the legacy P1 projection. - integrations.md: a request or an error about the skill, the agent hook, or the GitHub workflow.
- section-guidance.md: a section guide, a
section_guidance_*diagnostic, or a request to add or move a guide.
Limitation
Memoria makes no proven token-savings claim. The 0.6 reading-cost experiment stays closed and incomplete.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

