// configuration

`atlas.config.json` reference

atlas.config.json lives at the repository root (not inside the vault) and is the single source of truth for how a specific repo’s Atlas is wired: folder remapping, optional modules, owns resolver classes, retrieval exclusions, hook toggles, and self-maintenance routines. SPEC.md’s Configuration section points here for the normative, field-level shape — this document is that shape.

Every command loads this file through a tolerant deep merge onto the full default shape shown below: a missing file, a partial file, or an unknown key never crashes a command — unknown keys and type mismatches print one stderr warning line each and fall back to the default. An editor pointed at schema/atlas.config.schema.json (via the $schema key below) gets per-field descriptions and autocomplete.

{
  "$schema": "./node_modules/memory-atlas/schema/atlas.config.schema.json",
  "version": 1,
  "enabled": true,
  "vaultDir": "acme-shop-atlas",
  "folders": {
    "zones": "map/zones", "decisions": "map/decisions", "flows": "map/flows",
    "specs": "specs", "plans": "plans", "programs": "programs",
    "ideas": "ideas", "techDebt": "tech-debt", "vision": "vision",
    "reference": "reference", "archive": "archive", "drafts": "drafts",
    "templates": "templates"
  },
  "modules": { "flows": false, "programs": false, "vision": false,
               "reference": false, "archive": false, "backlog": false,
               "drafts": false },
  "anchors": {
    "testids": { "enabled": false, "pattern": "data-testid=\"{id}\"", "root": "src" },
    "tools":   { "enabled": false, "pattern": "'{id}'", "root": "" },
    "routes":  { "enabled": false, "fileGlobs": [], "stripPrefix": "", "stripSuffix": "" }
  },
  "check": {
    "strictFreshness": false,
    "ownership": true,
    "corpus": { "enabled": false, "maxSummaryLen": 500 },
    "packageFreshness": {
      "mode": "warn",
      "registry": true,
      "wired": true,
      "registryTtlHours": 24
    }
  },
  "retrieval": {
    "engine": "ctx-search",
    "excludeFromSearch": ["drafts/", "visuals/"]
  },
  "skills": { "dir": ".claude/skills", "nav": "atlas-nav" },
  "hooks": { "sessionStartStatus": true, "sessionStartIndexRefresh": true },
  "routines": { "enabled": false, "cadenceDays": 7, "tasks": ["gardening"] },
  "visuals": {
    "enabled": false,
    "dir": "visuals",
    "package": "memory-atlas-visuals",
    "configFile": "visuals/visuals.config.json",
    "illustrated": "visuals/illustrated",
    "files": "visuals/files",
    "skills": true,
    "port": 4555,
    "concurrentDev": true
  },
  "telemetry": {
    "enabled": false,
    "level": "debug"
  }
}

atlas init writes exactly this shape (with vaultDir set to the vault it just scaffolded) — open a fresh repo’s atlas.config.json and it already documents every key.

Field reference

`version`

Type integer, default 1. The config shape version — bumps only on a breaking change to this schema, independent of the package’s own semver.

`enabled`

Type boolean, default true. The master kill switch. Set to false and:

every atlas subcommand except init prints nothing and exits 0;
the ctx-search adapter’s SessionStart invocation exits immediately, without spawning its reindex worker.

This is the safe default for a repo that vendored the convention but paused the practice — nothing errors, nothing runs, no code needs to change back.

`vaultDir`

Type string | null, default null (in practice always set by atlas init). Repo-relative path to the vault directory. This field is informational for external/companion tooling (SPEC.md Interop: companion tools should read vaultDir/folders rather than assuming layout). This CLI itself always discovers the vault by structure — the first directory containing map/index.md or map/zones/ — never by trusting this field, per SPEC.md’s “discover by structure, never by name” rule.

`folders`

Type object. Vault-relative paths (relative to vaultDir) for each note-type module. Every loader (notes, ledger, status, init’s additive-scaffolding mode, routine’s vault-routines lookup) resolves directory locations through this map — remapping any entry is free:

