---
name: atlas
description: "Atlas is a distributed Semantic Knowledge Network built with technologies LLMs already know: git and markdown, with a SCHEMA and a CLI that keep agents inside pre-defined, extensible domains. Triggers on atlas, atlas recall, atlas compile, atlas CI, GitHub Actions compile gate, schema overlay, atlas init, schema install, skill memory, work hub, remember knowledge, query atlas, search atlas, knowledge substrate, refresh landscape, update competitors, symbiont, who should we partner with, atlas help, getting started with atlas, how does atlas work, list atlas paths, explain atlas mount, atlas-memorise, atlas-recall, atlas-forget, atlas-optimise, atlas restamp. Load a path module (mount, init, migrate, memory-migrate, recall, remember, atlas-memorise, atlas-recall, atlas-forget, atlas-optimise, work, landscape, schema, configure, ci, help, getting-started) before acting. Unqualified help outside Atlas context is not this skill. Format rules remain in the skill named okf."
version: 0.13.1
activation_card: on
---

# Atlas

Durable, modular **OKF v0.2** knowledge substrate for skills and projects.

**Format authority:** skill **`okf`**. Atlas does not re-implement OKF rules.

**Current-shape memory model:** recall cues schemas from the reserved
`index.md` directory listing, then walks schema → gist → memory and stops
when the level in hand answers; `hub.md` is outside that memory walk. The
index is a schema cue list, not short-term memory, a table of contents, or a
copy of memory. Remember cascades a new or contradicted memory to its owning
gist and schema. On `CONTRACT.json`, suffixes `.schema.md`, `.gist.md`, and
`.memory.md` are search handles only; frontmatter `type` remains authoritative.
Compile’s current-shape additions are limited to uncovered gists, missing
schema index cues, and stale gist descriptions. Shipped `SCHEMA.json` page
type names and `frame_members` behaviour remain unchanged. If a live branch
changes subject, remember adds a new suffixed schema linked to the prior
schema and cued by the index; the work hub stays put and is not a memory.

**Default store:** `github.com/sergio-sisternes-epam/atlas-atlas`. Load path **`mount`** (`references/paths/mount.md`) before query or persist. That module is not a store. The store mounts at `<git-root>/.atlas/github.com/sergio-sisternes-epam/atlas-atlas`. Do not write into the skill package.

## Activation card (required)

Render every activation card in the assistant response as a fenced Markdown
code block with the `text` info string. The opening and closing fences are part
of the required output contract; an unfenced field list is incomplete.

Before formal query or any store mutation, emit path **mount** first. This skill passes its own store on the card:

```text
skill: atlas
skill_path: <resolved Atlas skill directory>
mode: run | discussion
subject: atlas | <project>
path: mount
path_module: references/paths/mount.md
intent: <one line>
atlas_id: github.com/sergio-sisternes-epam/atlas-atlas
ref: main
root: <set after resolve>
```

Then load `references/paths/mount.md` from the resolved Atlas skill directory
and follow it with those card fields. Missing `atlas_id` or an unloaded module
means Enter is incomplete.

After `root` is set, emit the operational card and load that module:

```text
skill: atlas
skill_path: <resolved Atlas skill directory>
mode: run | discussion
subject: atlas | <project>
path: recall | remember | work | landscape | schema | configure | ci | memory-migrate
path_module: references/paths/<path>.md
intent: <one line>
root: <atlas store root>
```

Then read `path_module` from the resolved Atlas skill directory and follow it.
Do not run from this router alone.

To **explain** Atlas without operating a store, emit path **help** or
**getting-started**. Do **not** emit path **mount** first. These modules are
read-only: they must not mount, init, schema-install, remember, commit, or
push. If the packaged baseline answers, stop. Help with no target lists every
module in the installed registry; do not ask for clarification just to list.

```text
skill: atlas
skill_path: <resolved Atlas skill directory>
mode: discussion
subject: atlas
path: help | getting-started
path_module: references/paths/<path>.md
intent: <learning goal, not an operation to execute>
atlas_id: <selected store id, pending, or none>
root: <resolved selected store root, pending, or none>
atlas_status: not-queried
atlas_used: []
help_status: pending
```

