Repository navigation
Reference configuration
A complete, working configuration for using atlas as Claude Code's memory: recall on every prompt and at every
subagent start, a versioned copy of the memory folder, a generated MEMORY.md, compaction and agent limits. It
is the configuration atlas is developed with, with names, paths and personal values replaced by placeholders.
Start from it when Claude cannot work out how to use atlas as its memory, or when memory looks dead.
The files are in the repository under examples/reference/.
A test loads them through atlas's own configuration parser with the placeholders filled in, so every key in them
is one the current release accepts. Every key is described in Configuration reference.
| file | goes to | notes |
|---|---|---|
atlas.json |
atlas's configuration file (ATLAS_CONFIG, --config, or the user configuration folder; see Install and setup) |
fill in the placeholders; keep the models block of the configuration your first run wrote |
atlas.project.json |
the workspace root, where projects[].file names it |
one entry per repository in the workspace (Projects and multi-repo) |
.claude/settings.json |
<WORKSPACE>/.claude/settings.json |
lets the atlas MCP tools run without a permission prompt |
Install atlas as the Claude Code plugin (Install and setup), not as a bare binary. The plugin brings the
mcp_tool hooks (hooks/hooks.json) and the atlas and orchestrate skills. Recall reaches a session only
through those hooks: UserPromptSubmit in the main session, SubagentStart for subagents
(Memory store and hooks). A command hook (atlas --hook) cannot give a subagent its lane recall; use the
plugin's mcp_tool hooks.
atlas does not replace Claude Code's memory folder. Claude Code still writes the memory files; atlas indexes
them, keeps every version in its store, recalls from them, and (with memory.tree) writes the MEMORY.md that
Claude Code loads.
Four pieces must line up. With any one missing, memory looks dead.
-
A source on the memory folder. In
projects[].sources, the entry namedmemory:-
root: Claude Code's memory folder for the workspace,~/.claude/projects/<folder>/memory, where<folder>is the workspace's absolute path with every character that is not an ASCII letter or digit turned into-(separators,:,.,_and spaces alike):/home/me/workbecomes-home-me-work, andC:\work\my_appbecomesC--work-my-app. Write the absolute path. List~/.claude/projects/to get the folder name right: a wrong root is the most common failure, and nothing reports it. -
names_kind: "memory", so each memory's file name becomes an identifier (Identifiers and freshness). -
id_keys: ["name"], since a memory's id is its frontmattername:. -
exclude: ["index/*"], so the hub files the tree writes are not read back as memories.
-
-
An export with the same name.
memory.exportsholds{"name": "memory", "shape": "memory", ...}. An export whose name is also a configured source is synced from it: every rescan, and everyrecall, re-imports a changed file, and a changed memory file becomes a new version of the same key (recall {key, history}), so history is kept (Memory store and hooks). -
The tree, optional.
memory.treemakes atlas writeMEMORY.mdand the hub files (inmemory.tree.hub_dir,indexby default) into the memory folder, grouped bybranches[].words, with pinned memories in the root. Back upMEMORY.mdfirst; the first rebuild also saves a hand-written root toindex/MEMORY.md.before-tree. Leavememory.treeout to keep a hand-writtenMEMORY.md(Memory tree). -
Rules on.
atlas settings set memory-rules true(the file already has"memory": {"rules": true}). It is experimental and off by default. With it on, atlas also reads the project's Claude Code memory folder and the firstCLAUDE.mdat the working folder or a project root, and a query that hits a replaced ruling answers with the ruling that replaced it (Memory and rule files).
Then check it:
atlas --config <atlas.json> --rescan # index and sync; prints stats, and what each sync did under memory
atlas --config <atlas.json> --memory-check # hash chains, exports on disk, the round trip
atlas doctor # the atlas hooks in Claude Code's settings match the plugin'sIn a session, recall {query: "<words from a memory>"} should return that memory, and a prompt that uses a
memory's words should get a recall block from the hook. If the tool answers but no prompt ever gets a block, the
hooks are missing: run atlas doctor.
For the habits (recall before asking, journal and hand off to lanes), atlas settings rules-template <WORKSPACE>
offers a starter CLAUDE.md and .claude/atlas-rules.md, and writes nothing when the folder already has rules.
Do not add a Compact instructions block while compact.enabled is on: atlas's PreCompact hook already returns
that text (Memory and rule files).
| placeholder | meaning |
|---|---|
<ATLAS_HOME> |
the folder for atlas's state/ and exports/ (for example atlas's data folder) |
<WORKSPACE> |
the folder holding your repositories: the project root |
<CLAUDE_MEMORY_DIR> |
Claude Code's memory folder for the workspace, from step 1 above |
<project>, <Project>
|
your project's name |
<repo> |
a repository folder name in the workspace |
<repo folder, relative to the workspace> |
that repository's path in the project file |
<owner> |
the repository's owner on its Git host |
<one line: what this repo is> |
the repository's role, one line |
<Obsidian vault folder> |
a notes vault folder, if you keep one; else drop vaults
|
<one line: what memories on this branch are about> |
the branch's line in MEMORY.md
|
<keyword>, <prefix*>
|
words that file a memory on the branch; * matches any ending |
<your first name> |
in memory.tree.name_stop, lowercase: a word that never names a hub; in backlog.asker, as you write it: the name that leads your own asks |
- The project's own vaults, sources, identifier patterns and tree branches: each is one example. Keep the generic
branches (
atlas,workflow,machine,me) and add your project's own. -
memory.tree.pinsis empty: pins name your own memory slugs. -
semanticandcode.rust_analyzer: the defaults find the embedding model from themodelsblock and rust-analyzer onPATH. - Keys that point at tools on one machine only.
-
recall.*: floors calibrated on a long-running store. Start with them, and recalibrate on your own store if recall is too chatty or too quiet. -
orchestrate.resources: the example's{"gpu": 1, "compile": 1}are the defaults. Size them to your machine: setup writes 1 GPU slot and compile slots from the hardware threads (Configuration reference). -
recall.subagent_context: "binding"gives a subagent only the records its brief names and its lane's newest handoff and decisions. The default is"recall". -
orchestrate.kinds: at most 6 builders, 4 reviewers and 2 research agents at once; each is told to hand off from 285,000 context tokens (handoff), and past 500,000 (limit) every tool buthandoffis denied (Orchestration). -
cap: the kinds above hand off at their ownhandoff(285,000).cap.warn_tokens(450,000) andcap.block_tokens(500,000) apply to kinds without their ownhandoffandlimit, which are told to hand off at 450,000 and blocked at 500,000, and to the main session, whose compact point iscap.warn_tokenswhilecap.main_warn_tokensis 0.cap.main_session: falseturns off the main session's advice to ask for /compact.
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