--- source_hash: ad79814ffb28a969f81687519d86e0755f6869dd0d99287ca7d030e87eaefab3 post: advanced folder: ari-os shape: doctrinal --- # Advanced — the default-off surface — Context Pack (for agents) Agent-facing context pack for the published `advanced` post. Needles below are copied **verbatim** from the `.mdx` body. The composing component (`content.ts`) has **no advanced-specific literals** — every needle on this page lives in the body. Reproduce commands exactly; do not paraphrase, re-hyphenate, or re-case. The Python package is `ari_os` (**underscore**). Two distinct tool entry points are load-bearing and easy to conflate: the **cortex tool** (`ari_os.tools.cortex`) runs features; the **control panel** (`ari_os.tools.arios`) flips settings — note `arios` is one word, no hyphen, no underscore. When the post and this pack disagree, the post wins — re-fetch and re-extract. --- ## 1. One-line gist ARI-OS ships a **power-user surface that is off by default** — knowledge graph, prediction, prefetch, mind-wander, EARS, LENS — all run through one cortex tool (`python3 -m ari_os.tools.cortex`) and are toggled through one control panel (`python3 -m ari_os.tools.arios cortex on|off`); the core brain works without any of it, and you turn pieces on deliberately, one at a time. --- ## 2. NEEDLES (verbatim — do not confabulate) ### The two entry points (exact — do not conflate) - `python3 -m ari_os.tools.cortex` — "the cortex tool" everything runs through. Module path is `ari_os.tools.cortex` (**underscore**). - `python3 -m ari_os.tools.arios cortex on|off` — "the control panel" where the toggles live. Module path is `ari_os.tools.arios` (**`arios` is one word** — no hyphen, no underscore). This is a different sub-tool from the cortex tool above. ### Knowledge graph (exact) - `python3 -m ari_os.tools.cortex kg extract` — "builds the graph from your memory." - `python3 -m ari_os.tools.cortex kg list` — "shows the entities and relations it found." - `python3 -m ari_os.tools.cortex kg stats` — "measures it, so you can see how dense the graph has become over time." ### Prediction and prefetch (exact) - `python3 -m ari_os.tools.cortex predict` — "surfaces what you are likely to need." - `python3 -m ari_os.tools.cortex prefetch --cwd ` — "warms context for a given working directory, so the brain is ready the moment you arrive." ### Mind-wander (exact) - `python3 -m ari_os.tools.cortex wander --focus ""` — use `--focus` to point the wander at a topic. - `python3 -m ari_os.tools.arios cortex wander on|off` — toggle the whole feature (control panel, not cortex tool). ### EARS — listening (exact) - `python3 -m ari_os.tools.cortex ears ` — ingests an audio file or a transcript; "the contents land in memory like any other note." - `python3 -m ari_os.tools.arios cortex ears on` — enable through the control panel. ### LENS — seeing (exact) - `python3 -m ari_os.tools.cortex lens ` — "Pass it a slug and it reads through that lens." - `python3 -m ari_os.tools.arios cortex lens on` — enable through the control panel. ### Embeddings backend (exact — four choices, one command) - `python3 -m ari_os.tools.arios cortex embeddings auto|google|ollama|off` - `auto` — "picks a sensible backend for you." - `google` — pins to the Google provider. - `ollama` — pins to the Ollama provider. - `off` — "runs without embeddings at all." ### MCP gating (exact — load-bearing) - The MCP tools `brain.see` and `brain.lens` "stay off until both LENS and a local vision model are enabled. Without the model, there is nothing to see with." Both conditions, not either. ### The six surfaces (SurfaceList — all `kind: "off by default"`) - `Knowledge graph` — "Extract entities and relations from memory into a graph you can list and measure." - `Prediction` — "Surface what you are likely to need next." - `Prefetch` — "Warm context for a working directory before you start." - `Mind-wander` — "Now and then, surface a memory you had set aside." - `EARS` — "Ingest audio or a transcript into memory." - `LENS` — "Apply a visual or aesthetic lens. Needs a local vision model." ### Diagram asset (exact) - `src="/posts/ari-os/kg.png"` - `alt="A knowledge graph extracted from memory"` - caption: "Entities and relations, extracted from memory into a graph you can list and measure." ### Pullquote (exact) - `Most of this surface ships off. You turn it on when you want it, not before.` ### FAQ (3 — exact Q/A) - "Is any of this on by default?" → "No. Most of this surface ships off. Turn pieces on deliberately, one at a time, when you decide you want them." - "What do EARS and LENS need?" → "LENS, and the vision parts of EARS, need a local vision model. The plain audio and transcript path of EARS does not." - "Will turning these on slow things down?" → "Keep them off unless you want them. The core brain works without them, so you only carry the cost of what you switch on." ### Internal doc link (exact path from the body) - Brain page: `/documents/ari-os/brain` ### Frontmatter (exact) - `slug: advanced` - `title: "Advanced: the default-off surface"` - `date: 2026-06-15` - `folder: ari-os` - `type: how-to` - `status: published` - `summary: "The power-user surface that ships switched off: knowledge graph, prediction, prefetch, mind-wander, EARS, and LENS."` - `related: [brain, using-it, overview]` ### Load-bearing prose (exact sentences) - "Most of this surface is off by default. The core brain works without any of it. Turn pieces on only when you want them, one at a time." - "Everything here runs through the cortex tool, `python3 -m ari_os.tools.cortex`, and the toggles live in the control panel, `python3 -m ari_os.tools.arios cortex on|off`." - "The vision parts of EARS need a local vision model. The plain audio and transcript path does not." - "The MCP tools `brain.see` and `brain.lens` stay off until both LENS and a local vision model are enabled. Without the model, there is nothing to see with." ### Cross-file note (from `content.ts`) - The shared `ARI_OS` object in `components/ari-os/content.ts` has **no advanced-page literals** (no kg/wander/ears/lens/prefetch/predict entries). It carries only brand-level fields (`name`, `tagline`, `version`, `githubUrl`, `setupHref`, `install`, `reversibleNote`). The `memory.lines` string `"Now and then it surfaces a memory you had set aside."` is the closest sibling prose and echoes the Mind-wander surface description, but it lives on the **overview**, not here. Do not source advanced needles from `content.ts`. --- ## 3. GIST (the procedure condensed) The advanced page is a **catalogue of six off-by-default surfaces**, each with the same shape: a `cortex` subcommand to use it and an `arios cortex on|off` toggle to switch it. The surfaces are **knowledge graph** (`kg extract` / `kg list` / `kg stats`), **prediction** (`predict`), **prefetch** (`prefetch --cwd `), **mind-wander** (`wander --focus ""`), **EARS** (`ears `), and **LENS** (`lens `). Embeddings get their own control-panel switch with four backends (`embeddings auto|google|ollama|off`). The two entry points are the page's chief trap. `ari_os.tools.cortex` is the **feature runner**; `ari_os.tools.arios` is the **settings panel**. Both are real, both are reached as Python modules, and the only difference is the trailing subtool name (`cortex` vs `arios`). Commands like `arios cortex wander on` and `cortex wander --focus "..."` are not interchangeable — the first flips a setting, the second does the work. The through-line is **opt-in cost**. The core brain works without any of this; you only carry the weight of what you switch on. The single hard gate is vision: `brain.see` and `brain.lens` MCP tools stay off until **both LENS and a local vision model** are enabled, because without the model "there is nothing to see with." EARS splits along the same seam — audio and transcript ingestion work without a vision model, the vision parts of EARS do not. --- ## 4. KEY LEARNINGS 1. **Default-off is the contract.** Every surface on this page ships off and the core brain works without any of it. Any agent that asserts one of these features is on out of the box is confabulating. 2. **Two entry points, easy to conflate.** `python3 -m ari_os.tools.cortex` runs features; `python3 -m ari_os.tools.arios cortex on|off` flips settings. The trailing subtool name is the only tell (`cortex` vs `arios`). Both are real modules; do not "normalise" one into the other. 3. **Settings toggles use the control panel, not the cortex tool.** `arios cortex wander on|off`, `arios cortex ears on`, `arios cortex lens on`, and `arios cortex embeddings auto|google|ollama|off` all go through `ari_os.tools.arios`. Running them through `ari_os.tools.cortex` is wrong. 4. **Embeddings is a four-way switch, not a boolean.** `auto` picks, `google` and `ollama` pin, `off` disables. Treat `off` as a real mode: the brain runs without embeddings at all. 5. **Vision is gated on two conditions, not one.** The `brain.see` and `brain.lens` MCP tools require **both** LENS enabled **and** a local vision model. "Without the model, there is nothing to see with." 6. **EARS splits along the vision seam.** Audio and transcript ingestion work without a vision model; only the vision parts of EARS need one. Do not assert EARS as a whole requires a vision model. 7. **Knowledge graph is three subcommands, not one verb.** `extract` builds, `list` enumerates entities and relations, `stats` measures density over time. They are distinct and not interchangeable. 8. **Prefetch takes `--cwd `; predict takes no args.** Prefetch warms context for a specific working directory; predict surfaces what you are likely to need from where you are. 9. **Needles live in the body, not in the component.** Unlike the install page, `content.ts` has no advanced literals. Source every needle from the `.mdx` body; do not invent `ARI_OS.advanced` fields that do not exist. --- ## 5. FILE INDEX (load-bearing — re-fetch to verify needles) - `content/posts/ari-os/advanced.mdx` — **primary and only source for this page's needles.** Frontmatter (`slug: advanced`, `folder: ari-os`, `type: how-to`) plus the SurfaceList, all cortex and arios commands, the embeddings switch, MCP gating, diagram asset, pullquote, and 3-item FAQ. **All needles are here.** - `components/ari-os/content.ts` — the shared `ARI_OS` object. Confirmed to have **no advanced-specific literals**. Read it only to verify that no `ARI_OS.advanced` / `ARI_OS.surfaces` field exists; do not extract advanced needles from it. - `content/posts/ari-os/kg.png` — the knowledge graph diagram referenced by the single `` on the page. External refs to re-fetch if stale: - `https://github.com/PUSHINGSQUARES/ARI-OS` — confirm the `ari_os.tools.cortex` and `ari_os.tools.arios` module paths still exist and the subcommand surface (kg / predict / prefetch / wander / ears / lens / embeddings) matches what the body shows. > Backfilled 2026-07-18 from the published body; not needle-extracted at thought-time.