Then load that module. Unqualified “help” outside Atlas context must not
enter these modules.

To **create** a new Atlas, emit path **init** instead of mount. Default
**strategy is shared** (knowledge on consumer branch `atlas`). Dedicated
needs an existing store `remote`. Never create the host repository:

```text
skill: atlas
skill_path: <resolved Atlas skill directory>
mode: run
subject: atlas | <project>
path: init
path_module: references/paths/init.md
intent: <one line>
strategy: shared
remote: <consumer origin or existing dedicated store URL>
root: <set after resolve>
```

If strategy is dedicated and `remote` is missing, ask and stop. Then load
`references/paths/init.md` from the resolved Atlas skill directory.

To **migrate**, emit path **migrate** with required `migrate_mode`:

- `relocate` — skill off `<skill>/references/atlas` onto `.atlas/<id>/`
- `strategy` — move history between shared and dedicated (`atlas store rehost`)

```text
skill: atlas
skill_path: <resolved Atlas skill directory>
mode: run
subject: <skill>
path: migrate
path_module: references/paths/migrate.md
intent: <one line>
migrate_mode: relocate | strategy
atlas_id: <host/org/repo>
ref: main
destination_strategy: shared | dedicated
remote: <existing dedicated URL when destination is dedicated>
```

Then load `references/paths/migrate.md`. Missing `migrate_mode` (or `atlas_id` on
relocate) means Enter is incomplete. One own store per Run. CLI `atlas migrate`
still copies into staging; do not use it for strategy moves.

## Path registry (load before execute)

| path_id | When | Module |
|---------|------|--------|
| **mount** | Mount-if-missing and resolve `--root` | `references/paths/mount.md` |
| **init** | New Atlas; default shared (`atlas` branch) or dedicated existing remote; never creates the repo | `references/paths/init.md` |
| **migrate** | Relocate `references/atlas`, or rehost shared ↔ dedicated | `references/paths/migrate.md` |
| **memory-migrate** | Assess, inventory, or apply a named batch from a document-era or pre-beta store toward memory; also the explicit opt-in restamp of a current 0.13.0-beta.3/beta.4/beta.7 store to 0.13.0 | `references/paths/memory-migrate.md` |
| **recall** | Find / answer from an Atlas | `references/paths/recall.md` |
| **remember** | Write experiences, decisions, lessons, recipes; compile green | `references/paths/remember.md` |
| **atlas-memorise** | Choose the four-layer write target, then load path remember | `references/paths/atlas-memorise.md` |
| **atlas-recall** | Navigate the four-layer model by loading path recall | `references/paths/atlas-recall.md` |
| **atlas-forget** | Drop memory with keep, vary, or abandon | `references/paths/atlas-forget.md` |
| **atlas-optimise** | Operator-chosen fill and tidy of a named target: evidence-gated gist and schema fill, four-layer tidy repair, subject clustering, per-folder task list, dry-run first; not on install or compile | `references/paths/atlas-optimise.md` |
| **work** | Open, update, or close `work_id` hubs | `references/paths/work.md` |
| **landscape** | On-demand competitor + symbiont research; write comparison memory | `references/paths/landscape.md` |
| **schema** | Init, overlay install/new/uninstall; compile merge; Atlas overlays from APM packages (step 3a) | `references/paths/schema.md` |
| **configure** | SCHEMA 2.0 recall inspect, upgrade, explicit profile selection | `references/paths/configure.md` |
| **ci** | Assess, install, or repair CI for a mount with a contract file (`CONTRACT.json` or `SCHEMA.json`) | `references/paths/ci.md` |
| **help** | Explain installed modules without running them | `references/paths/help.md` |
| **getting-started** | First-use purpose, prerequisites, first journey, storage choices | `references/paths/getting-started.md` |

Paths are **not** separate catalog skills. CLI verbs (`recall run`, `compile`, ...)
are tools used inside paths. **help** and **getting-started** are explanation
modules; they are not CLI verbs.

## Hard rules

