Ari’s Space*   est. 2026
Skip to content
ari*s space[ a. ]
← Libraryari os / 2026-06-15

Get the most from the Cortex brain

Save, retrieve and inspect durable context. A source-checked guide to Cortex memory, mode settings, consolidation and the limits of the original local-only guarantees.

8 parts / Hover to explore. Click to read.

Save, retrieve and inspect durable context. A source-checked guide to Cortex memory, mode settings, consolidation and the limits of the original local-only guarantees.

Markdown note -> ingest -+
                         |
remember(text) ----------+
                         v
                       index
                         |
                       recall
                         |
                  inspect sources
The remember skill keeps a Markdown record; the MCP write indexes text directly. Retrieval and source quality still need checking, and local storage does not establish processing locality.
Context Pack (for agents)

Cortex gives ARI-OS a memory layer across sessions, with reads and writes exposed through the ari-os-cortex MCP server. You can save useful material, retrieve it for a task and create summaries of earlier capture. The useful question is what the next session can actually find and verify.

The original June 2026 guide described a wholly local setup. Local storage is still part of the design, but processing depends on the configured endpoints and backends. A local database does not establish that nothing leaves the machine.

This revision distinguishes the original examples from public source at commit 85bba5f. The checks below are source inspection, not a runtime test of ARI-OS.

Saving the useful part of a session gives the next one somewhere to begin. It still has to retrieve the right material and judge whether it applies.

Remember, consolidate, recall
Save material, produce summaries, retrieve and inspect the result.

Understand the region map

The brain groups context into regions associated with identity, language, vision, episodes and structure. The interactive map is a teaching illustration of those ideas.

CORTEX REGION MAP
Select a region to see what memory lives there.

The inspected retrieval output has seven keys: vmpfc, frontoparietal, hippocampus, wernicke, broca, occipital and parietal. The five buttons above are a simplified view, not the runtime schema or evidence that the system works like a biological brain.

Choose how to save a memory

The file-based remember skill prescribes a Markdown note at $ARI_OS_HOME/memories/<context>/<UTC-timestamp>.md, followed by ingestion. The context folder groups notes and the UTC timestamp orders them. Keep that file as the readable record.

python3 -m ari_os.tools.cortex ingest --path <file>

The MCP tool brain.remember(text, layer='semantic', source) takes a different path: it indexes supplied text directly and does not create that Markdown note. layer labels the memory and source identifies its origin.

When source is omitted, the wrapper trims the text and uses the first 16 hexadecimal characters of its SHA-256 hash to form the source ID. An explicit source can identify a replaceable entry. Do not assume every write is unconditional content-based deduplication or that every indexed item has a file behind it. See the remember skill and indexing implementation.

Retrieve and check the result

The MCP reference call is brain.recall(query, mode='default', k=12, token_budget=4000). The query supplies the question; the mode influences ranking; k feeds the vector-candidate count. It is not a count of every candidate from every retrieval path.

The token budget is approximate: the inspected packer estimates words multiplied by 1.3 and can admit an oversized first chunk. Treat 4000 as a requested packing budget, not a hard protection against filling the conversation.

The CLI example supplies a working directory:

python3 -m ari_os.tools.cortex retrieve -q "<query>" --cwd "$PWD" --mode <mode>

--cwd is retrieval context, not an access-control boundary. The inspected path recognises workspace names under workspaces/<name>; other paths may have no workspace filter. Automatic posture can choose global retrieval, and adjacency can include chunks beyond the selected workspace. MCP recall has no cwd argument in this reference signature.

These limits come from the retrieval implementation. Inspect the returned sources before treating the answer as project-specific.

the evidence dig

Toggle the example layers, then play the illustration. No model or source check runs.

The fidget illustrates adding context to an answer. More context is not a guarantee of a better answer; relevance and source quality still need judgement.

Use modes as parameter presets

