agentleFS
invakid404invakid404/umbra/.agents/skills/memoria/SKILL.md

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

  • Other versions3 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 3

    1. wendelcastro/fluxo-engenharia-ia★ 1same name
    2. aelena/claude-skills★ 0same name
    3. 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.

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
  1. Distinctive:

    Start read-only. Activation of this skill grants no permission to edit, acknowledge, install, or invalidate anything.

    line 12
  2. Distinctive:

    If guidance conflicts with the task, ask the owner.

    line 17
  3. Distinctive:

    Documents: Every README.md is a tracked document.

    line 22
  4. Very specific:

    Tokens: Every review artifact carries a token mrv3.<16 hex> that binds one exact snapshot.

    line 27
  5. Distinctive:

    If a coordinator assigned you a document, skip this section and go to Capture.

    line 116
  6. Very specific:

    If data.next_action.kind is render, run memoria render <DOCUMENT> for that document.

    line 119
  7. Very specific:

    If data.next_action is null and data.tasks is empty, go to Finish, which runs memoria check.

    line 120
  8. Very specific:

    If data.next_action is null and tasks remain, the remaining documents wait for pending providers.

    line 121
  9. Very specific:

    Create a directory outside the project: dir=$(mktemp -d).

    line 126
  10. Very specific:

    Run memoria review <DOCUMENT> --save "$dir".

    line 127
  11. Very specific:

    Run memoria guidance <DOCUMENT> and read the current text.

    line 128
  12. Distinctive:

    Read the review view: why the review is needed, each change with its relationship and its verified hunk, the semantic review requests, …

    line 135
  13. Very specific:

    If a hunk was cut, run memoria review <DOCUMENT> --details for all computed hunks.

    line 136
  14. Very specific:

    Follow the mode under How to read.

    line 137
  15. Distinctive:

    Read the whole document. This pass is always required.

    line 138
  16. Distinctive:

    Treat co-covering documents and export consumers as prompts for judgment.

    line 139
  17. Very specific:

    Before you add or remove a link to a document in a subfolder, run memoria status --explain <PATH> for a file in that subfolder.

    line 140
  18. Very specific:

    If the document is wrong, edit its authored text.

    line 141
  19. Distinctive:

    After any edit, capture a fresh artifact with the Capture steps.

    line 149
  20. Very specific:

    Use an explicit reviewer label.

    line 156
  21. Very specific:

    Write a note that states what you verified.

    line 157
  22. Very specific:

    If ack reports state_busy, run the same ack again.

    line 162
  23. Very specific:

    If the plan from memoria review --format json has a non-null data.guidance_assessment, assess the guidance change.

    line 166
  24. Distinctive:

    If it fails, read its diagnostics, fix the cause, and go back to Select.

    line 168
  25. Very specific:

    Run memoria guidance --changed.

    line 175
  26. Very specific:

    Read the current guidance with memoria guidance <DOCUMENT>, and its history with git log -p on the listed sources.

    line 176
  27. Very specific:

    If the task authorizes review requests, run memoria invalidate doc:<DOCUMENT> or subtree:<DIRECTORY> with a reason for each affected scope.

    line 177
  28. Distinctive:

    Never acknowledge a document only to clear this list.

    line 180
  29. Very specific:

    Run memoria review --format json.

    line 188
  30. Very specific:

    Keep documents with waiting_on for a later round.

    line 189
  31. Distinctive:

    After the reviewers finish, run Select again for newly ready documents.

    line 190
  32. Distinctive:

    Do not run Select or Finish, and do not take other documents.

    line 195
  33. Very specific:

    If review reports dependencies_pending, return the document to the coordinator.

    line 196

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 ack note 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.md is 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.lock is machine-owned. Commit it. Never edit it. Only memoria ack and memoria invalidate write 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.
  • src and guidance are relative to the document's folder. files lists 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.
  • guidance is optional and comes last. A section with guidance and no files is 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 = true

Commands