1. **Formal lookup = path `recall`** - B17 card `path: recall`, load `references/paths/recall.md`, then the CLI: `atlas recall run` for text and topic questions; `atlas graph nodes|edges|neighbours` for structural ones (see CLI surface). Do not merge those names. Unbounded whole-tree grep/rg/find is not path recall. On synthesis or a mention-only hit list, rewrite once from `glossary.md` Search aliases and prefer spine / work-hub pages. **Exception:** paths `help` and `getting-started` explain without mounting. They use the packaged baseline first. Only if that baseline cannot answer may they `atlas resolve` an already registered checkout and `atlas recall run --engine grep` under their own card. That is not path recall. They must not mount-if-missing, build recall indexes, or run the explained operation.
2. **`staging/` never answers** - compile hard-fails if staging is non-empty.
3. **Writes end on compile green** - `atlas compile --root <root>` exit 0 before claiming memory stored. Compile checks SCHEMA shape, required frontmatter, and required links - not markdown headings. On the current shape its new closed gates are `schema_folder` for uncovered gists, `schema_missing_from_index`, and exact-substring `stale_upper_page`; a second schema or a schema-only folder is not a compile failure. An unmounted external `atlas://` reference is a visible, non-blocking warning (`exit 0`) because the dependency may be transient. `index_md_present`, `index_md_listing`, and new page-contract misses remain actionable warnings (`exit 1`) until promoted. Listing checks concept `.md` pages and child folders with an index; media files are ignored. Compile severity `info` (memory-rung findings at the default rung) does not change the exit code.
4. **`relates_to` / `kind` are authoritative** - body `## Related` is optional mirror.
5. **Work cluster** - pages with a `work_id` link `work/<work_id>.md` with `kind: implements`.
6. **`log.md`** - append only for structural store changes (not every experience).
7. **Format-only questions** -> skill **`okf`**.
8. **Interim:** new process memory and knowledge ops for this substrate -> **Atlas paths**, not okf-wiki (until migration work completes).
9. **Wrong-frame correction** - if the user explicitly kills a comparison or thesis, resolve and load the installed companion skill **discuss**, then use its `terminate` path (recipe `references/recipes/terminate-wrong-path.md`). If `discuss` is unavailable, stop and tell the user that this path requires the companion skill; do not infer its procedure or keep writing the dead frame.
10. **Thoughtful current-theory remember** - writing `lesson`, live `decision`, or `recipe` requires this skill's remember card and a designed inventory (path, type, one-line claim, source URIs) produced by the agent before write. Human request and approval are **not** default gates. If the human asks for review on an important persist, stop after the inventory and wait. Recipe: `references/recipes/gated-memory-building.md`. Decision (atlas-atlas store, not this package): `decisions/atlas-memory-layers.md`.
11. **Write-home is the active git repo** - load path `mount` first. Mount-if-missing with no `--target`. Query and persist use `--root` on that mount. No git repository: refuse to persist. Never mount or write at `<skill>/references/atlas`.
12. **SCHEMA mutations = path `schema` + CLI** - load `references/paths/schema.md`. Do not hand-edit the store's single contract file (`SCHEMA.json` or `CONTRACT.json`) or `schema.d/`.
12a. **Recall policy = path `configure` + CLI** - load `references/paths/configure.md`. Installing a contribution is not activation.
13. **CI layers stay distinct** - path `ci` configures the institutional merge gate on an Atlas mount (`SCHEMA.json` or `CONTRACT.json`); `atlas compile` is the CLI tool; path `compile` is separate agent-session discipline. Do not substitute Atlas skill tests for mount CI.
14. **Help explains; it does not execute** - paths `help` and `getting-started` are discussion modules. Reading help for mount/init/remember/recall must not run those operations. No-target help lists the installed registry without clarification. Unknown targets are explicit unknowns plus valid choices. Unqualified “help” outside Atlas context must not hijack unrelated tasks. CLI option lists come from installed non-mutating `--help`, not memory.

## CLI surface

Resolve `<atlas-skill>` to this skill's installed `skill_path`; do not resolve
the following commands relative to the consumer project.

