Core concepts

Anthracite is a compiler for personal knowledge. Understanding four things — the 3-layer model, ANTHRACITE.md, .anthracite/config.json, and the vault layout — explains how the whole app behaves.

The 3-layer model

Everything flows through three layers: Capture → Interpret/Compress → Surface.

Layer 1 — Capture
  Connectors land immutable bytes in raw/<id>/
  reading / transcription / scrape → raw/<id>/extracted.md (+ meta.json)

Layer 2 — Interpret & Compress   (two parallel tracks)
  Wiki track  → wiki/*.md     ("what I know")
  Board track → tasks/*.md    ("what I should do" — journal parse → kinds → Eisenhower)

Layer 3 — Surface & Output
  Wiki reader · Board · Graph · Ask · (exports declared for later)

Layer 1 — Capture. Connectors copy original bytes into raw/<id>/ and never mutate them. Anthracite then extracts plain text (extracted.md) by reading (handwriting/images/PDFs), transcribing (voice), or scraping (web clips).
Layer 2 — Interpret & Compress. Two parallel tracks read extracted.md: the Wiki track distills knowledge into linked wiki/ pages, and the Board track parses journal entries into tasks, classifies them into kinds, and prioritizes the actionable ones on an Eisenhower matrix.
Layer 3 — Surface. You read and act on the result in the app (Wiki, Board, Graph, Ask). Export adapters (ICS, Todoist, …) are declared but built later.

The deep dive lives in docs/CONCEPT.md.

Policy vs. mechanism

A core design split that explains where settings live:

	File	Holds	Example
Policy / intent	`ANTHRACITE.md` (vault root)	What to capture, how to interpret/compress, what to surface, in what language	journal style, signifier legend, task kinds, board layout, purpose
Mechanism / secrets	`.anthracite/config.json` (+ system keychain)	How — endpoints, model IDs, ports, keys	LLM provider/model, OCR backend, API tokens

This makes ANTHRACITE.md a portable, human-readable source of truth that never leaks secrets — you can commit it, diff it, and share it.

When the same setting is declared in both files, ANTHRACITE.md wins and the app shows a banner in Settings telling you which config values are being overridden.

`ANTHRACITE.md` — the policy spine

ANTHRACITE.md at the vault root is the single, user-authored contract for how a vault's content is interpreted. It is configuration, never ingested as a source. The onboarding wizard seeds it (your "Purpose" goes in ## Purpose), and you can edit it any time:

In-app: open it from ⌘K → Vault files → ANTHRACITE.md, from the schema-stale banner, or from Settings → Vault. The in-app editor has a rendered/markdown toggle and validates as you go.
On disk: it's just a Markdown file — edit it in any editor.

Parseable sections include ## How I take notes (plain-language capture + grouping; mention BuJo there for the standard signifier table), ## Notes for the assistant, ## Notes for the prioritizer, and ## Board (name + views). Advanced structured sections (## Journal rules, ## Composition, ## Collections, …) still work for power users and override derived policy when present. Anything missing falls back to sensible defaults, so a minimal file is fine. The full section-by-section guide is in Editing ANTHRACITE.md.

Cheap recompose vs. processing again

Editing ANTHRACITE.md only changes interpretation, so saving it triggers a recompose — instant, free, and makes no LLM calls: it re-parses existing extracted.md text and rewrites the board + tasks/*.md. Your manual board edits (completion, edited titles, pinned quadrants) are preserved across recompose because each task has a stable, content-derived id.

Processing again in full (re-reading pages + wiki rebuild via the LLM) is the separate, on-demand expensive path — the app shows a banner with a Process now button after an ANTHRACITE.md change so you can refresh the wiki when you actually need to.

`.anthracite/config.json` — operational settings

This file (inside the vault's .anthracite/ folder) holds the mechanism: LLM provider/model/endpoints, OCR backend selection, and other operational knobs. Most people never edit it by hand — Settings writes it for you — but you can open it from ⌘K → Vault files → config.json (raw, JSON-validated) or edit it on disk. Secrets like API keys go in the system keychain, not this file.

A typical llm / ocr block:

{
  "llm": {
    "provider": "mlx",
    "model": "mlx-community/GLM-OCR-bf16",
    "mlxEndpoint": "http://localhost:8080"
  },
  "ocr": {
    "preferredProvider": "mlx-glm-ocr",
    "mlxModel": "mlx-community/GLM-OCR-bf16",
    "mlxEndpoint": "http://localhost:8080"
  }
}

config.json vs state.json. .anthracite/config.json is your editable operational config. .anthracite/state.json (same folder) is machine-managed runtime state — it's where the local ingest token and webhook secret live (see Capturing content). There's also a global registry at ~/.anthracite/state.json that tracks your known vaults and which was last opened.

Vault layout

A vault is a folder with this structure:

my-vault/
  ANTHRACITE.md          # policy spine (human-authored)
  .anthracite/
    config.json          # operational settings (mechanism)
    state.json           # machine state: ingest token, webhook secret, …
  raw/                   # immutable captured sources
    <source-id>/
      original.*         # the original bytes (image, pdf, md, audio…)
      extracted.md       # normalized plain text (read / transcribed / scraped)
      meta.json          # provenance: connector, timestamps, content hash
    inbox/               # drop files here for the folder watcher
  wiki/                  # processed knowledge — linked Markdown pages
    sources/             # one summary page per ingested note
    concepts/            # recurring themes, methods, protocols
    entities/            # companies, products, tools, projects, places
    people/              # named individuals
    collections/         # auto-maintained groupings (policy in ## Collections)
  tasks/                 # processed task lists / board lanes (tasks/<lane>.md)

Because it's all plain files, the vault is Obsidian-native and yours to back up, sync, or version however you like. See Syncing vaults across devices for iCloud/Dropbox/git guidance and the one-machine-at-a-time rule.

One `ANTHRACITE.md` per vault — switching brains

The unit of policy is the vault: exactly one ANTHRACITE.md per vault. A genuinely separate context (Work vs. Personal) is a separate vault with its own policy. Each machine keeps a registry of known vaults at ~/.anthracite/state.json, and one backend process serves exactly one vault at a time. Switch vaults in Settings → Vault (the app prompts a guided restart), or — only when running from source; the packaged app ships no CLI — from the terminal:

anthracite init ~/Work          # create a vault and make it active
anthracite vault list           # show the registry
anthracite vault add ~/Personal # register without switching
anthracite vault use ~/Work     # set active (restart to load)