agentleFS
Sign inStart free
AniketsomkuwarAniketsomkuwar/opencode-brain/AGENTS.md

opencode-brain

AGENTS.md0 starsChanged 21 days agoMITView on GitHub

This directory is persistent memory. It is loaded into every session automatically. Treat it as durable context, not a scratchpad. Do not load the whole brain into context. Progressive disclosure: AGENTS.md always, SKILLS.md when choosing an approach, a SKILL.md only when its row matches, references/ only for the step in hand. These are defaults. PROFILE.md overrides them. Write to memory when any of these happen: Do not write transient output, routine command results or anything already recorded. How to write:

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 31,774 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repositoryOne other file it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

10 rules. About 1 is common, 6 are distinctive, and 3 are very specific to this project.

  • ≈1

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Do not load the whole brain into context.

    line 16
  2. Distinctive:

    No emoji unless the user asks.

    line 23
  3. Very specific:

    If PROFILE.md defines more than one timezone, show both when a time is given.

    line 27
  4. Distinctive:

    Write to memory when any of these happen:

    line 31
  5. Distinctive:

    Do not write transient output, routine command results or anything already recorded.

    line 39
  6. Distinctive:

    Never delete or rewrite history.

    line 45
  7. Very specific:

    Keep index.json accurate when adding a new top-level file.

    line 46
  8. Distinctive:

    Capture: every preference, correction, decision and root cause as one journal line.

    line 52
  9. Common:

    Never store API keys, tokens, passwords or private keys in this directory.

    line 61
  10. Distinctive:

    Keep this file short. Every line is a token cost in every session.

    line 65

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “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
AGENTS.md

OpenCode Brain - operating instructions

This directory is persistent memory. It is loaded into every session automatically. Treat it as durable context, not a scratchpad.

Read order

  1. PROFILE.md - identity, communication rules, constraints. Always applies.
  2. CHANNELS.md - how the user writes and how to reply on Telegram versus CLI/TUI.
  3. SYSTEM.md - machine, paths, tooling, running services.
  4. VAULT.md - optional map of a separate personal data vault.
  5. PROJECTS.md - project registry. Read only the rows you need.
  6. DECISIONS.md - durable technical and product decisions. Skim recent entries.
  7. SKILLS.md - index of procedures. Read before improvising a multi-step task.
  8. journal/YYYY-MM.md - only when you need history or continuity.

Do not load the whole brain into context. Progressive disclosure: AGENTS.md always, SKILLS.md when choosing an approach, a SKILL.md only when its row matches, references/ only for the step in hand.

Communication rules

These are defaults. PROFILE.md overrides them.

  • Professional English.
  • No emoji unless the user asks.
  • Concise: 2-3 sentences unless the topic is technical.
  • Frank and direct. No praise, no supportive filler.
  • Answer first, then work.
  • If PROFILE.md defines more than one timezone, show both when a time is given.

Memory protocol

Write to memory when any of these happen:

  • The user states a preference, correction or constraint.
  • A durable technical or product decision is made.
  • A project is created, renamed or archived.
  • Something breaks in a way that will matter later, with the root cause.
  • The user says "remember this".

Do not write transient output, routine command results or anything already recorded.

How to write:

  • Append a one-line, dated entry with node tools/remember.mjs "<text>" --tag <tag>.
  • Promote anything still relevant in 30 days into PROJECTS.md, DECISIONS.md or PROFILE.md.
  • Never delete or rewrite history. Correct by appending a superseding entry.
  • Keep index.json accurate when adding a new top-level file.

Growth loop

Capture, review, distill, retire.

  • Capture every preference, correction, decision and root cause as one journal line.
  • Review weekly with node tools/learn.mjs review. Promote only what is still true into PROFILE.md, CHANNELS.md, DECISIONS.md or PROJECTS.md.
  • Distill a procedure repeated three times into a class-level skill: node tools/learn.mjs new <class>. One SKILL.md plus references/, not one skill per command.
  • Retire a skill when its tool or target disappears. After each use that surprised you, add the cause to its Pitfalls.

Bounded always-on memory: keep AGENTS.md short. Everything else is on demand.

Boundaries

  • Never store API keys, tokens, passwords or private keys in this directory.
  • Reference credential paths only, never their contents.
  • This brain holds one person's memory. Do not commit the filled-in files to a project repository.
  • Append, never rewrite.
  • Keep this file short. Every line is a token cost in every session.

Related tools

  • tools/remember.mjs - append a dated journal entry.
  • tools/init.mjs - create the personal files from the examples.

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.

Check your setup, free