The ten names remain useful reference points. Their meanings below describe the inspected definitions, not measured speed or accessibility outcomes.

  • defaultmodeBalanced regional weights for the baseline retrieval setup.
  • focusmodeNarrower preset candidate and adjacency settings, with procedural/workspace emphasis.
  • widemodeA broader legacy preset, distinct from creative.
  • synthesismodeCross-region weights and an expansion preference, subject to call settings and gates.
  • deepmodeLarger preset candidate counts with procedural and episodic emphasis.
  • creativemodeIdentity, visual and higher-tier emphasis.
  • visualmodeGreater weight for the occipital region.
  • recallmodeEpisodic and language weighting, not a guaranteed fast lookup.
  • adhdmodeDefault retrieval sizes and weights with additional council settings; no proven short-output transformation.
  • dyslexicmodeDefault retrieval sizes and weights with additional council settings; no proven reading-ease transformation.

The original control-panel example records a global mode preference:

python3 -m ari_os.tools.arios cortex mode <name>

The Cortex CLI separately provides mode list, mode get, mode set <name> and mode auto. Its per-workspace selection and the control-panel preference use separate stores. Direct recall and retrieve calls also supply an explicit mode, defaulting to default.

Explicit call values such as k=12 and token_budget=4000 override the corresponding preset values. A selected name alone doesn't demonstrate that every mode setting took effect. See the mode definitions and control-panel setter.

Consolidate without confusing a summary with the source

Dream combines summarisation and importance decay. The inspected session, daily and weekly distillation passes require an enabled LLM; disabled passes return zero. That makes the whole operation more than a deterministic compression routine.

CONSOLIDATION COMPRESSOR
22.0M
TOKENS / YEAR
RawSessionDailyWeeklyFact
Raw

Illustrative stages and token counts, not measured storage or a guaranteed runtime pipeline.

Every session captured as-is. Maximum fidelity, maximum noise.

The slider's five stages and 22-million-to-600,000 token figures are a design illustration. They are not measurements of this installation or proof of a fifth automatic distillation tier. The inspected passes create tiers 0 to 1, 1 to 2 and 2 to 3.

python3 -m ari_os.tools.cortex dream

You can request a named tier using the original reference form below. Choose one of session, daily or weekly; the vertical bars mean alternatives, not a shell pipeline to paste literally.

python3 -m ari_os.tools.cortex distill --tier session|daily|weekly

Distillation adds summary rows, parent IDs and connections while retaining input rows during that operation. It writes artefacts under $ARI_OS_HOME/consolidation. This is not evidence that the stored data shrinks without loss.

Lineage records help you trace a summary, but they are not a forever guarantee. Re-ingesting a source replaces its old chunks and can leave a parent missing. A source identifier may not name an existing file. Keep and inspect the underlying records when the claim matters.

The inspected decay pass reduces importance by 3% for previously retrieved chunks whose last retrieval was more than seven days ago. It has no identity-region exemption. See distillation and dream.

Check the embedding path before relying on it

The original Ollama setup uses nomic-embed-text, configured for 768-dimensional embeddings, and gemma3:4b for local language work:

ollama pull nomic-embed-text
ollama pull gemma3:4b

OLLAMA_URL defaults to http://127.0.0.1:11434. The URL, model and language backend can be configured, so inspect their actual destinations rather than inferring locality from those defaults.

The old guide promised keyword recall when Ollama was unavailable. The inspected retrieval path calls the Ollama embedding client before its full-text search and can fail at that call. A separate embedding API advertises an off/lexical mode, but this retrieval path does not use it. That is an integration gap found in source, not a reproduced runtime result.

The control panel's embeddings setting records a preference; it does not demonstrate that this direct client honours it. The embedding source and retrieval path need checking together before promising an offline fallback.

Keep the record you can verify

Files own the truth. The brain owns the connections.

That is the intended division of responsibility. Save the meaningful record, inspect what recall returned and follow important claims back to their source.

Use Advanced for optional surfaces, Using it for the session commands and Overview for the working arrangement.

[ comments ]

guests welcome. members show first in the list

members

  • Member take: local-first memory is the only way I trust a long project. Cloud chat forgets me every week.

    member · desk · Wed, 29 Jul 2026 21:32:56 GMT

  • Also: scope recall by cwd or the brain hands you the wrong client.

    member · desk · Thu, 30 Jul 2026 21:32:56 GMT

guests

  • Guest here — still reading. The leaky bucket image clicked for me.

    guest · Riley · Fri, 31 Jul 2026 09:32:56 GMT

  • Anonymous guest. Wondering if Atkinson body + VT323 chrome is the right split for long essays.

    guest · Fri, 31 Jul 2026 18:32:56 GMT

1 / 10