memory-init

Run once per project. Gives checkpoint somewhere to read and write.

If you use Claude Code, this is not its built-in /init. That one writes a CLAUDE.md describing your codebase, and it is worth running. This one creates the files that carry state between sessions, and it leaves any existing instruction file standing.

The three files

All under memory/. Each has one job, and the split is what keeps the first one short enough to be read every session.

Steps

1. Survey first. Read the instruction file your agent reads, if the project has one: AGENTS.md, CLAUDE.md, or your agent's equivalent. List memory/. Done when you can name which of the four target files already exist.
2. Back up anything that exists. Copy each existing target to <filename>.bak beside it. A file with no .bak does not get written to. Done when every file you intend to modify has a backup.
3. Learn the project before writing about it. Read the README, the build and test config, the entry point, and the directory layout. Run the test command if there is one, and record whether it passed. Done when you can state in your own words what the project does, how it is run, and how it is tested.

4. Write PROJECT.md. These sections, in this order:

   • What this is (one paragraph)
   • Run and test (exact commands, copy-pasteable)
   • Where things live (only the paths that matter, one line each)
   • State (what works, what is in flight)
   • Traps (anything that looks wrong but is deliberate, and what breaks if someone "fixes" it)

   A section with nothing real in it gets the words none yet. Done when every claim in the file came from a file you read or a command you ran.

5. Seed DECISIONS.md and SESSIONS.md. Each gets its heading and one real first entry: for decisions, any choice already visible in the project's config or docs; for sessions, today's setup run. The checkpoint skill owns the session entry shape and repeats it there. Done when both files exist and neither first entry is a placeholder.

6. Add the boot block to your agent's instruction file. Write it to the file your agent actually reads at the start of a session:

   • If the project already has AGENTS.md, use that.
   • Otherwise, if it already has CLAUDE.md, use that.
   • If it has neither, create the one your own agent reads. Claude Code reads CLAUDE.md; several other agents read AGENTS.md. Pick the correct one for yourself rather than guessing, and say in your report which file you chose and why.

   Append the Memory section using the copy below. Keep everything already in the file. Where a rule there clashes with the block, keep both and name the two lines that disagree. Done when the block is present in the right file and nothing that was in it is gone.

7. Prove it works. Re-read the three files as though you had never seen this project, and state the brief they give on their own. Done when that brief answers what this is, how to run it, and what is next, using nothing you remember from this session.

The boot block

## Memory

Continuity for this project lives in `memory/`. Read `PROJECT.md` and
`DECISIONS.md` at the start of every session, before doing any work.

- `PROJECT.md` is the current state. Where it disagrees with the code, the code
  wins, and the file gets fixed in the same pass.
- `DECISIONS.md` holds settled choices. A settled choice is reopened by asking,
  not by quietly working around it.
- `SESSIONS.md` is the log of what happened.

Run `checkpoint` when something a future session would need to know becomes
true.

A note on what this pack does not include

This is the free two-skill pack. Session start-up is manual here: you read the three files yourself, or tell the session to read them, which is what the boot block above instructs.

The full stack adds four more skills that automate the parts this pack leaves to you: cold-booting a session from the memory files, saving state ahead of a context compaction, locking a decision with its reasoning, and removing stale lines with your approval. Details at https://getclearstack.carrd.co

Nothing here is time limited or crippled. These two skills do the whole job they describe.