"folders": { "ideas": "notes/sparks", "techDebt": "debt" }

atlas init, run again in an existing vault, will create notes/sparks/ and debt/ instead of the defaults ideas/ and tech-debt/. map/index.md itself is not remappable — it’s a fixed generated-file location per SPEC.md’s vault layout, independent of this map.

`modules`

Type object, all boolean, default false. Optional vault modules beyond the core skeleton (map/zones, map/decisions, specs, plans, ideas, tech-debt, templates) — SPEC.md requires an Atlas never scaffold an empty optional module by default, so each stays off until enabled here or via atlas init --modules <name>,<name>.

`anchors`

Type object. Optional owns.* resolver classes beyond the always-on, always-required owns.globs. Each class (testids, tools, routes) MUST be declared here (enabled: true) before a verifier enforces it — SPEC.md §5. testids/tools are HARD anchors (an unresolved id is an error); routes is SOFT (an unresolved route warns, it doesn’t fail atlas check).

`check`

Type object.

strictFreshness (boolean, default false): when true, any stale zone fails atlas check. Useful for CI. Staleness stays advisory under plain atlas check and under atlas check --strict — only this config key hardens it (SPEC.md owner decision 3).
ownership (boolean, default true): enforce one-artifact-one-owner across mounted zones’ owns.globs.
corpus (object, default { enabled: false, maxSummaryLen: 500 }): opt-in retrieval-shape lint (summary cap, required headers, body links, orphans).

packageFreshness (object, default below): two-tier fleet follow for the memory-atlas package itself (not zone code freshness).

Field	Default	Meaning
`mode`	`"warn"`	`"warn"`: print only (exit 0). `"fail"`: `atlas gate` exits 1 on enabled-tier issues. CLI `--strict` always fails on issues.
`wired`	`true`	Tier A: installed package vs `.atlas-state.json` `atlasVersion` + pending migrations.
`registry`	`true`	Tier B: installed package vs npm latest (TTL-cached, fail-open if offline / no `npm`).
`registryTtlHours`	`24`	Reuse `updateCheck.latest` in the state lockfile before re-querying.

Surfaces: atlas status (always soft), atlas doctor [--strict], atlas gate [--strict] [--force]. Consumer recipe:

"scripts": {
  "predev": "atlas gate",
  "check": "atlas gate --strict && atlas check"
}

`retrieval`

Type object.

engine — one of ctx-search | obsidian-skills | grep | none, default ctx-search. Informational in v0.1: no retrieval engine is ever required, this just documents which one a repo uses so its skills/adapters can message correctly.
excludeFromSearch — array of vault-relative folder names (trailing slash), default ["drafts/", "visuals/"]. Hidden from automatic agent-facing indexing, search results, and orientation sweeps — the same .clineignore-style precedent: an agent explicitly asked to read one specific excluded file may still do so. Hidden, not sealed.

`skills`

Type object. dir (default .claude/skills) and nav (default atlas-nav): where this repo keeps its Atlas-navigation skills, and which one is the entry ramp. Documents the wiring described in docs/ONRAMP.md.

`telemetry`

Type object. Local-first debug telemetry — OFF by default when the package is published.

Field	Default	Meaning
`enabled`	`false`	Append one JSONL event per finished CLI command
`level`	`"debug"`	Reserved; counts when vault is available

Fleet enable (once on the machine, not per repo):

atlas telemetry on
# or: echo '{"telemetry":{"enabled":true}}' > ~/.config/memory-atlas/config.json
# or: export ATLAS_TELEMETRY=1

Events land in ~/.cache/memory-atlas/events.jsonl. Inspect with atlas telemetry report. Kill: ATLAS_TELEMETRY=0, --no-telemetry, or atlas telemetry off. Never tracks status --hook. No network in v1.

`hooks`

Type object, all boolean, default true. Per-hook toggles so a repo can disable one SessionStart helper without touching .claude/settings.json:

