agentleFS
illescasDanielillescasDaniel/memory-bank/skills/memory-bank/SKILL.md

memory-bank

Skill0 starsChanged 24 days agoMITView on GitHub

Keep a git-tracked markdown memory bank (memory/ folder) so the agent resumes work across sessions. Use at session start, when a task finishes or a blocker appears, when a tool or documentation problem needs logging, when a significant technical decision is made, before ending a session with unfinished work, and when asked to set up or reset the memory bank for a project or branch.

8 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 5 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 8 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

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

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

    Create missing files in memory/ from the templates/ folder next to this SKILL.md, including friction/README.md.

    line 23
  2. Distinctive:

    Do not rewrite these files on every turn.

    line 42
  3. Very specific:

    Commit memory updates at milestones, with the feature commit or in a memory: commit.

    line 58
  4. Distinctive:

    Never track per-developer local chores (worktree cleanup, local setup) here: they only create merge noise.

    line 59
  5. Distinctive:

    When the user starts a new branch or worktree and asks to initialise memory:

    line 64
  6. Distinctive:

    Commit the initialisation in the branch's first commit.

    line 70
  7. Distinctive:

    If the project also has a semantic or long-term memory tool (for example jev-mem), keep the two from overlapping:

    line 74

“Common” is measured: kept by at least 6 in 10 of the 8 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

Memory bank

Project state lives in plain markdown files in memory/, tracked in git. Because the folder is tracked, every branch and worktree carries its own version: context follows the branch, shows up in PR diffs, and needs no service.

Files

FileRoleRead at session start?
memory/progress.mdMacro checklist: what is done, what is open, known bugs.yes
memory/activeContext.mdScratchpad: current focus, blockers, files touched, the exact next step.yes
memory/decisions.mdAppend-only log of significant technical decisions and why (newest first).no, search it when needed
memory/archive.mdFinished history moved out of the two files above.no
memory/friction/Maintenance log of tool/doc/workflow problems to fix later; separate from project memory.no

Setup and missing files

Create missing files in memory/ from the templates/ folder next to this SKILL.md, including friction/README.md. Check individual files even when memory/ already exists (for example, an installer may have created only friction/). Preserve every existing file; never replace notes with templates. Fill the "Branch" and "Current focus" lines of a newly created activeContext.md from what you know, and tell the user what you created. If you cannot locate templates/, create missing files with the headings described in this document.

Session start

  1. Set up any missing memory-bank files as above, then read memory/activeContext.md.
  2. Read memory/progress.md.
  3. Continue from "Next steps". If they look stale against the code or git log, say so and ask before acting on them.

During work: update only on these triggers

  • progress.md: a task is completed ([ ] to [x]), or you discover a new task or bug.
  • activeContext.md: focus changes, you hit a blocker, or you conclude a step (touched files, state, exact next step).
  • decisions.md: a significant technical, structural or dependency choice. Append at the top: context, decision, rationale.
  • friction/: a tool errors, a doc misleads, or you need a workaround. Add one small dated file using memory/friction/README.md and keep working. This is a maintenance backlog, not session context; also record current blockers in activeContext.md.

Do not rewrite these files on every turn. Small, trigger-based edits keep the diffs reviewable.

Keeping it lean

activeContext.md is a scratchpad, not a log: roughly the current thread, its blockers and next steps, plus a short "just changed" list. When a thread concludes, move it to archive.md under a dated heading. progress.md lists open items plus the in-flight feature's Done list; move a finished feature's Done list to archive.md once nothing in it is likely to be referenced again. Never delete from decisions.md or archive.md.

Hand-off (before finishing a turn that leaves work unfinished)

  1. Checkbox state in progress.md is accurate.
  2. activeContext.md names the exact next step, so a fresh session can start without asking.

Version control

  • Commit memory updates at milestones, with the feature commit or in a memory: commit. Do not leave the tree permanently dirty.
  • Never track per-developer local chores (worktree cleanup, local setup) here: they only create merge noise.
  • On merge, keep the feature branch's progress.md and activeContext.md; merge decisions.md by keeping both sides' entries, newest first.

New feature branch

When the user starts a new branch or worktree and asks to initialise memory:

  1. progress.md: new section for the feature, empty Done list, carry forward only still-relevant Open items.
  2. activeContext.md: rewrite with the branch name, the new focus, no blockers, only relevant next steps.
  3. decisions.md: leave untouched.

Commit the initialisation in the branch's first commit.

Alongside a semantic memory (optional)

If the project also has a semantic or long-term memory tool (for example jev-mem), keep the two from overlapping:

  • Current state (focus, in-progress work, blockers, next steps) belongs here, never in the other tool, where it would go stale silently.
  • Dated facts that stay true (decisions with reasons, bug causes, gotchas, user preferences) belong in the semantic memory. A significant decision gets both a decisions.md entry and a one-fact note there.
  • Rules the agent must always follow belong in AGENTS.md / CLAUDE.md.

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.