PurposeCommand
Overviewmemoria status, memoria status --explain <PATH>, memoria graph
Planmemoria review [--format json]
Read one reviewmemoria review <DOCUMENT> [--details], memoria explain <DOCUMENT>, memoria guidance <DOCUMENT>
Save an artifactmemoria review <DOCUMENT> --save <DIR> [--full]
Record a reviewmemoria ack <DOCUMENT> --packet <FILE> --reviewer <NAME> --result <updated|no-update> --note "<TEXT>"
Refresh importsmemoria render [<DOCUMENT>] [--dry-run]
Assess guidancememoria guidance --changed
Request a reviewmemoria invalidate <all|doc:DOCUMENT|subtree:DIRECTORY> --reason "<TEXT>"
Validatememoria lint, memoria check
Statememoria state inspect, memoria state diff <OLD_LOCK> <NEW_LOCK>
Saved full exportmemoria packet view <FILE> --section <guidance|content|history>, --file <PATH>
Setupmemoria 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.

SituationWhat to doLoad
Code changed and documents are pendingSelect, Capture, Inspect, Reconcile, Record, then Finish.review-details.md for a focused review
memoria check fails, locally or in CIRead 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 summaryPut 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 documentAdd 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.mdRegister a section guide and name it in each section marker.section-guidance.md and the agent instructions cookbook
Guidance changedFollow Guidance assessment. Nothing becomes pending on its own.
A decision changed, but no file didAsk the owner. Then run memoria invalidate with a reason, and review the affected documents.
Several reviewers, or an offline readerFollow 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.

  1. Run memoria review --format json.
  2. If data.next_action.kind is render, run memoria render <DOCUMENT> for that document. Then go back to step 1.
  3. If data.next_action is null and data.tasks is empty, go to Finish, which runs memoria check. Never acknowledge an empty plan.
  4. If data.next_action is null and tasks remain, the remaining documents wait for pending providers. Review those providers first.
  5. Otherwise, take data.next_action.document as the document to review.

Capture

  1. Create a directory outside the project: dir=$(mktemp -d).
  2. Run memoria review <DOCUMENT> --save "$dir". It prints the review view, then Saved: with the file path and the exact ack command.
  3. 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

  1. 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.
  2. If a hunk was cut, run memoria review <DOCUMENT> --details for all computed hunks. The evidence budget can omit hunks without a reason, even with --details. A No hunk line means Git lost the reviewed bytes. Read that whole input.
  3. Follow the mode under How to read. For full baseline, read the inputs under Read first, then every other source in the scope: memoria status --explain <DOCUMENT> lists them. For focused candidate, read review-details.md first.
  4. Read the whole document. This pass is always required.
  5. Treat co-covering documents and export consumers as prompts for judgment. They are not proof that a change matters.
  6. 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.
  7. If the document is wrong, edit its authored text. Never edit a generated import body. Run memoria render instead.
  8. If a section that you edit or that the review suggests names a guide (· guide:), read that guide in memoria 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

  1. After any edit, capture a fresh artifact with the Capture steps.
  2. Compare the new requirements with the inspection you already did. Read what is new.
  3. Reuse an earlier inspection only when the identities and hashes match. See review-details.md.

Record

  1. Run memoria ack <DOCUMENT> --packet <saved file> --reviewer <explicit label> --result <updated|no-update> --note "<why the document is correct now>".
  2. Use an explicit reviewer label. Do not inherit an unknown MEMORIA_REVIEWER value.
  3. Write a note that states what you verified. Generic notes such as looks good are refused.
  4. 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

  1. If the plan from memoria review --format json has a non-null data.guidance_assessment, assess the guidance change. Follow Guidance assessment.
  2. Run memoria check.
  3. If it fails, read its diagnostics, fix the cause, and go back to Select.
  4. Report the result, including your guidance decision.

Guidance assessment

A guidance change does not make documents pending. You decide which documents it affects.

  1. Run memoria guidance --changed. It groups the documents by the guidance that their last review saw.
  2. Read the current guidance with memoria guidance <DOCUMENT>, and its history with git log -p on the listed sources.
  3. If the task authorizes review requests, run memoria invalidate doc:<DOCUMENT> or subtree:<DIRECTORY> with a reason for each affected scope. Then review those documents.
  4. 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:

  1. Run memoria review --format json. Give each reviewer a different document from data.tasks with ready: true.
  2. Keep documents with waiting_on for a later round. Run memoria render when the plan asks for it.
  3. After the reviewers finish, run Select again for newly ready documents. Then run Finish once.

As an assigned reviewer:

  1. Capture, Inspect, Reconcile, and Record your own document only.
  2. Do not run Select or Finish, and do not take other documents.
  3. If review reports dependencies_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_candidate mode, 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.