sessionStartStatus — gates atlas status --hook only. A direct atlas status (no --hook) always prints, regardless of this toggle — SPEC.md Interop requires a CLI invoked by both a hook and a human to distinguish the two call sites with a --hook flag, and this is that flag.
sessionStartIndexRefresh — gates the ctx-search adapter’s automatic SessionStart invocation (no flags). A deliberate --worker/--force run of the adapter script still runs regardless of this toggle.

Every hook body here returns in under a second and fails open (prints nothing, exits 0) — never surfaces an error on a normal session start.

`routines`

Type object. Configuration for atlas routine — see below. This package never schedules anything; enabled/cadenceDays/tasks describe how a repo wants to run routines, for the human (or the human’s own scheduler) to act on.

`visuals`

Type object. Optional companion package (memory-atlas-visuals) for a presentation plane over the vault (gallery, digests, typeset/derived views). Off by default. Paths are vault-relative. This package never requires or loads the companion — config is declarative only so zero runtime deps stay intact. Full enable path: docs/VISUALS.md.

Key	Type	Default	Meaning
`enabled`	`boolean`	`false`	Master switch. When `false`, digests/gallery tooling is not expected; companions and scripts should no-op.
`dir`	`string`	`"visuals"`	Vault-relative root for the visuals tree (digests, app, static assets). Always excluded from agent search by default (`retrieval.excludeFromSearch`).
`package`	`string`	`"memory-atlas-visuals"`	npm name of the companion. Informational for install docs and discovery — memory-atlas never imports it.
`configFile`	`string`	`"visuals/visuals.config.json"`	Vault-relative path to the companion’s own config.
`illustrated`	`string`	`"visuals/illustrated"`	Vault-relative directory for illustrated (skinned) note digests (`.mdx` only).
`files`	`string`	`"visuals/files"`	Vault-relative directory for companion-owned binary assets (diagrams, hero images, etc.).
`skills`	`boolean`	`true`	Whether companion navigation/skinning skills may be offered or vendored alongside Atlas skills when visuals are enabled.
`port`	`integer`	`4555`	Local dev server port for the visuals gallery app.
`concurrentDev`	`boolean`	`true`	Hint that dogfood/dev scripts may start the gallery alongside the product app. Consumer responsibility — core does not spawn product servers.

"visuals": {
  "enabled": true,
  "port": 4555,
  "concurrentDev": true
}

`atlas routine`

atlas routine <name> prints a self-contained maintenance-prompt template with {{CADENCE_DAYS}} substituted (from routines.cadenceDays) and a live counts footer (current zone/seeded/stale/open-debt counts) appended — a paste-ready prompt for an agent session, not something this package runs itself. atlas routine with no name lists available routines: the vault’s own <folders.templates>/routines/*.md first, then this package’s built-in templates/routines/*.md — a vault-level routine shadows a built-in of the same name, so a repo can add or override routines without forking anything.

Recipes

Hide two extra human folders from retrieval

"retrieval": { "excludeFromSearch": ["drafts/", "visuals/", "scratch/", "raw-notes/"] }

Remap `ideas` to a different folder name

"folders": { "ideas": "notes/sparks" }

Disable everything except `atlas status`

{ "enabled": false }

then wire only atlas status --hook in .claude/settings.json — every other command, and the ctx-search adapter, becomes a silent no-op. (This disables status too, since the kill switch is global — there is no “disable everything but one command” toggle; use per-hook toggles under hooks instead if you specifically want to keep status alive while turning off the index-refresh hook.)

Strict CI freshness (config only — not the `--strict` flag)

"check": { "strictFreshness": true }

Point skills at a custom directory

"skills": { "dir": "tools/agent-skills", "nav": "repo-nav" }

# atlas.config.json reference

# Field reference

# version

# enabled

# vaultDir

# folders

# modules

# anchors

# check

# retrieval

# skills

# telemetry

# hooks

# routines

# visuals

# atlas routine

# Recipes

# Hide two extra human folders from retrieval

# Remap ideas to a different folder name

# Disable everything except atlas status

# Strict CI freshness (config only — not the --strict flag)

# Point skills at a custom directory