---
source_hash: 61ef13d1e72be29d829930512b57aed522a32dd806d61144cb06ed54242731a9
post: /posts/ari-os/brain
folder: ari-os
shape: doctrinal
---

# Get the most from the Cortex brain — Context Pack (for agents)

Agent-facing context pack for the published post. Every string under NEEDLES is
copied **verbatim** from the published body (`brain.mdx`) or the cited fidget
components (`CortexRegionMap.tsx`, `ConsolidationCompressor.tsx`). Reproduce
them exactly — do not paraphrase, re-case, re-hyphenate, or "fix" punctuation.
When the post and this pack disagree, **the post wins** — re-fetch and
re-extract.

> Scope note: this is the **brain doc page** (memory layer how-to). The
> `components/ari-os/content.ts` file holds literals for the **ARI-OS product
> landing page**, not this doc — its needles are NOT valid here. The brain
> doc's needles live in the `.mdx` body plus the two shared block components.

---

## 1. One-line gist

The Cortex brain is the **local-first memory layer of ARI-OS** — it reads and
writes through the `ari-os-cortex` MCP server, stores memory in **regions**,
**consolidates** raw capture down through tiers to durable facts without
throwing lineage away, and reweights recall through **10 modes** — nothing
leaves your machine to make it work.

---

## 2. NEEDLES (verbatim — do not confabulate)

### The load-bearing principle (Pullquote, body)

- **`Files own the truth. The brain owns the connections.`**

### The three moves

1. **remember** — "remember what matters"
2. **consolidate** — "consolidate it over time"
3. **recall** — "recall it when it counts"
- Diagram caption (exact): **`The three moves of the brain: remember what matters, consolidate it over time, recall it when it counts.`**
- Diagram asset path (exact): **`/posts/ari-os/brain-flow.png`**

### MCP server + tool signatures (exact — do not alter arg names/defaults)

- MCP server name: **`ari-os-cortex`** ("reads and writes through the `ari-os-cortex` MCP server")
- **`brain.remember(text, layer='semantic', source)`** — `layer` says where the memory sits; `source` records where it came from.
- **`brain.recall(query, mode='default', k=12, token_budget=4000)`** — `query` = what you are looking for; `mode` shapes ranking; `k` = candidate count; `token_budget` caps result size.
- Dedup: **by the sha256 of the text** ("writing the same thing twice does not create a duplicate").

### CLI commands (exact module paths — run verbatim)

- **`python3 -m ari_os.tools.cortex ingest --path <file>`** — ingest a markdown note. Module is `ari_os.tools.cortex` (underscore).
- **`python3 -m ari_os.tools.cortex retrieve -q "<query>" --cwd "$PWD" --mode <mode>`** — recall from CLI. `--cwd` is the **workspace gate** (scopes recall to the current project).
- **`python3 -m ari_os.tools.arios cortex mode <name>`** — switch active mode. NOTE: module here is **`ari_os.tools.arios`** (different module from `ari_os.tools.cortex` above — verbatim, do not "correct").
- **`cortex mode list|get|set <name>`** — list / get / set the mode on the cortex tool.
- **`python3 -m ari_os.tools.cortex dream`** — run a full dream pass (distil + decay).
- **`python3 -m ari_os.tools.cortex distill --tier session|daily|weekly`** — run a single tier on its own.

### Memory file layout (exact)

- **`$ARI_OS_HOME/memories/<context>/<UTC-timestamp>.md`** — "The folder is the context, and the timestamp keeps each note in order." Env var is `ARI_OS_HOME`.
- "write a markdown note first, then ingest it. **The note is the canonical record.** Ingesting it just teaches the brain the connections."

### The 10 retrieval modes (exact `name` tokens, from the `SurfaceList` block — verbatim)

| name         | desc (verbatim)                                                              |
| ------------ | ---------------------------------------------------------------------------- |
| `default`    | Balanced ranking for everyday work. The sensible starting point.             |
| `focus`      | Tight and on-task. Pulls only what is closest to the job in front of you.    |
| `wide`       | Casts a broad net. Surfaces more candidates from further out.                |
| `synthesis`  | Favours connections across memories, for joining ideas into a whole.         |
| `deep`       | Slower, heavier ranking for hard reasoning and careful work.                 |
| `creative`   | Loosens the ranking to surface unexpected links and adjacent ideas.          |
| `visual`     | Weights the vision region, for image descriptions and visual work.           |
| `recall`     | Fast lookup. Reaches for specific facts you have stored before.              |
| `adhd`       | Short, punchy context that respects a wandering attention span.              |
| `dyslexic`   | Plain, skimmable context shaped for reading ease.                            |