```text
python3 <atlas-skill>/scripts/atlas.py init --root <atlas> [--force] [--schema-version 1.0|2.0]
python3 <atlas-skill>/scripts/atlas.py compile|validate --root <atlas> [--type <type>] [--path <prefix>] [--dry-run]
                       # --dry-run reports findings (including memory_rung) without writing mesh.json or publishing the recall index
python3 <atlas-skill>/scripts/atlas.py recall run "..." --root <atlas> [--engine grep|bm25|nanograph] [--include-exits] [--profile <id>] [--allow-partial] [--scope store|mesh] [--rrf-k N]
                       # query tokens: type: kva: status: work_id: path:
                       # --scope mesh: federated recall over the atlas-mesh.json members (tiered RRF, k 1-1000, default 60); --profile and --allow-partial are store scope only (each exits 2 with --scope mesh); --limit 0 = all hits
python3 <atlas-skill>/scripts/atlas.py schema upgrade --to 2.0 --root <atlas> [--dry-run|--apply]
python3 <atlas-skill>/scripts/atlas.py recall status|profiles|show|validate|activate|disable --root <atlas>
# index verbs all take [--root <dir>] [--json]; `index build` replaces deprecated `recall index build`
python3 <atlas-skill>/scripts/atlas.py index set <grep|bm25|nanograph> [--store <id> | --default] [--build]
python3 <atlas-skill>/scripts/atlas.py index unset [--store <id> | --default]
python3 <atlas-skill>/scripts/atlas.py index show [--store <id>]   # at a project root of 2+ stores: --store required (exit 2, store_required)
python3 <atlas-skill>/scripts/atlas.py index status
python3 <atlas-skill>/scripts/atlas.py index build [--store <id> | --all] [--force]
python3 <atlas-skill>/scripts/atlas.py graph nodes --root <atlas> [--where field=value]... [--path <prefix>] [--include-exits] [--limit N]
python3 <atlas-skill>/scripts/atlas.py graph edges --root <atlas> (--from <page> | --to <page> | --all) [--kind K]... [--include-exits]
python3 <atlas-skill>/scripts/atlas.py graph neighbours <page> --root <atlas> [--kind K]... [--direction in|out|both] [--hops 1..3] [--where field=value]... [--driver native|nanograph]
python3 <atlas-skill>/scripts/atlas.py graph drivers --root <atlas> [--json]
python3 <atlas-skill>/scripts/atlas.py graph export --root <atlas> --format json|nanograph --out <dir-outside-store>
python3 <atlas-skill>/scripts/atlas.py id <pointer>
python3 <atlas-skill>/scripts/atlas.py auth [--host github.com] [--ssh]
python3 <atlas-skill>/scripts/atlas.py mount <source> [--ref <branch>] [--target <path>] [--ssh]
python3 <atlas-skill>/scripts/atlas.py resolve <pointer>
python3 <atlas-skill>/scripts/atlas.py store init [--strategy shared|dedicated] [--remote <url>]
python3 <atlas-skill>/scripts/atlas.py store rehost --destination-strategy shared|dedicated [--remote <url>] [--id <atlas_id>]
python3 <atlas-skill>/scripts/atlas.py migrate <source> --root <atlas>
python3 <atlas-skill>/scripts/atlas.py promote <staging-file> --to <path> [--type ...] --root <atlas>
python3 <atlas-skill>/scripts/atlas.py schema new <id> --root <atlas> [--claim <folder>]
python3 <atlas-skill>/scripts/atlas.py schema install <source> --root <atlas> [--force]
python3 <atlas-skill>/scripts/atlas.py schema uninstall <id> --root <atlas>
# --set accepts exactly one of: info, warn, error
python3 <atlas-skill>/scripts/atlas.py schema memory-rung --set info --root <atlas>
python3 <atlas-skill>/scripts/atlas.py schema memory-rung --set warn --root <atlas>
python3 <atlas-skill>/scripts/atlas.py schema memory-rung --set error --root <atlas>
python3 <atlas-skill>/scripts/atlas.py memory-migrate --root <atlas> --operation assess|inventory|apply [--batch contract-file|restamp]
python3 <atlas-skill>/scripts/atlas_optimise.py plan|apply --root <atlas> --target <folder|.> [--optimise-mode path|full|custom|incremental] [--since-hours <N>] [--custom-tree <prefix>] [--tidy-only] [--auto-verbatim] [--fill-sensible] [--cost-ceiling <pages>] [--pilot] [--out-dir <dir>] [--plan <plan.json>]
                       # path atlas-optimise only: standalone helper, operator-chosen, never run by install or compile. Full is serial only.
```

