
atlas
Local project memory and token savings for Claude Code: an MCP server and hooks
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up atlas (claude-plugin project) into my current project. Found on https://claudeers.com/atlas-3 Repo: https://github.com/bloodfeast/atlas Homepage/docs: — Detected install method: claude-plugin → /plugin install atlas@bloodfeast/atlas Category: productivity. Platforms: cli, api. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: unknown; community-verified: false. Confirm the source before running anything.
⚠ Unverified / not recently updated — review before pasting a run-this config.
/plugin marketplace add bloodfeast/atlas /plugin install atlas@bloodfeast/atlas
git clone https://github.com/bloodfeast/atlas
// compatibility
| Platforms | cli, api |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | Apache-2.0 |
| Pricing | open-source |
| Language | Rust |
atlas
atlas makes long Claude Code sessions cheaper without changing how you work. It is a local MCP server and a
set of Claude Code hooks: large tool output stays on disk under a short handle and the model gets a digest,
code reads get exact item ranges instead of guessed windows, and memory (rules, decisions, journals,
handoffs) is recalled by relevance instead of loaded whole. It runs on your machine, has two direct
dependencies, SQLite (rusqlite) and an ed25519 signature check, plus the crates those two pull in (every one
is in Cargo.lock), and makes no network calls at query time.
You do not need Obsidian. A vault is any folder of Markdown files: atlas reads and writes the files
itself and never touches Obsidian's .obsidian settings folder. Obsidian is optional, as a reader for the
same folders. The one Obsidian-specific output is that make_link writes obsidian://open links between
vaults, which open only in Obsidian (elsewhere they are plain text); links within a vault are standard
[[wikilinks]].
Languages. Memory, recall and history, search over Markdown notes and sources, discussions, the work
queue, projects and multi-repo, and the hooks work whatever programming language a project uses, as does .proto indexing (rpc call
sites are found in any language's files). The code index (symbol, item ranges on reads, grep annotations)
covers Rust, WGSL, .proto, Go, TypeScript, JavaScript, C#, Python, Java and Kotlin (through scip-go,
scip-typescript, scip-dotnet, scip-python and scip-java when they are installed, or a prebuilt index.scip
from CI, WSL or Docker, else an owned scanner), and any language with a SCIP indexer from a .scip file.
Build and test digests recognise cargo test, nextest, go test (plain and -json), jest, vitest,
dotnet test, pytest, Maven and Gradle output, and other runners get the generic digest.
Ranked search (fts, sections, recall) splits words on spaces and punctuation, so text written without
spaces (Chinese, Japanese, Thai) is found with search in substring mode or grep instead.
What it saves
Every assistant turn re-reads the whole context, so a result that enters at turn 10 of a 300-turn session is processed 290 more times. Measured on real sessions:
| Without atlas | With atlas | |
|---|---|---|
| The tool list, loaded with every session | 47 tools, 5,930 tokens (v0.1) | 14 tools, 6,057 bytes (about 1,514 tokens at 4 bytes a token, measured at v0.6.0); the full reference is one fetched resource |
| A lookup (7,067 answers against 96 lookups done before atlas, measured at v0.6.0) | grep, then read the files | 6.4x fewer tokens in all (ratio of sums); 10.9x median per answer |
| Rules and memory at an agent's start (1,560 agents, measured at v0.6.0) | the whole rulebook read once per agent | the relevant records injected as pointers: 108.4x fewer tokens |
| Memory questions (100-question evaluation, at v0.6.0) | the whole rulebook loaded | 100/100 answered when the agent follows a result to its source, 99/100 reading only the first result; median 506 tokens each |
Shell reads are 36% of what a builder session processes and startup context another 35%; those are the
buckets atlas targets. atlas --token-report measures your own store the same way: it takes its baseline from
your Claude Code transcripts from before atlas, by itself in the background, and nets what atlas puts into
context (the tool list, hook injections, tool output) against what it saves. How each number was measured, and
how to measure your own sessions with cargo xtask attrib, is on Token savings and method.
Beyond the savings
- Orchestrated mode, asked at setup and never on by default: an
orchestrateskill teaches the main session to delegate through lanes and lean briefs, and the hooks cap how many agents of each kind run at once and hand an agent off at its context limit to a fresh one. atlas backloglists ruled work that fell out of the queue, aging items first, each with the rulings behind it. It only proposes; the queue's written order never changes.- Pull request reviews. In a
gh pr difffile read, context far from a change is one marker line thatrecall h:ID lines=A-Bopens, andatlas pr-events servewakes the session that waits on a review. - Long sections are searched whole. Semantic search embeds a long section as overlapping windows, so a question answered deep inside it finds it.
atlas worktreeskeeps an append-only ledger of which lane owns which worktree.- A fresh install teaches Claude atlas. The server's instructions and a bundled
atlasskill carry the habits (recall before asking, journal decisions, hand off before stopping), and atlas tells you at session start when an update arrives.
Install
atlas is a Claude Code plugin with prebuilt binaries for Windows x86_64, Linux x86_64 and aarch64, and macOS (Apple Silicon and Intel). In Claude Code:
/plugin marketplace add bloodfeast/atlas
/plugin install atlas@atlas
Restart Claude Code. On its first start atlas writes a starter configuration, atlas.json, in your
configuration folder (%APPDATA%\atlas, ~/Library/Application Support/atlas or ~/.config/atlas) and
downloads the embedding model (about 35 MB) in the background, checked against its pinned SHA-256. Until the
model is in place, search and recall are lexical. Updates are signed and on by default (atlas settings off update turns them off). Building from source, uninstalling and the data folders are on
Install and setup.
Quickstart (5 minutes)
-
Install the plugin (above) and restart Claude Code.
-
Optionally run the setup in the foreground to see each step; Claude can run it for you, since the plugin's
binfolder is on the Bash tool'sPATH(not on your own terminal's):atlas --setupRun by Claude, it has no terminal, so it lists its questions instead of asking them and records nothing; Claude puts them to you at the next session. In auto mode, Claude Code's classifier may block
atlas --setupandatlas settingscommands (with "No reason provided") until you tell Claude you allow them. -
Open a session in your project. Claude asks you about atlas: create a vault for this project at
<path>? yes / other folder / no, and, unlessatlas --setupasked already, whether to work in orchestrated mode (caps on how many agents run at once; no is fine; on yes the caps and compile slots start from this machine's cores, see the wiki's Orchestration page). It may also offer Claude Code settings. Say yes to the first: its Markdown becomes a searchable source, a folder holding code becomes a code root, and a new vault (an Obsidian-compatible folder) holds the project's notes and discussion threads.atlas settings undoreverts it all; it never deletes a note. A question you do not answer comes back at your next new session, until you answer it, and Claude may not always put it. A session with no user (claude -p, the SDK) asks nothing and counts as nothing asked, and atlas stays silent if it could not record your answer.atlas settings add-project .andatlas settings orchestratedo the same from a terminal. The vault question is per folder. -
Work as usual. Large Bash, Read and Grep results now arrive as digests with a handle; Claude pulls what it needs with
recall key=h:ID item=NAMEorfailures=true. Grep and Read results name the enclosing item and its line range. -
Ask Claude to remember a decision (
remember), and start the next session: relevant records are recalled on each prompt, within a 600-token budget (recall.budget_tokens). The recall defaults (600 tokens, a 0.53recall.cos_floor) were chosen by a sweep that measured off-topic records as well as on-topic recall. -
Optionally,
atlas settings offerproposes the Claude Code settings that cut cost (the 1-hour subagent cache, fewer goal check-ins). Nothing is written without a yes, andatlas settings undoreverts (it shows the change and asks first;--yeswithout a terminal). With the compaction features on (the default;"compact": {"enabled": false}oratlas settings off compactturns them off),atlas settings compact-mdoffers a Compact instructions block for a project'sCLAUDE.mdthe same way. For a project with no rules,atlas --setupandatlas settings rules-templateoffer a starterCLAUDE.mdand.claude/atlas-rules.md(the rules template).
Projects
One install serves several projects, each with its own index and memory store; recall, the hooks and the work queue see only the active project. A shared user layer is imported into every project.
One repository. Open Claude Code in it and answer yes, or run:
atlas settings add-project --vault . # or --vault-at FOLDER; without either, no vault
A folder of repositories. Open Claude Code in the folder that holds them (each one level down). atlas offers to make it a project, or run:
atlas settings add-project --new .
That writes atlas.project.json, listing each repository by path and remote, and creates the project's vault
beside atlas's configuration (--vault-at FOLDER for another folder, --no-vault for none); commit the file so the whole team
gets the same layout. Describe how the repositories relate, and a prompt that names one gets its role and
neighbours, while recall puts records about the repository you are working in first:
{
"name": "acme",
"repos": [
{"name": "billing", "path": "billing", "role": "invoices and payments", "talks_to": ["auth", "ledger"]},
{"name": "gateway", "path": "gateway", "role": "public API edge", "talks_to": ["billing"]},
{"name": "ledger", "remote": "https://git.example/acme/ledger"}
]
}
On a fresh install, add-project --new first moves the current setup into a project of its own (shown, backed
up, and reversed by the same atlas settings undo). In a terminal it asks for that project's name; otherwise the
name is the folder holding atlas.json, made a valid project name (-2 if the new project takes it). An existing
setup moves into a project of another name with atlas settings migrate-projects NAME. Everything else is on
Projects and multi-repo.
Minimal configuration
atlas.json, with relative paths taken from its folder. Every key is checked, so a misspelt key is an error.
{
"vaults": [{"name": "notes", "path": "../Notes"}],
"sources": [{"name": "docs", "root": "../my-project", "include": ["**/*.md"], "exclude": ["target/**"]}],
"code": {"roots": [{"name": "app", "root": "../my-project"}]}
}
Vaults are folders atlas may add to; sources are folders it only indexes; code roots feed symbol. After an
edit, run /mcp and reconnect atlas, or restart Claude Code. Every key is on
Configuration reference.
Security in brief
- Local only. One process over stdio. No HTTP client or DNS in the code or its dependencies, and one socket:
atlas pr-events serve, run only from the command line, listens on 127.0.0.1 for signed GitHub events and never connects out; the events reach it throughgh webhook forward, which it starts withgh. Nothing reaches the network at query time. The model download at setup and the update check go through the systemcurl, to pinnedhttpsURLs, and are verified (SHA-256, and an ed25519 signature for updates). - Confined. Every path is checked to stay inside a configured folder, lexically and after resolving links; dot folders are refused.
- A fixed deny-list.
.env*, keys, keystores and credential files are never read, whatever the configuration says: not in a source, not in a vault (nor written there), not byatlas digestoratlas crop. A file Claude Code reads with such a name is never kept as a handle, and neither is the output of a shell command,atlas runor Grep that names one. That catches named files only, since a shell command can hide a path. - Nothing lost. No delete or rename tool exists; writes are additive or exact, atomic and audited with a stated reason. The memory store is append-only.
The threat model and every defence are on Security model. Report vulnerabilities privately, as SECURITY.md describes.
Documentation
The wiki is the full manual:
- Overview: what atlas is and the rules it is built to
- Install and setup: install, updates, uninstall, build from source
- Configuration reference: every key of
atlas.json - Projects and multi-repo: scoped projects and repository graphs
- Token savings and method: where the tokens go and how it is measured
- Handles and digests: routing,
recall h:ID,atlas run - Tools reference: every MCP tool and the answer format
- Code index:
symbol, item ranges and language coverage - Semantic search: the owned embedder and hybrid search
- Identifiers and freshness: the registry, freshness and misses
- Memory store and hooks: the store, exports, sync and the hooks
- Memory tree: the memory index as a tree
- Memory and rule files: experimental, off by default: what atlas does with your rules and memories once you turn it on, and how to turn it off
- Orchestration: orchestrated mode: lanes, kinds and caps, starter resources
- Discussions: reviewer threads and the decision queue
- Generated indices: indices between markers
- Cross-vault links: links between vaults
- Security model: threat model and defences
- SQLite store: the database and the audit log
- Testing and coverage: the suite, adversarial tests, coverage
- Releasing: the changelog rule, release notes and the wiki
- Changelog: every release
License
// faq
What is atlas?
Local project memory and token savings for Claude Code: an MCP server and hooks. It is open-source on GitHub.
Is atlas free to use?
atlas is open-source under the Apache-2.0 license, so it is free to use.
What category does atlas belong to?
atlas is listed under productivity in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/atlas-3)
// retro hit counter
[](https://claudeers.com/atlas-3)
// reviews
// guestbook
// related in Productivity
Agent skills for Obsidian. Teach your agent to use Obsidian CLI and open formats including Markdown, Bases, JSON Canvas.
Open source repository of plugins primarily intended for knowledge workers to use in Claude Cowork
Garry's Opinionated OpenClaw/Hermes Agent Brain
An open-source alternative to Claude Cowork (powered by opencode)