- Body framing: **"Same brain, different posture."** — "There are 10 retrieval modes."

### Regions (canonical — 5 keys, from `CortexRegionMap.tsx` `REGIONS` array)

| key         | label      | description                                        | example                    |
| ----------- | ---------- | -------------------------------------------------- | -------------------------- |
| `language`  | Language   | Prompts and the meaning you give them.             | The brief you wrote this morning. |
| `vision`    | Vision     | References, style, what things look like.          | A saved lighting reference.|
| `episodic`  | Episodic   | Timestamped events: what happened, when.           | Yesterday's shipped build. |
| `structure` | Structure  | Projects, files, how things are laid out.          | This site's folder map.    |
| `identity`  | Identity   | Who you are, your rules, your voice. **Never decays.** | Your house style.      |

- **DISCREPANCY (flag, do not collapse):** the body prose lists six coverage areas — "Language comprehension, language production, vision, episodic events, spatial and project structure, and identity" — but the canonical interactive `CortexRegionMap` has **five** region keys (`language` / `vision` / `episodic` / `structure` / `identity`). If asked "how many regions," answer **5** and cite the component; the prose splits `language` into comprehension + production and folds "spatial and project structure" into one `structure` region.

### Consolidation tiers (canonical — from `ConsolidationCompressor.tsx` `TIERS` array)

| key      | label   | tokens / year | description                                                         |
| -------- | ------- | ------------- | ------------------------------------------------------------------- |
| `raw`    | Raw     | **22,000,000**| Every session captured as-is. Maximum fidelity, maximum noise.      |
| `session`| Session | **8,000,000** | Raw sessions distilled into per-session digests. Noise removed.     |
| `daily`  | Daily   | **3,200,000** | Sessions collapsed into a daily summary. Patterns begin to form.    |
| `weekly` | Weekly  | **1,400,000** | Durable thinking extracted across a week. Signal accumulating.      |
| `fact`   | Fact    | **600,000**   | Promoted permanent facts. Dense, queryable, long-lived.             |

- Body prose names three middle tiers ("session, daily, and weekly") and the end state ("a durable fact"); the canonical component adds `raw` as the start and `fact` as the end. Full pipeline: **`raw → session → daily → weekly → fact`**.
- Lineage invariant: **"it never throws the lineage away. You can always walk a durable fact back to the note it came from."** / "Memories compress, but lineage still walks back to the original source." Fidget caption fragment: `still walks back to source`.
- Dream framing: **"a deterministic distil plus decay pass."** — "It compresses old memories down through tiers while their importance fades."

### Embeddings (exact model names, dims, URL)

- Default backend: **Ollama** ("runs on your machine").
- Embedding model: **`nomic-embed-text`** — produces **768-dimensional vectors**.
- Language model: **`gemma3:4b`** — "handles the local language work".
- Pull commands (exact): `ollama pull nomic-embed-text` and `ollama pull gemma3:4b`.
- **`OLLAMA_URL`** defaults to **`http://127.0.0.1:11434`** ("a standard local Ollama needs no extra configuration").
- Fallback: **"ranked keyword search"** when no Ollama is running — "less precise than vector ranking, but the brain still works, fully offline, with nothing to set up."

### Related links (exact, from body)

- Tuning / custom modes / deeper mechanics → **`/documents/ari-os/advanced`**
- Brain in a working session → **`/documents/ari-os/using-it`**
- Bigger picture → **`/documents/ari-os/overview`**
- Body `related:` frontmatter → **`[overview, using-it, advanced]`**

---

## 3. GIST (the argument condensed)

The Cortex brain is ARI-OS's answer to a single failure: **a session with no
memory boots blind** — you re-explain yourself, then the window closes and it
all drains away (the `LeakyBucket` fidget). The brain plugs the leak so each
new session starts **knowing, not guessing**.

Memory is shaped, not piled. It is split into **regions** that mirror
neuroanatomy (language, vision, episodic, structure, identity), so recall
returns **grouped** answers instead of a heap. Two paths in (MCP
`brain.remember`, or write a markdown note and `ingest` it — the note is the
canonical record) and two paths out (MCP `brain.recall`, or the CLI
`retrieve` command whose `--cwd` gate scopes recall to the project in front of
you).

