Repository navigation
Memory tree
Claude Code loads the memory folder's index (MEMORY.md) into every session, one line per memory, and cuts it at
200 lines. memory.tree turns that index into a tree that every memory stays reachable through
(src/memory/tree.rs):
-
The root (the index file) lists the top-level branches, then the pinned memories (their line, and their body
when it is at most
pin_body_charslong). It is always loaded, so it stays short. -
A branch is a hub file in
<memory folder>/<hub_dir>/that lists its memories, one line each (- slug: hook, or- [Title](../file.md) - hookwithline_format: link). A branch pasthub_maxlines is split by topic (k-means over the embedding model's vectors; hashed word vectors without a model) into hubs of abouthub_target, and then lists those. Every memory is at most three reads from the root: branch, hub, file. -
Branches are a fixed taxonomy in the configuration. A memory is placed once, when it first appears: by
branch: NAMEin its frontmatter, else by meaning and words together. Each branch scores it by the mean cosine with its five nearest members (its listed memories and those its words claim confidently) pluskeyword_weight(0.5) times its word score over the memory's best one (three points per branch word in its file name, one per word in its description, two when itsmetadata.typeis in the branch'stypes). On a hand-labelled set of 227 memories this placed all but 20, against 21 for words first and 36 for meaning alone; the rest were judgement calls, fixed withbranch:. A memory is pinned (in the root as well as its branch) bypinned: trueor by being named inpins. -
A memory's line is its title (from the line a writer added to the root, or the line its hub holds, or its
name) and its frontmatterdescriptionas the hook, cut at a whole word toline_maxwith no trailing punctuation or dangling word. A file with no description keeps its index line.
Rebuilds are stable, and the files are the tree's only state: a memory stays in the hub that lists it; a split
keeps the hub's file name for its largest part and names only the new parts; a part that falls under hub_min is
merged into its nearest sibling; no untouched hub is rewritten. A rebuild with nothing changed writes nothing, and
a new memory changes only the hubs on its path (usually one file). Every rescan that syncs the memory source
rebuilds the tree first, so a memory file that appears is filed on the next rescan; with the tree on, the sync
reads every memory's line from the hubs, so the store's titles and the export are unchanged by the switch.
"memory": {
"tree": {
"export": "memory",
"hub_dir": "index", "hub_max": 24, "hub_target": 20, "hub_min": 8, "line_max": 150, "pin_body_chars": 400,
"line_format": "slug", "name_stop": ["acme"], "keyword_weight": 0.5, "pins": ["deploy-credentials"],
"branches": [
{"name": "game-art", "title": "Game: art", "hook": "models, rigs, textures", "words": ["mesh*", "rig", "texture*"]},
{"name": "workflow", "title": "Workflow", "hook": "how agents work here", "words": ["agent*", "git"], "types": ["feedback"]}
]
}
}line_format is slug (the default: - slug: hook; the root says once that a memory is slug.md beside it and a
hub index/slug.md; shorter, and a memory's title is not shown) or link (- [Title](file.md) - hook, a Markdown
link the harness, Obsidian and people follow). Switching to slug gives every memory record one new
version on the next sync, as its title becomes - [slug](slug.md) - hook. name_stop adds lowercase words that
never name a hub (the user's or the project's name, say) to the built-in ones.
Every key is optional: export defaults to the first memory export, and without branches there is one
branch per memory type (rules, about the user, project facts, references). A branch name is its hub's file name
(lowercase letters, digits and -); a word ending in * matches any ending. Add "exclude": ["index/*"] to the
memory source so the hubs are not indexed as documents.
atlas --config C --memory-tree [DIR] # rebuild the tree in DIR (default: the memory source) and check it
atlas --config C --memory-tree [DIR] --check # write nothing; report what a rebuild would change, and check it
cargo xtask memory-tree-check --config C [--dir DIR] # the navigation and stability check, as CI would run itThe tree is opt-in: without a memory.tree block both commands stop with memory.tree is not configured and
exit 1, --check included. That is not a fault in the store.
The check walks the tree as a reader would: every memory file within three reads of the root, every pinned memory
in the root, no memory listed by two hubs (a pinned one also by the root), no generated hub that no link reaches,
no dangling link, no hub over hub_max; and a rebuild of what is on disk would write nothing. It prints the root's
size and the mean size of the root plus the hubs on the way to a memory.
Switching a live index over. The tree is written into the memory folder itself, the one Claude Code reads:
- Back up the folder (
MEMORY.mdat least). The first rebuild also saves a hand-written root to<hub_dir>/MEMORY.md.before-treebefore replacing it. - Add
pinned: trueto the frontmatter of each memory to pin, and list them inmemory.tree.pinstoo: a pin in either place counts, and--recall-checkreports (asmemory pindrift) a configured pin whose file has lostpinned: true, so a memory writer that rewrites the frontmatter is caught. - Add
memory.tree(and the source'sexclude) to the configuration, then runatlas --config C --memory-tree --checkto see the churn, andatlas --config C --memory-treeto build.cargo xtask memory-tree-check --config Cmust report no problems. - Restart the server (or let the next rescan do it): from then on every rescan rebuilds the tree.
To go back, remove memory.tree and restore MEMORY.md from the backup; the memory files are never touched.
With Projects and multi-repo, each project gets its own tree: its own memory.tree, else the user-level one
pointed at the project's memory export. The tree is built in the folder that export syncs from, so hubs live in
each project's own index/ folder and no two projects share one. A top-level memory.tree in a configuration with
projects names no export until a project resolves it. The user layer never gets a tree (a tree naming the user
export is refused); its records reach every project through the sync.
Pins have a scope. A pinned memory of the user layer (the user.memory folder, or one marked scope: user in
another project's folder) and the user-level memory.tree.pins are shared: every project's root lists them
under their own heading, with the file's path (* lines, which no tree reader takes for a memory of the folder).
A project's own pins stay in its own root. --recall-check reports a user-level pin found in neither the project
nor the user layer as memory pin drift.
A branch may name a repository (memory.tree.branches[].repo): a memory filed under it is tagged with that
repository for recall's boost, unless its frontmatter says repo: itself.
atlas is licensed under the Apache License 2.0. This wiki is generated from the repository's wiki/ folder at each release; edits made here are replaced by the next release. Report vulnerabilities privately, as SECURITY.md describes.
Getting started
What it saves
Reference
- Tools reference
- Code index
- Semantic search
- Identifiers and freshness
- Memory store and hooks
- Memory tree
- Memory and rule files
- Orchestration
- Discussions
- Project tracking
- Generated indices
- Cross-vault links
Internals