Repository navigation
Tools reference
tools/list names 14 tools (about 1,510 tokens; it was 47 tools and 5,930 tokens). lookup, search,
section, grep, symbol, recall, remember, journal, handoff and hook keep their names; the rest
of the surface sits behind four tools with an op argument:
| Listed tool | op |
Runs |
|---|---|---|
note (reads) |
read (default), list, find, backlinks, outlinks, broken, link, log, vaults, sources, judge, help
|
read_note, list_notes, find_by_frontmatter, backlinks, outlinks, broken_links, make_link, write_log, list_vaults, list_sources, judge_task, the help text |
edit (writes) |
create, append, history, frontmatter, section, link, next_id, index, refresh, refresh_all
|
create_note, append_to_note, append_history, set_frontmatter, replace_section, link_notes (vault and path name the note written into), next_id, build_index, refresh_index, refresh_all_indices
|
discuss |
open, post, read, status, awaiting, list, queue, conclude, unresolved, decide
|
open_discussion, post, read_discussion, discussion_status, awaiting, list_discussions, decision_queue, conclude_discussion, mark_unresolved, record_decision
|
miss |
list (default), report, resolve
|
misses, report_miss, resolve_miss
|
lookup without id runs ids; remember with old runs supersede; recall with op: "status" runs
journal_status and with op: "log" runs memory_log. Each listed schema names the arguments most calls
use, without descriptions; every argument of the full tool an op runs is still accepted and checked. The whole
reference, every tool and argument described, is one fetched text: the MCP resource atlas://help, or
note {op: "help"} for a client without resources. The full tool names (the table below) still work as tool
names for this release, so existing calls and hooks keep running; the server's instructions point at the help.
search, recall, section and grep are marked always-loaded
(_meta["anthropic/alwaysLoad"]: true in tools/list, Claude Code 2.1.285 and later), so their schemas are
in context from the first turn and the model calls them without a tool search first. Every other tool stays
deferred: only its name is in context until the model searches for it. lookup and symbol (the identifier
and code indexes) are deferred too: 12 calls a week did not pay for their 627 bytes in every agent's context,
so an agent loads them by a tool search (in Claude Code, ToolSearch with select: and the tool's name) before
its first call.
Every tool answers in plain text by default; format: "json" gives
the JSON instead (for the memory tools: recall {key} and recall {op: "status"} as fields, every other memory
answer as {"text": ...} around its text), and verbose: true adds scan times and timings where a tool takes it. read_note is one
vault:path sha256=... bytes=N line, then the note exactly as written (the JSON answer repeats the frontmatter
parsed beside the content). A tool without a text form of its own writes its JSON as key: value lines, a list
of flat records as one table under key: N, and every element of every list: the work-queue tools
(decision_queue, awaiting, journal_status) are never cut. journal_status lists the active lanes (an open
question, a queued entry, or a record in the last 14 days), then +N idle lanes (all=true to list) for the
rest; all: true lists every lane. The text (src/text.rs):
- A list is a header row of field names, then one tab-separated row per record, so names appear once. Inside a
value a tab is written
\t, a newline\nand a carriage return\r; nothing else is escaped. - A snippet is about 120 characters centred on the matched identifier or word, cut on character boundaries,
with
…where it was cut. Repeat mentions in one section are one row with a count (n). - Default limits are small (
lookupmentions 3,search50 lines or 5 sections,ids50,misses20) and a cut list ends with+N more (limit=L).recall {query}ends with what it left out:+N more over budget_tokens,+N more scoring near zero,+more (limit=L). Akindorscopefilter searches every word of the query up to its first 48, and a query longer than that ends with+N more words were not searched; with no filter, a long query is searched by its 12 rarest words. The query is not echoed. - Freshness says nothing when everything is fresh; otherwise one
stale SOURCE:PATH STATE[, reindexed]line per file, up to 8 per source; past that onestale SOURCE N files (REASON)[, reindexed]line, where REASON is why the source is rebuilt from empty (schema rebuild,index rules changed,first index) or the count per state (12 changed, 3 new). JSON givesstale_countandreasonin place of the list. -
lookupshows its definitions first (defs), then the strongest definition's text capped at 600 characters (full: truefor every definition whole), thenmentions.searchin sections mode shows snippets (full: truefor whole sections).
Each answer is sent once, as the text content: there is no structuredContent copy.
Every answer is logged to the token_log table with the bytes returned and the bytes the same question costs
without atlas: what grep -rniF would print for the question's literal over the same files, plus the files a
reader then opens (whole when at most 80 lines, else an 80-line window around each match, windows merged). The
rule is in src/tokens.rs; the measurement runs on a background thread after the answer is written.
atlas --token-report prints a summary in about 15 lines: the measured ratio (mean and median), credit, cost
and net, the "Where the savings live" rows by source (when two or more sources are each under 1% of both the
credit and the cost, they fold into one "small sources" row), and the answers and ledger ratio of the 7 days to
the newest logged day. Every line fits 80 columns. atlas --token-report --verbose prints the
full report: totals by tool and by day (tokens returned, the counterfactual, and the ratio) and every block
below; --tsv prints the full report as tab-separated lines. The blocks named below are the full report's.
The other read tools with a grep equivalent use the same two parts: section greps its id or heading like
lookup, grep is its own pattern, read_note reads the whole note, recall {query} greps the query over the
export files, and recall {key} or {lane} reads the record where it is written (a memory's whole file;
another record's text plus 40 lines either side in its export; a lane's every record), the rule the hooks use.
Writes, journal among them, log no counterfactual.
The "brief without atlas" is what an agent spent on the rulebook (memory.brief_reference) before atlas,
measured from the calibration's pre-atlas transcripts: the bytes of their Read calls of that path (matched as
text, slashes and case folded, a relative path joined to the call's folder) over every pre-atlas subagent
transcript, readers and non-readers alike; main sessions are left out. Agents read parts of it, so its size is
not the yardstick. With no calibration, or no such read, the report says "not measured" and gives no ratio.
Each subagent start logs the rulebook's size at that moment; --token-report counts agents by those rows (a
distinct session and agent id) and keeps their sum as one if read whole line, the size once per agent, not a
measurement. Each agent is counted once, at its first start: Claude Code fires SubagentStart again whenever an
agent resumes (a SendMessage, or a background task waking it), and a resumed agent keeps its context, so the
report gives those repeats as resumes and does not count them as reads. It never enters a per-answer ratio.
Beside it, hook injections sums what the recall hooks injected: a main session (it lives for many prompts)
per prompt, by the turn rule of the cost section, and a subagent per agent, each as p50, p95 and max, then the
largest one main session or subagent received. brief vs injections then compares the measured rulebook with
what the hooks injected on the agents both tables hold, and the ratio. A Where the savings live block, right
after the headline, gives credit, cost and net per source (lookups, routing, the rulebook at subagent starts,
prompts and tool calls, memory and note reads, tool definitions, the rest), each against its yardstick; the rows
sum to the net, whose credit counts the rulebook only when it is measured. No source is credited twice: a measured
rulebook replaces the SubagentStart hit credit, and is credited less the credit of recall by key or lane, which
may read the same records. Other lookups that open the rulebook may still overlap it; the ledger records no agent
or file per answer, so the block's header bounds that overlap by the rulebook row's credit instead of measuring
it. A PreToolUse injection is costed by event, so a subagent's lands on the prompts and tool calls row.
read_note is 1x by design: its
counterfactual is the whole file it returns, and section is the cheaper read for one heading.
recall.inject_floor (a cosine threshold) and recall.session_budget_tokens (a cap per session) bound it.
Then a context selection line says what recall.select did to those injections: how many were sent whole,
trimmed to their matching clauses or collapsed into a ref to a near-duplicate, the tokens each would have taken
whole against what was sent, and the share saved.
The report also measures what atlas itself costs, from bytes, with no model estimate. A: the tool list and
instructions sent at every session or subagent start the store shows, plus each atlas tool schema loaded later
through tool search. B: the hook injections as sent, by event, plus their re-reads: an injection stays in
context for every later request up to the next compaction. C: every tool's returned bytes, one total for all
sessions (the ledger has no session column). A Net block after the headline gives credited savings minus that
cost, and a net table gives it by tool. Each re-read is priced from its request's usage block: cache reads,
5-minute and 1-hour cache writes and uncached input by their proportions, at the ratios of one price table by
model (src/token_cost.rs); a request with no usage block or an unknown model is priced at the full rate and
counted. Tool search loads and re-reads are seen only with --token-report --transcripts DIR (Claude Code's
projects folder, read only); without it, or for a session whose transcript is gone, the net line says it counts
only the costs atlas can see and that the true net is lower. A turn is a distinct second of a main session's
UserPromptSubmit rows, so a prompt that injected nothing is not counted and the cost per turn errs high.
recall {key: "KEY@HASH"} reads one exact version: HASH is 8 to 64 hex digits of the version's SHA-256 (a
ref is written with 12, the start of the sha line a recalled record shows). The answer is that version
verbatim, marked (current), or (changed: the current text is KEY@NEW) when a later version replaced it;
a hash no version has is an error that says the ref is dangling. Versions are never deleted, so a ref handed
out once always resolves to its text. recall {key: "SRC:PATH:A-B@HASH"} reads lines A to B of a vault or
source file: marked (current) when the hash still names them, else the current lines with their new ref (a path
with a space cannot be written as a ref). With memory.transcripts on, recall {key: "turn:<session8>:<line>@hash"}
returns one earlier transcript turn as stored (visible text, secret lines [redacted]) and recall {query, kind: "turn"} lists matching turns with their refs; both see this project's turns only, and with the source off both
are refused. atlas --compact-report --transcripts DIR [--sweep T,T,...] adds the
checkpoint card's size and coverage, the hooks' latency, and with --sweep the token side of where to compact
(a plain and an atlas-assisted arm at each threshold on the same sessions, each atlas row judged against plain at the
same threshold: compactions, raw and cache-weighted tokens, re-reads; plain at Claude Code's default point is a
labelled reference row only). --token-report --verbose ends with the compaction line: the ratio of context
before a compaction to its summary, refs and their dangling rate, and the lookups made again after one:
within 40 tool calls of the boundary, repeats over lookups (comparable with the offline replay) and misses of
targets unchanged since (a file's mtime and size, a folder by the edits under it and any shell command, a record's sha), then the uncapped misses, the repeats of
changed targets and the unstamped ones (shell commands, MCP calls without a key). atlas --token-report --repeats [--since TIME] lists the 20 targets repeated most since TIME (paths, patterns, keys, and a shell
command's first two words with a hash), misses, changed and unstamped apart.
atlas --misses-week [--since TIME] is the weekly misses pass: the ten open misses (report_miss) seen most
since TIME (default seven days ago), by tool and query, then the ten injected keys that cost the most tokens in
the same window, to check whether each earned its place.
Every key a hook injects is logged to hook_inject with its scores, bytes and counterfactual.
atlas --hook-report marks each one a hit by fixed rules, looking only at the same session's later assistant
messages: the key in a tool input (a recall key=, a lookup, a grep), its source read (a memory's file, or a
Grep of its export file whose pattern matches it), or a quoted run of 8 of its words; and prints the hit rate
per hook. --transcripts DIR --since TIME adds injections reconstructed from past transcripts (rescored by the
hook's own gate), --rows lists every key, and --tune-floor SCALE prints the relevance-floor curve from the active floor up and the
floor that maximises the bytes the kept hits save net of the bytes injected (SCALE is the share of a hit's
counterfactual credited: 1 for the full ledger credit). --token-report credits each hit by the same rules;
once an injection's transcript has been still for six hours (and ends before the ledger's last row), its
verdict is stored in hit_verdict, so a repeat report reads only the transcripts still changing. A stored
verdict (a hit's, or a routed Read's in read_verdict) keeps the judge's version and the transcript's last
change and size, and is judged again when either differs, as when a settled session is resumed; once the
transcript is deleted, its stored verdicts stand. They hold memory as it was when they were judged: a later
edit to a record does not change them.
The counterfactual is rule-based, not a bound: some rows overcount and others score 0. atlas measures the other side itself, from your own Claude Code
transcripts: the bytes of the Grep, Read and shell-read results agents read when they looked something up in the
files atlas serves, before atlas, grouped into one episode per question. The server does it in the background,
never on a hook's path, at its first start and again when the lookup rules or the configured targets change;
atlas --calibrate does it by hand, with progress. The cutoff is the earlier of the store's first atlas answer
and the first atlas call in the project's transcripts, kept from the first run; the transcripts are those whose
session ran in one of the project's folders (every one without projects), less temporary, scratch, eval and
replay folders (calibrate.skip); a call another transcript already holds (a replay, a resumed session) counts
once. What the rules read of each pre-cutoff call (never a result's text) is kept in the store, so a later
recalibration does not lose history Claude Code has since deleted. --token-report --verbose then heads its output with
the measured ratio (mean pre-atlas episode over mean atlas answer, a ratio of sums; the medians' ratio beside it,
marked not additive), when it was measured, from how many episodes and transcripts and with which rules version,
and the ledger ratio with its per-answer median, labelled rule-based, not a bound. With fewer than 30 episodes
from 5 transcripts it gives the ledger ratio alone and says why. The rules are in src/calibrate/.
| Tool | Writes | What it does |
|---|---|---|
lookup |
an identifier's definitions (strongest first, each with the defining text) then mentions (newest first), source, path, heading path and line for each, plus freshness; text_hits when nothing is registered |
|
ids |
registered identifiers in natural order: kind, definition and occurrence counts, newest date; filters prefix, pattern, kind, source
|
|
list_sources |
vaults and sources: root, globs, files and sections, last scan and index times, stale files | |
judge_task |
the task judge's pick for an agent launch prompt (prompt; kind, else read from the prompt, subagent_type and description): scope, unknowns, model, effort, split, and a Judge: line to paste. Needs orchestrate.judge.cells
|
|
report_miss |
misses log | records what grep found and atlas did not: tool, query, what atlas returned, where it was found, reason |
misses |
the misses log, newest first: open (default), resolved or all
|
|
resolve_miss |
misses log | marks a miss resolved; the reason is the note. Misses are never deleted |
list_vaults |
short name, folder name, note count | |
list_notes |
notes under a folder, optional glob (* ? **; without / it matches the file name) |
|
read_note |
a vault:path sha256=... bytes=N line, then the note as written; JSON: content, sha256, size, parsed frontmatter |
|
search |
substring (default), regex, or fts (SQLite FTS5, ranked) over vault notes only (an empty answer says so when sources are configured; sections or grep reach sources), returning vault, path, line, snippet; or sections: ranked FTS5 over the sections of every vault and source, returning whole sections with heading path and line range, plus freshness; semantic ranks the same sections by meaning, hybrid fuses both rankings (see the Semantic search page) |
|
symbol |
a name (or Type::name) in Rust, WGSL, Protocol Buffers, Go, TypeScript, JavaScript, C#, Python or Java (Kotlin and unindexed files: definitions only; see Code index for when each needs its SCIP indexer): its definitions, then references with the function each sits in (the caller), then impl edges, each root:path:line with a snippet (see the Code index page) |
|
find_by_frontmatter |
key = value (list values match any item, prefix for queued vs queued 139) |
|
backlinks / outlinks
|
across all vaults: wikilinks, embeds, Markdown links, obsidian:// links, each resolved |
|
broken_links |
links whose target note is missing, cross-vault included (attachments not checked) | |
make_link |
[[wikilink]] in the same vault (folder dropped when the file name is unique in the vault, as Obsidian's shortest-path links do), obsidian://open link across vaults; errors if the note or heading is missing |
|
link_notes |
yes | appends - <link> under ## Related (or another section, created if missing); reverse links back; skips a link already present |
create_note |
yes | fails if anything exists at the path (create_folders to make parents) |
append_to_note |
yes | appends at the end |
append_history |
yes |
- YYYY-MM-DD: text as the last line under ## History (heading created at the end if missing); date defaults to local today |
set_frontmatter |
yes | replaces named keys' lines in place; other keys and the body stay byte-identical |
replace_section |
yes | replaces one heading's body, or the preamble (text between the frontmatter and the first heading) with preamble: true or heading: ""; requires expected_sha256
|
next_id |
yes | allocates the next PI-### (any prefix and width) and optionally creates <folder>/<id> <name>.md, {{id}} substituted |
build_index |
yes | writes a generated index between markers (see Generated indices) |
refresh_index / refresh_all_indices
|
yes | regenerate from the specs stored in the markers; no write when nothing changed |
write_log |
the audit log, newest first: time, tool, vault, path, client, reason, discussion, sha before and after; filters vault, path, client, discussion, since, until (UTC, 2026-10-08 or 2026-10-08T14:30) |
|
open_discussion |
yes | creates Discussions/D-### <topic>.md with subjects, participants and P-1 (see the Discussions page) |
post |
yes | appends the next post to a thread |
read_discussion |
posts as JSON (since_post for only what is new), integrity check, and outcomes
|
|
discussion_status |
each claim, challenge and question: answered, conceded, retracted, contested, unchallenged or open | |
awaiting |
challenges and questions to an author's posts that the author has not replied to | |
conclude_discussion |
yes | verdict post, status concluded; gated on contested challenges; returns the verdict's link |
mark_unresolved |
yes | ends a thread without agreement for a human decision |
record_decision |
yes | settles an unresolved thread with a decision post |
list_discussions |
threads, filtered by vault, status, subject, needs_decision
|
|
decision_queue |
every unresolved thread in every vault, oldest first |
append_to_note and set_frontmatter accept an optional expected_sha256. Every write returns
sha256_before, sha256 and changed; an edit that produces identical bytes writes and logs nothing.
Line endings: no write normalises a note's line endings. Every edit leaves the bytes outside the edited span
untouched, and inserted text takes the note's own ending (CRLF when its first line break is CRLF, else LF);
new notes are LF. Test writes_keep_crlf_files_crlf runs every write tool over a CRLF note.
Every write tool except open_discussion and post has a required reason argument: why the change is
being made. (open_discussion and post record their post's kind, author and the start of its body as the
reason.) Every write tool except the thread tools also takes an optional discussion
(perf:D-004 or perf:Discussions/D-004 ....md): the thread the change comes from. The server checks the
thread exists, stores it on the audit row and the JSONL line, and a short reason that just points at the
thread ("per perf:D-004") is enough. A thread's read_discussion then lists those writes as outcomes, and
write_log {discussion: "perf:D-004"} finds them. The reason is checked before
anything is read or written, and the call is refused if it is missing, not a string, blank, under 12
characters after trimming, over 500 bytes, more than one line, or a stock placeholder (update, fix,
n/a, none, edit, minor changes, no reason given, not applicable, ... compared case- and
punctuation-insensitively; the list is PLACEHOLDERS in src/tools.rs). The trimmed reason is stored in
the writes row and the writes.jsonl line, and never written into the note (an append_history line is
exactly the text given). write_log answers "why did this note change?":
write_log {vault: perf, path: "Ideas/PI-014 ....md"}.
-
next_id {vault: perf, folder: Ideas, prefix: "PI-", name: "Short name", content: "---\nid: {{id}}\n..."}takes the number and createsIdeas/PI-NNN Short name.mdin one step. Two agents can never get the same id: allocation runs under the database write lock, skips any number a file in the folder already uses (by hand or by a writer outside this server), and the file is created exclusively, retrying on a clash. - Status change:
set_frontmatter {values: {status: "parked", tags: [...]}}thenappend_history {text: "parked: measured +0.2 ms (PR #123)"}. Nothing is removed; parking is a frontmatter change. - Index and area lines: either
append_to_note/replace_sectionon the hand-written tables, or (once the tables are converted, see Generated indices)refresh_all_indices. - Evidence on an existing idea:
append_to_noteorreplace_sectionwith the sha fromread_note.
With the hooks on, the PreToolUse hook names the session and agent behind the next atlas call. A read tool
called again by the same agent with the same arguments then answers unchanged since your call #N with these arguments, or, when the answer changed and the changed lines are under half of it, only those lines (+ line
new, - line gone). fresh: true on any call gives the whole answer, and every such reply says so. Without the hooks there is
no agent identity, and repeats are compared per server process: one server serves a session and its
subagents, so a subagent may be told unchanged since call #N of an answer only its parent holds, and
follows the reply's fresh: true to get it. Once a PreToolUse hook has been seen, a call it did not announce
is never answered by reference. A PreCompact hook forgets the session's answers. The work-queue tools
(decision_queue, awaiting, journal_status, next_id, the discussion reads, misses) and
recall {lane} always answer whole; whole for journal_status means every active lane and the idle count
(all: true for every lane).
read_note takes lines (A-B, A- or A, from 1) or budget_tokens (whole lines up to about that many
tokens, the first line always); the header line names the lines shown, and a cut ends with
+N more lines (lines=A-B). Search hits already carry vault:path:line. A record recall {key} reads, and a
whole record in a recall {query} answer, carries @L1234 (the line of the export file its key names) or
@path:line. Pointers do not by default: with recall.pointer_anchors on, each ends with @src:path:line,
and read_note {vault: src, path, lines} reads that part of the vault or source file. Measured on the memory
evaluation, the anchors cost more tokens a question than the line reads they enable save (see the
configuration reference). read_note reads a source's files as well as a vault's notes.
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