Search engine: grep by default until recall is enabled. Without recall, `--engine bm25` ranks with SQLite FTS5 on a fresh on-disk index, falling back to grep with a warning only if FTS5 is unavailable or projection fails. A preferred engine (`atlas-mesh.json` `recall.engine` or `ATLAS_RECALL_ENGINE`) becomes the default, its index auto-created and refreshed; an enabled store recall profile still wins. An all-words FTS5 miss triggers one any-word retry labelled `match: "any"`. Opt-in default is `atlas:ranked` (published FTS5, content-digest fast path; beats grep on speed and follow-up reads). `atlas:tgrep` is advanced/limited. See paths `recall` and `configure`. Provenance: atlas-atlas lesson `lessons/2026-09-09-opt-in-ranked-after-fast-path.md`.

Routing (hard rule 1): formal lookups enter path `recall`; there, text and topic questions use `atlas recall run`, structural ones (which pages link to X, neighbours, work-hub children, nodes by frontmatter) use read-only `atlas graph nodes|edges|neighbours` (`references/graph.md`). `graph export` writes outside the store.

Drivers: optional nanograph (`--engine`/`--driver nanograph`) runs only on macOS arm64, is never the default, and falls back to the built-in driver with a `driver_note` (`references/drivers.md`). Derived indexes live in the consuming project at `.atlas/indexes/<driver-type>/<atlas-id>/`, never in the store; legacy in-store `.atlas-index/` is read-only until removed after 0.14.x.

## Core contract (summary)

| Topic | Rule |
|-------|------|
| Structure | Free layout; mandatory single root contract file (`CONTRACT.json` on new stores, `SCHEMA.json` on shipped 0.13.0-beta and 0.13.0-beta.2 stores — never both); short-lived `staging/`; `index.md` / `log.md` per OKF |
| Types | `experience`, `decision`, `work`, `lesson`, `recipe`, `document` (legacy), `protostar`, `gist`, plus the memory-layer pair: `page`/`frame` on shipped 0.13.0-beta (`SCHEMA.json`, one gist still counts), `memory`/`frame` on 0.13.0-beta.2 (`SCHEMA.json`, one gist still counts), `memory`/`schema` on the current `CONTRACT.json` shape (written as `0.13.0`; first introduced in 0.13.0-beta.3; one gist still counts) — recommended, not closed |
| Memory layers | Optional progressive disclosure. Index membership does not require a schema, and a page may skip the gist. A folder with one or more gists has exactly one same-folder frame (or, on the current `CONTRACT.json` write model, `schema`) listing those gists once each; zero gists means none. A gist may list N≥1 same-folder `derived_from` parents. Shipped 0.13.0-beta, 0.13.0-beta.2, and the current `CONTRACT.json` shape all treat a lone gist as enough for a frame/schema. |
| Origin / sensitivity | Recommended frontmatter: `origin` (internal \| third-party \| user \| derived), `sensitivity` (public \| internal \| restricted) |
| Relations | `relates_to: [{path, kind}]` - kinds: follows, records, supersedes, implements, derived_from, related |
| Composition | Optional mesh; consolidated in compile |
| Provenance | Optional `sources` profile on extracted pages |

## Skill relationship

| Skill | Role |
|-------|------|
| `okf` | Format authority |
| `okf-wiki` | Legacy only - **do not use for new process memory**; prefer Atlas paths until migration |
| `autogenesis` | May use Atlas as process memory |
| `construct` | Adversarial / happy-path evaluation |
| `discuss` | KVA discussion fabric; path `terminate` owns wrong-frame exit ramps |

## Non-goals

- Replacing `okf`
- Phone-home telemetry
- Auto-authoring claims without an agent
- Live okf-wiki migration (separate work `atlas-bm25-and-live-migration-v1`; BM25 ranking itself ships as `--engine bm25`)

## Progressive disclosure

Procedures live only under `references/paths/`. Load one path per intent
(mount, init, migrate, memory-migrate, recall, remember, work, landscape, schema, configure, ci,
help, getting-started). Packaged help baseline lives under `references/help/`.
SCHEMA and templates live under `references/`. Do not dump full help into this
file.