Home / The second brain

File-based memory: basic structure and disciplines

Claude Code's memory lives in a folder of markdown files, one fact per file classified by a type field with four values, and a note that carries a single idea linked to at least one other stays findable within seconds rather than after a full reread.

Claude Code can keep its own memory from one session to the next, in a folder of plain text files in markdown format, a simple format where a few symbols are enough to mark headings and lists. A memory file carries a single fact, and its header, called the frontmatter, carries a field named type that takes one of four possible values, listed below exactly as the software writes them. A separate memory folder exists for each project opened with Claude Code, and it always starts with an index file that lists in one line each of the memories already written.

The frontmatter, the header that classifies each file

The frontmatter is the block of information placed between two lines of dashes, right at the start of the file, before the text that is actually read. It tells no story, it only serves to file the note. A minimal memory file looks like this:

---
type: project
---
The shortcut to reopen the last closed session stays active for seven days.

The four values of the type field: user, feedback, project, reference

The project value links a note to the work under way on a specific repository. A note of type feedback documents, by contrast, an observed piece of feedback about a way of working, and a note of the fourth type listed above signals a stable fact, to be consulted rather than followed to the letter.

A note that carries a single idea, linked to another

The type field is used to classify what Claude records in the frontmatter, but the discipline that makes a memory folder genuinely useful depends entirely on the person writing it. A file that mixes two distinct facts becomes harder to find the day only one of the two still matters. An isolated note, with no link at all to another note, stays invisible until someone thinks to search for its exact title.

Linking a note to at least one other, even by a simple sentence that mentions it, builds a network that can be navigated rather than a pile that can only be dug through from top to bottom. This discipline appears in no rule imposed by the type field: nothing stops you writing a note of type project that mixes three subjects with no link to anything else. It nonetheless remains the difference between a folder that can be consulted in a few seconds and a folder that has to be read in full to find a single fact, a point developed in querying a graph rather than rereading everything, the third lesson of this module.

This same discipline also explains why a content map, a way of linking several notes together, comes into its own once several memory files have accumulated, a subject developed in wikilinks, content maps and memory types.