47%
·
opus-4.7
·
WORKSPACE
·
main*
·
2🛠
·
02:41
Surface 1
Voice
{'~/.claude/CLAUDE.md'}
{'~/.codex/AGENTS.md'}
How Claude talks to you. Markers, header tiers, mono signals, paragraph length, where decisions live.
Surface 2
Interface
{'~/.claude/scripts/statusline.py'}
{'~/.claude/settings.json'}
How you read what's happening. Persistent, glanceable, colour-coded by zone.
#
THE headline of the reply (max 1)
##
Main sections (status, decision, design, question)
###
Sub-sections inside one of those
####
Inline labels and micro-groupings
47%
·
opus-4.7
·
WORKSPACE
·
main*
·
2🛠
·
02:41
47% context: green <50, yellow 50 to 75, orange 75 to 90, red over 90
opus-4.7 model: opus magenta, sonnet cyan, haiku grey
WORKSPACE per-prefix brand colour
main* white clean, yellow dirty, red on conflict
2🛠 dispatch worker count: yellow when 4 or more
02:41 session clock, always dim grey
That's the mistake. The model isn't supposed to be the centre of your stack. The contracts you give the model are.
## The three layers that fix it
Once I worked through it, the pattern came out as three rules. They're boring on purpose. The whole point is that they're things you can build incrementally without learning anything exotic.
### 1. Markdown is the contract
A capability is a markdown file. The model reads it and follows it. Not a Python function calling an API. Not a model-specific prompt buried in code. A document that says: here's what to do, here's the format, here are the anti-rules.
Any model that can read English can run it. Claude has its own way to discover the file. Codex has another. Kimi has another. All three read the same file when pointed at it. The file is the contract. The harness is just how it gets opened.
This is the most counterintuitive part of the pattern for engineers, because the engineer's instinct is to wrap things in code. Wrapping it in code is what makes it model-specific. Leaving it as a document is what makes it portable.
### 2. Files are the memory
Long-term context lives in shared markdown on disk at a stable path. Any tool, any model, any session, reads the same files.
When I learn something about how I work (a preference, a recurring mistake to avoid, a belief about how a project should run), it goes into a memory file. When the next session starts, whatever harness I'm in, that session loads the same context. The memory doesn't know which model is reading it. It doesn't need to.
The price of this is discipline about the format. Every memory file has the same frontmatter shape. Every entry has the same fields. The benefit is a single source of truth that survives every model swap and every harness migration.
### 3. CLIs are the tools
Anything that needs deterministic execution (search, similarity, embeddings, transformations) is a command-line program. Models shell out.
A model can't reliably compute cosine similarity. A Python script can. So the script lives at the shell, the model invokes it with arguments, and gets JSON back. The model handles judgement. The script handles math. Both layers are model-agnostic by construction.
## What this buys you
Once the toolkit is portable, the model becomes a knob, not a foundation. You're not choosing one model and building your life on it. You're choosing the right model for the task in front of you, and the toolkit you use to express the task doesn't care.
Hard reasoning task? Reach for the biggest model. Mechanical refactor across forty files? Reach for the cheapest fast one. Need to read a hundred-thousand-line transcript? Reach for whichever has the longest context window today.
Same capabilities every time. No port. No drift. No "I'll re-add that feature when I get around to it."
The shape of the choice changes. It stops being "which model do I commit to?" and starts being "which model serves this turn?". Those are very different questions and they produce very different working habits.
## The anti-pattern this kills
> Vendor SDKs as your primary interface.
Every time you wrap your capability in `import anthropic` or `import openai`, you've built a model-specific abstraction. It will work beautifully right up until the moment you want to switch.
I'm not saying never use the SDKs. I'm saying don't let them be the surface your capabilities are defined against. The SDK is fine as an internal detail of one specific tool. It's a problem as the place where the behaviour lives.
The portable version doesn't import anything from the model vendor. It writes a markdown file. The vendor is whatever happens to be reading the file that session.
## The one rule that does the most work
> Build the interface, not the integration.
An integration ties you to one vendor. An interface accepts any vendor that can meet its contract. Markdown contracts, files, and CLIs are all interfaces. SDKs are integrations.
When in doubt, lean interface. Even when the integration is more ergonomic today. Even when "you're only using one model anyway, why bother." The cost of writing it as an interface is small. The cost of unwinding an integration after it's grown roots is enormous.
## What it doesn't promise
This isn't model-agnostic in the sense that every model is equally good at every task. They aren't. Claude reasons differently from GPT differently from Kimi. Each has things it's better at and things it's worse at.
What this pattern gives you is the freedom to pick the best one for the job without throwing away your work. The capability is portable. The choice of model is still a judgement call. You just don't pay the rebuild tax anymore.
You also still need taste. The toolkit being portable doesn't mean every task should be run on every model. You're still making real engineering choices about which model belongs where, in the same way you'd make choices about which database belongs where. The point is the choice is reversible.
## How this changes the way you build
A few practical knock-ons once you've adopted the pattern:
You stop reading "model X just released" announcements as a threat or a chore. You read them as "could be a new option for the knob." The release doesn't invalidate your toolkit. It expands the set of models that can plug into it.
You stop optimising your prompts for one model's quirks. You optimise the contract for clarity instead. A clear contract reads well in every model. A model-specific quirk-prompt reads weirdly in the others.
You stop fearing the cost surprise from any single vendor. If one model gets too expensive for a task, you reach for a cheaper one and the toolkit doesn't notice.
You stop equating "which AI tool I use" with "which way I work." You can switch harnesses freely and your workflow follows you.
## The takeaway
The model is the replaceable part. Your contracts are the asset.
If your toolkit can't survive a model swap, you don't have a toolkit. You have a vendor relationship.
Build the interface, not the integration.
//
---
## A second brain for taste, not for notes
URL: https://aris-space.com/documents/tools-and-plugins/lens
Date: 2026-05-21
import { LensFidget } from '@/components/blocks/LensFidget'
# A second brain for taste, not for notes
Creative reference libraries have a rot problem. You save references. You forget them. Your aesthetic exists somewhere between your eyes and your past work. It's not a document anyone can query.
So you go to brief a workspace. A collaborator. A process. And you're re-explaining your visual sense from scratch. Every time.
The fix isn't a better folder structure. It's distillation. Take the reference, extract the principle, throw the reference away.
## Two streams
There's a hard line between two things most people mash together.
{`your files/ # canonical: notes, transcripts, decisions, outputs
index.db # derived: SQLite + a vector extension
hooks/
session-start # run retrieval, inject top-k context into turn 1
on-change # re-index a file the moment it is edited
jobs/
nightly # consolidate raw -> digests -> facts (the "sleep")
adapters/
injected-context # default: drop context into the prompt preamble
mcp-server # for tools that speak Model Context Protocol`}
The seven moves:
1. **Keep your files canonical.** Your notes and transcripts stay the source of truth. The brain reads them, it never replaces them.
2. **Build a derived index.** SQLite plus a vector extension is enough. Chunk each file, embed it, and tag it with a region and a memory layer.
3. **Wire the deterministic edges.** Prompt to answer. Image to caption. Everything inside one project to everything else inside it.
4. **Let co-activation do the rest.** When two chunks keep getting retrieved together, strengthen the edge between them. Let unused edges fade.
5. **Auto-inject at session start.** A start-up hook runs retrieval and drops the top results into the model's first turn, organised by region. No one has to ask.
6. **Re-index on change, consolidate at night.** A file-change hook keeps the index fresh. A nightly job distils raw capture into durable facts.
7. **Stay model-agnostic.** Expose the brain through injected context, a thin adapter, or an MCP server. Any model can read it. The next model can too.
## What it unlocks for any LLM
The difference is not subtle. It is the gap between a tool that starts cold and one that starts knowing.
- Every session boots with the right context already loaded, shaped the way a brain organises it.
- The brain volunteers what is relevant instead of waiting to be queried. Recall, not search.
- It learns your patterns. Over weeks it notices which things fire together and surfaces them before you think to look.
- A year of raw thinking lives in a small, dense, rebuildable store, with nothing lost.
- It works across every model you use today, and the one you switch to next month.
Familiarize yourself with the Pushing Squares website, then evaluate
what needs to be done for CBA, Fuzz, Subtract to be done and sellable
by the end of the night.
Twenty five words. No spec. No file paths. No list of steps. No mention of checkout, signing, pricing, marketing footage, or which pages to build.
About two hours later there were product pages live on the site. Real checkout. Real signed builds. Real marketing footage rendered from scratch. My total input for the whole run was a handful of "status?" check-ins and one round of notes.
"status?"
"go ahead"
"can you spin up a local host for me to QC"
That was most of it. While five workers built, signed, and rendered in parallel, and two more waited on their inputs, I mostly asked how it was going. I was an orchestrator, not a typist.
{/* DIAGRAM 1 — parallel vs chained. Top row: 5 workers running at once. Bottom: the 2 dependent workers firing only after their inputs land. TODO: art. */}
Don't include the images for the effects we don't have images for,
just use the gallery for the ones I provided, but mention all of the
effects below in text. Other than that, everything looks perfect.
One note. Then:
perfect merge and deploy live to the site via vercel plz
That is the shape of being in the loop properly. Not writing the work. Not babysitting every step. Just sitting at the two or three gates that actually need a human: is this right, and should it go live.
{/* DIAGRAM 2 — the review gates. Staged preview, the one round of notes, the human go-live click. TODO: art. */}
{`python3 -m ari_os.tools.cortex kg extract
python3 -m ari_os.tools.cortex kg list
python3 -m ari_os.tools.cortex kg stats`}
`extract` builds the graph from your memory. `list` shows the entities and relations it found. `stats` measures it, so you can see how dense the graph has become over time.
## Prediction and prefetch
Prediction looks at where you are and surfaces what you are likely to need next. Prefetch goes one step further and warms the context for a working directory before you open it.
{`python3 -m ari_os.tools.cortex predict
python3 -m ari_os.tools.cortex prefetch --cwd `}
`predict` surfaces what you are likely to need. `prefetch` warms context for a given working directory, so the brain is ready the moment you arrive.
## Mind-wander
Now and then, the brain surfaces a memory you had set aside. It is the quiet background process that connects an old note to the thing in front of you.
{`python3 -m ari_os.tools.cortex wander --focus ""`}
Use `--focus` to point the wander at a topic. Toggle the whole feature on or off through the control panel.
{`python3 -m ari_os.tools.arios cortex wander on|off`}
## EARS (listening)
EARS ingests sound. Point it at an audio file or a transcript, and the contents land in memory like any other note.
{`python3 -m ari_os.tools.cortex ears `}
Enable it through the control panel.
{`python3 -m ari_os.tools.arios cortex ears on`}
The vision parts of EARS need a local vision model. The plain audio and transcript path does not.
## LENS (seeing)
LENS applies a visual or aesthetic lens to your work. Pass it a slug and it reads through that lens.
{`python3 -m ari_os.tools.cortex lens `}
Enable it through the control panel.
{`python3 -m ari_os.tools.arios cortex lens on`}
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.
## Embeddings backends
The brain needs an embeddings backend to turn text into vectors. Choose it through the control panel.
{`python3 -m ari_os.tools.arios cortex embeddings auto|google|ollama|off`}
`auto` picks a sensible backend for you. `google` and `ollama` pin it to one provider. `off` runs without embeddings at all.
{`python3 -m ari_os.tools.cortex ingest --path `}
Memory files live under your memories directory, at `$ARI_OS_HOME/memories/
{`python3 -m ari_os.tools.cortex retrieve -q "" --cwd "$PWD" --mode `}
Recall gets better as more context layers switch on. The fidget below shows the same answer sharpening as each layer is added.
{`python3 -m ari_os.tools.arios cortex mode `}
On the cortex tool you can also list, get, and set the mode with `cortex mode list|get|set
{`python3 -m ari_os.tools.cortex dream`}
You can also run a single tier on its own.
{`python3 -m ari_os.tools.cortex distill --tier session|daily|weekly`}
The point of consolidation is to keep the store small and dense while losing nothing. Memories compress, but lineage still walks back to the original source.
## Embeddings
The brain turns text into vectors so it can rank by meaning. The default backend is Ollama, which runs on your machine.
Pull two models. The embedding model `nomic-embed-text` produces 768-dimensional vectors, and `gemma3:4b` handles the local language work.
{`ollama pull nomic-embed-text
ollama pull gemma3:4b`}
`OLLAMA_URL` defaults to `http://127.0.0.1:11434`, so a standard local Ollama needs no extra configuration.
With no Ollama running, recall falls back to a ranked keyword search. It is less precise than vector ranking, but the brain still works, fully offline, with nothing to set up.
## Where to go next
{`git clone https://github.com/PUSHINGSQUARES/ARI-OS
cd ARI-OS
uv pip install -e .`}
If you do not use `uv`, plain `pip install -e .` works the same way. For the optional media features, install the extra group with `pip install -e '.[media]'`.
## Run the installer
The installer is a Python module. Run it as a module, not as a script.
{`python3 -m ari_os.install`}
The wizard accepts the following flags:
- `--llm ollama|api|off` sets how recall is powered. The default is `ollama`.
- `--ears` enables the optional listening surface.
- `--lens` enables the optional vision surface.
- `--no-mcp` skips automatic MCP registration.
- `--dry-run` shows what would change without writing anything.
- `--update` re-applies the latest managed files.
- `--revert` rolls the managed changes back.
- `--uninstall` removes everything ARI-OS placed.
- `--purge-keys` clears stored keys, used together with uninstall.
## What it installs
The installer writes a small, predictable footprint. It places:
- 10 skills into `~/.claude/skills/{`claude mcp add ari-os-cortex -- python -m ari_os.tools.cortex.mcp_server stdio`}
There is more on how the brain works in the [brain](/documents/ari-os/brain) page.
## Keys
Keys are read from environment variables first, and then from the macOS Keychain under the service `com.ari-os.keys`. They are never printed. This is the same principle as the rest of the install: nothing destructive, nothing leaked, and every action reversible.
{`python3 -m pytest -q
python3 -m ari_os.tools.monitor`}
The monitor opens at `http://localhost:7777`. If the tests pass and the monitor loads, the install is healthy.
## Reversible
Every change is backed up first, so you can move forwards or backwards at any time.
- `python3 -m ari_os.install --update` re-applies the latest managed files.
- `python3 -m ari_os.install --revert` rolls the managed changes back.
- `python3 -m ari_os.install --uninstall` removes everything ARI-OS placed. Add `--purge-keys` to also clear stored keys.
{`claude mcp add ari-os-cortex -- python -m ari_os.tools.cortex.mcp_server stdio`}
Once it is registered, your model can call these tools directly. The names are stable and the parameters are listed in full.
{`python3 -m ari_os.tools.dispatch start --executor sonnet --task-file BRIEF.md --cwd ./worktree --label mytask`}
A few rules keep dispatch safe and predictable.
The executors are `haiku`, `sonnet`, and `opus`. Pick the smallest one that can do the job, and escalate only when the work demands it.
Two extra flags shape what a worker can touch: `--add-dir` grants access to an additional directory, and `--read-only` runs the worker without write access.
Dispatch refuses a git repository root as `--cwd`. Point it at a worktree or a subdirectory instead, so a worker can never act on the whole repository at once.
Once workers are running, manage them from your session:
{`python3 -m ari_os.tools.dispatch list
python3 -m ari_os.tools.dispatch questions
python3 -m ari_os.tools.dispatch answer --answer "..."`}
`dispatch list` shows what is in flight, `dispatch questions` surfaces anything a worker is blocked on, and `dispatch answer` sends your reply back to a specific worker so it can carry on.
## Watch it run
The monitor gives you one window onto every running worker, live.
{`python3 -m ari_os.tools.monitor`}
It opens at `http://localhost:7777`. Leave it running while you work, and you can see progress, questions, and completions without switching context.
## Control panel
The control panel is the single command for configuring ARI-OS.
{`python3 -m ari_os.tools.arios`}
It takes these subcommands:
- `keys` manages the API keys for any models you use.
- `theme {`python3 -m ari_os.tools.arios cortex status`}
And to switch the retrieval mode to focus:
{`python3 -m ari_os.tools.arios cortex mode focus`}
Each cortex setting changes what the brain pulls and how. The [brain page](/documents/ari-os/brain) covers the modes and embeddings in depth.
Codex / Terra
GPT Image 2
Plates
MiniMax H3
QC
Keyframe
Plate front
Plate rear
subject
black performance SUV
verb
hold / advance
move
slow push along body axis
duration
short take
aspect
21:9
multi-beat
drive in, pan, dissolve, exit, cutaway
identity
motion
light
crop
FAIL multi-state
FIX one dissolve
one variable: camera locked · rear dissolve only
2944 × 1248 · 21:9 · 24 fps · H.264
native delivery from the motion model
crop to 16:9 = damage zones
### 02 · Glacial river
Kinetic water and body solidity.
### 03 · Controlled data rupture
Front half solid. Rear dissolves on purpose.
### 04 · Basalt arches
World scale at 21:9.
### 05 · Reality exit
Rear geometry + spare held.
---
## Assembled study
There is a 30 second corrected conform in the private archive. It is **reference only**. Music and voiceover are **not selected**. That file is over the public site asset size cap, so it is not embedded here. The raw H3 selects above are the public proof.
## What I am not claiming
- Not manufacturer work. Independent AI production proof.
- Not "one prompt, whole commercial."
- Not a finished sound mix.
- Not a mystery finish pipeline. This post is stills to H3 to QC to native delivery.
Lock the still. Move one action. Fix one variable.
---
## Active Brain: memory that watches the whole session
URL: https://aris-space.com/documents/memory/active-brain
Date: 2026-08-06
import { Pullquote } from '@/components/blocks'
# Active Brain: memory that watches the whole session
The count from my own bench this week: one memory system that only woke up on the first prompt, three coding seats that never got mid-session help, and zero useful interruptions when I was actually stuck.
Session start was solved. Mid-session was not.
I already had a [Cortex](/documents/memory/cortex): durable notes, indexed, recalled when a chat opens. That first pack is gold. Then the conversation moves. I pivot. I rephrase the same bug four times. I invent a fix that contradicts a decision from last month. The model has no idea any of that history exists, because nothing is watching after turn one.
So I designed **Active Brain**.
| Stage | Input | Output | Next Receiver | Acceptance Check |
| --- | --- | --- | --- | --- |
| Script | An agreed outcome and source facts | Approved spoken words | Voice production | Claims, meaning, and intended delivery are reviewed |
| Voice | Approved words and pronunciation notes | A reviewed audio file | Timing and animation | Listen for pronunciation, omissions, and delivery |
| Timed Transcript | The actual reviewed audio | Words aligned to that recording | Animation | Compare timings against the same audio |
| Animation | Approved audio, timings, and visual direction | A playable cut | Release review | Inspect sync, readability, framing, and the intended effect |
| Publish | The approved cut and destination requirements | The intended public item | Its audience | Human approval, correct destination, and live verification |
These outputs give the stages an identity. “Editor” on its own doesn't. The work could mean correcting language, cutting audio, aligning subtitles, or judging a visual sequence. Until the output is explicit, a role name can conceal several incompatible expectations.
I want the map to survive a change of owner. A person could record the voice. A model could propose it. A script could align a transcript. The required artefact and its acceptance check still need to exist.
## Give Each Handoff A Contract
A handoff is where an output becomes somebody else's input. That boundary deserves a contract.
Mine starts with four fields:
- **Input:** The accepted artefact this stage can rely on, including the revision it belongs to.
- **Output:** The artefact the stage must produce, with enough structure for its next receiver.
- **Receiver:** The person or process that needs to use that output.
- **Check:** The observable evidence that lets the receiver accept it.
Then I add the judgement the stage requires, the dependencies that must already be accepted, and the owner who can make the decision.
For a timed transcript, “a transcript exists” is a weak check. The file might contain every spoken word and still belong to an earlier recording. Its shape can be valid while its relationship to the audio is wrong.
A stronger contract names the accepted audio revision, specifies the time units, requires ordered timestamps within the recording's duration, and includes a sync comparison at meaningful points. Structural checks can reject malformed timestamps. Listening or viewing checks whether the alignment works for the cut. Each check supports a different claim.
A parser accepting a file proves that the parser could read it. It doesn't prove that the words are accurate, the timing belongs to the current recording, or the visual intention survived. Those need their own evidence.
The receiver determines which evidence is useful. Someone recording a voice needs approved words and pronunciation decisions. An animation process needs timings tied to audio. A reviewer needs a playable cut and the intended outcome. Giving each of them the same enormous document makes the interface harder to use.
**Enough context means enough to do this job and judge its output.** It doesn't mean handing over every conversation that preceded it.
## Correct Stages Still Need The Correct Order
A list of sensible stages can describe a broken workflow.
If this animation is timed to the voice, the timings must come from the recording the animation will use. A transcript made before that recording cannot establish its actual timing. If the recording changes, dependent timing and animation need to be checked again.
Try moving the stages below. The lab evaluates the prerequisites of this illustrative workflow. It also propagates an invalid prerequisite: putting Animation after an unusable Timed Transcript doesn't repair the transcript.