The same brain reweights retrieval through **10 modes** — "same brain, different
posture" — so one store serves focus work, broad synthesis, visual lookup, or
reading-ease context. Raw capture is **consolidated** by `dream`: a
deterministic distil + decay pass that compresses through session → daily →
weekly tiers down to durable facts, **never throwing lineage away**. The whole
thing runs local-first through the `ari-os-cortex` MCP server, embeds with
Ollama (`nomic-embed-text`, `gemma3:4b`) on `http://127.0.0.1:11434`, and
falls back to ranked keyword search offline.

The thesis lands in the closing pullquote — **Files own the truth. The brain
owns the connections.** — which is the invariant that makes consolidation
safe: because files are canonical and the brain only owns the connections,
every memory can be compressed, decayed, or rebuilt while still walking back
to its source.

---

## 4. KEY LEARNINGS

1. **Memory plugs a leak, not a search box.** A session with no memory "boots blind"; the win is starting each session knowing instead of guessing. This is recall shaped by region, not a typed query.
2. **Files own the truth; the brain owns the connections.** The markdown note is the canonical record — ingesting it "just teaches the brain the connections." This is why compression and decay are safe: nothing is destroyed, only re-weighted.
3. **`--cwd` is the workspace gate.** Recall is scoped to the current project by default — "the context that belongs to the project in front of you and not everything you have ever written." Widening is opt-in.
4. **Modes are posture, not separate brains.** Same store, ten retrieval postures (`default`/`focus`/`wide`/`synthesis`/`deep`/`creative`/`visual`/`recall`/`adhd`/`dyslexic`). Switching is a one-liner; the underlying data does not move.
5. **Consolidation is lossless-by-lineage, not lossless-by-storage.** `dream` compresses raw (22M tok/yr) down toward durable facts (600K tok/yr) through tiers, fading importance but keeping the lineage walk to source. The point is "small and dense while losing nothing" — where "nothing" means the traceable provenance, not the byte-for-byte text.
6. **Local-first is the privacy contract.** "Nothing leaves your machine to make it work." Embeddings run on Ollama on `127.0.0.1:11434`; with no Ollama, recall degrades gracefully to ranked keyword search — "the brain still works, fully offline."
7. **Dedup is content-addressed.** `brain.remember` dedupes by the sha256 of the text, so replaying the same memory does not double-store it — important when ingesting notes that overlap.
8. **Module paths are verbatim and inconsistent on purpose.** Mode switching is `ari_os.tools.arios cortex mode` (note `arios`, not `cortex`); every other cortex command is `ari_os.tools.cortex`. Do not "normalise" either path — copy them exactly or the command will not resolve.

---

## 5. FILE INDEX (load-bearing refs to re-fetch)

- **Post body (canonical source for almost all needles):** `content/posts/ari-os/brain.mdx` — frontmatter (`slug: brain`, `folder: ari-os`, `type: long-read`, `status: published`, `related: [overview, using-it, advanced]`) plus all MCP signatures, CLI commands, the 10-mode `SurfaceList` block, and the embeddings section.
- **Region map component (canonical 5 regions):** `components/blocks/CortexRegionMap.tsx` — `REGIONS` array (shared with the `memory/cortex` post). NOTE: body prose enumerates 6 coverage areas but the canonical component has 5 keys; trust the component for the count.
- **Consolidation component (canonical 5 tiers + exact token counts):** `components/blocks/ConsolidationCompressor.tsx` — `TIERS` array (shared with the `memory/cortex` post). Token-per-year figures and `raw → fact` pipeline live here.
- **Other fidgets cited (illustrative, not config):** `LeakyBucket.tsx`, `EvidenceDigFidget.tsx`, `SurfaceList.tsx`, plus `Diagram` and `Pullquote` from `@/components/blocks`.
- **NOT a needle source for this page:** `components/ari-os/content.ts` — that is the ARI-OS **product landing page** object (`ARI_OS.name`, `tagline`, `githubUrl`, `install` commands). It is NOT imported by `brain.mdx` and none of its literals are valid for this doc. (Read per cross-plan guidance; documented here as a negative ref so an agent does not lift `Software 1.0 · Now open-source` etc. into this pack.)
- **Shared block barrel:** `@/components/blocks` — exports `Code`, `SurfaceList`, `CortexRegionMap`, `ConsolidationCompressor`, `EvidenceDigFidget`, `LeakyBucket`, `Diagram`, `Pullquote`.

External refs to re-fetch if stale:
- `nomic-embed-text` / `gemma3:4b` — verify model tags still resolve on Ollama.
- `http://127.0.0.1:11434` — verify the default `OLLAMA_URL` has not moved.

> Backfilled 2026-07-18 from the published body; not needle-extracted at thought-time.