Antumbra on your own machine

In June I wrote about why I'm building Antumbra, and last week about what changed in the four months since. Both described it from my side, as the system I build and run. This one is from yours.

Opening Antumbra up for other people to run for themselves changes which questions matter. Not "how does the gate work", but: what do I need, what will it do to my machine, how do I take it back out, and what leaves my computer while it runs?

Antumbra is available now. Version 0.1.0 has installers for macOS, Linux and Windows, the source is on GitHub, and antumbrahq.ai has the steps. This is what you'll find.

Setting Antumbra up is one command, and taking it out is four steps. Everything it keeps lives in one folder in your home directory.

What you need

• A computer running Windows, macOS or Linux. No GPUGPU (graphics processing unit)The chip that trains and runs AI models far faster than a computer's main processor..
• Docker, running. That's Docker Desktop on macOS and Windows, and Docker Engine on Linux.
• ollama, which turns text into embeddingsEmbeddingA list of numbers that captures what a piece of text means, so text about similar things can be found by comparing the numbers. An embedder is the model that produces them. on your own machine. Antumbra uses a small model, all-minilm.
• On macOS and Linux, jq and curl, which the hooksHookA script an app runs automatically at a set moment, such as when a session starts or ends. use.
• Claude CodeClaude CodeAnthropic's AI coding agent. It works in your terminal and your codebase, and connects to outside tools over MCP., the agent I've tested Antumbra with so far.
• gitGitThe version control tool most software is written with. It records every change to a project as a commit, so history can be compared and undone., to clone the repositoryRepositoryA project's files together with their full history of changes, usually kept with git and hosted on a service such as GitHub., which setup builds the server from. You don't need RustRustA programming language known for being fast and for catching whole classes of bugs before a program ever runs..

Plan on about ten minutes the first time. Most of that is Docker building the server image, which happens once.

Getting it

The antumbra command comes from an installer, which puts it on your PATH:

# macOS and Linux
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/albedosehen/antumbra/releases/latest/download/antumbra-cli-installer.sh | sh

# Windows, in PowerShell
irm https://github.com/albedosehen/antumbra/releases/latest/download/antumbra-cli-installer.ps1 | iex

There are builds for macOS on Apple silicon and Intel, Linux on x86-64 and ARM, and Windows, and the release page has MSI packages and checksums too. Then clone the repository and run setup from inside it:

git clone https://github.com/albedosehen/antumbra.git
cd antumbra

One command

antumbra setup local

That's the whole setup. In order, it checks Docker, ollama, jq and curl, pulls the embedding model and checks that it gives the 384 dimensions the store expects, and generates the database's password and the server's signing secret into the stack's own settings file, which git ignores. Then it starts two containersContainerA packaged program bundled with everything it needs to run, so it behaves the same on any machine., the database and the Antumbra server, mints you a token that's good for a year, and proves recall works with it before it touches anything of Claude Code's. Only then does it write the hooks, add them to Claude Code's settings and register the MCPMCP (Model Context Protocol)The standard way AI coding agents such as Claude Code connect to outside tools and data. server.

A first run reads like this, trimmed, with your own paths and versions in place of mine:

Setting up Antumbra on this machine.

  ✓ Docker 28.4.0 is running
  ✓ jq and curl are installed (the hooks use them)
  ✓ ollama answers at http://127.0.0.1:11434
  ✓ all-minilm embeds (384 dimensions)
  ✓ docker/.env: generated SURREAL_PASS, ANTUMBRA_JWT_SECRET
  ✓ the store and the server are up
  ✓ the server answers at http://127.0.0.1:8081
  ✓ minted a token for ws:default / user:default, saved to ~/.antumbra/token.txt (valid for a year)
  ✓ recall works with that token
  ✓ hooks written to ~/.antumbra/hooks
    backed up the settings to ~/.claude/settings.json.antumbra-backup-20261006093012
  ✓ ~/.claude/settings.json: hooks on SessionStart, UserPromptSubmit, Stop, PreCompact; ANTUMBRA_URL, ANTUMBRA_WORKSPACE_ID, ANTUMBRA_HOST_ID; autoMemoryEnabled false
  ✓ MCP server "antumbra" registered with Claude Code (user scope)

Antumbra is set up. Start a new Claude Code session: it opens with what Antumbra
remembers, and what you work on goes back in.
Check it any time with: antumbra setup check

Running it again is safe. Every step keeps what's already in place, so when one fails, you fix what its message names and run the same command again. --dry-run shows what it would change without changing anything, and antumbra setup check looks at every piece later and ends with Everything is in place., or a list of what isn't and what to do about each.

If you'd like to look before setting anything up, the console runs against a seeded, throwaway store, with no Docker and no database. It installs the same way, with antumbra-tui in place of antumbra-cli in the installer's address:

antumbra-tui --demo

Or let your agent do it

You can hand the whole thing to Claude Code with one sentence:

Set up Antumbra for me by following https://antumbrahq.ai/setup.md

That page is written for the agent, not for you, and it sets rules I'd want any agent to follow on my machine. It asks before installing anything system-wide, and says what each thing is for. It never prints a token, and when one has to be typed in, it asks you to save it to a file yourself, so the token never passes through the chat. It never edits Claude Code's settings by hand, because setup does that safely. And when it's done, it tells you to start a new session, since Claude Code only loads hooks and MCP servers when a session starts.

What it changes, and how to take it out

You should know exactly what a tool did to your machine, so here it is, all of it:

Setup only ever adds to Claude Code's settings. It backs the file up first, never rewrites what's already in it, refuses an edit that would change anything else, and reads the file back to check that the edit took.

The one setting it changes is Claude Code's own file-based memory. With both on, what your agent learns lands in two stores that don't know about each other, so setup turns Claude Code's off. --keep-auto-memory leaves it alone.

Taking it out is the same list in reverse:

claude mcp remove antumbra --scope user
docker compose -f docker/docker-compose.yml down

Then restore the settings backup and delete ~/.antumbra. Delete the clone, the Docker images and the antumbra command in ~/.cargo/bin too if you want the disk space back.

A working day with it

Once it's set up, you don't do anything differently. You open Claude Code and work. The hooks do their part at three moments.

When a session starts, Antumbra hands your agent your conventions and the memories that matter for the repository and branchBranchA separate line of work in a repository, so a change can be built and reviewed without touching the main line until it is merged. you're in, each marked with whether it still applies to the code in front of you. It also announces any handoffs waiting for this machine, more on those below. All of it stays under 9,500 characters, and if the server is slow to answer, the hook gives up rather than hold your session.

With every prompt, it recalls the three memories most relevant to what you just typed, scoped to the repository and branch you're in. They arrive in your agent's context looking like this:

## Antumbra recall (top matches for this prompt)

- (world) [in_scope] This repo formats with deno fmt, and CI fails on unformatted files.

- (bank) [in_scope] The site's dev server breaks islands on Windows; test them against the Docker build.

- (opinion) [other_branch] Prefer one PR per article.

These are automatic; call recall_memories for a deeper or differently-phrased search.

The recall has ten seconds, and it never fails your prompt. If it runs out of time, the prompt goes through without it.

When the session stops, or Claude Code compacts its context, your agent is asked once to store what it learned and what it verified, and, if you stated or corrected how it should work, to record that as a behaviour. More on those below.

In between, your agent has Antumbra's tools. There are 33 of them, and a coding agentCoding agentAn AI agent, such as Claude Code, that works inside your codebase: it reads files, runs commands and writes code on your behalf. needs seventeen: four for memory (recall, store, and confirm or correct what it recalled), two for documents, route and answer, three for handoffs, two for the machines you work on, and four for behaviours. The agent profile advertises only those, so the rest don't take up room in your agent's context.

Teaching it how you work

The way Antumbra learns changed after the last article, and it's the change I'm happiest about.

In that article, memories grew into experts once they'd been confirmed often enough. When I measured what that path actually did, it had never produced an expert. In a store of 6,451 memories, not one had ever been confirmed, because nothing in an ordinary day confirms a memory. And if it had fired, it would have taught an expert to repeat a memory back, which recall already does better: a recalled memory can be cited, corrected and kept current, and one baked into weightsWeightsThe learned numbers inside an AI model. Training adjusts them, and answering a question reads them. can't. So that path is retired. Facts stay in the store, where recall serves them. What an expert learns now is behaviour.

A behaviour is how you want an agent to act on a whole class of tasks: name branches feat/{issue}-{slug}, reach a server by its SSHSSH (Secure Shell)The standard tool for logging in to remote machines. It remembers each server's key and warns you if that key ever changes. alias, open pull requestsPull requestA proposed change to a repository, reviewed and discussed before it is merged into the main line of work. against main. When you state one, or correct your agent, it records the behaviour with record_behaviour: the rule in one sentence, a check a program can apply, at least three tasks with answers that follow the rule, and answers that break it.

{
  "rule": "Name branches feat/{issue}-{slug}.",
  "must": ["feat/\\d+-[a-z0-9-]+"],
  "examples": [
    { "task": "Start a branch for issue 42, the login timeout.", "answer": "git checkout -b feat/42-login-timeout" },
    { "task": "I'm picking up #108, dark mode for settings. Branch?", "answer": "git switch -c feat/108-settings-dark-mode" },
    { "task": "New branch for issue 7: retry failed uploads", "answer": "git checkout -b feat/7-retry-failed-uploads" }
  ],
  "violations": ["git checkout -b login-timeout-fix", "git checkout -b feature/42"]
}

Antumbra tests the check against the examples and the violations before it stores anything, and refuses a check that can't tell them apart. A rule you stated yourself is accepted on the spot. One your agent inferred waits as proposed until you accept it. You can retire a behaviour, and a newer one can replace an older one. Behaviours live in a compartmentCompartmentA named group of memories you own in Antumbra. You can keep it private, share it with specific people, and train a private expert from it. of your own, and recall finds them like any other memory.

Recording, accepting and recalling behaviours needs no GPU. With one, the behaviours you accept are trained into a standing expert of your own, one for everywhere and one per repository, retrained within ten minutes whenever the set changes. Training holds back tasks phrased in ways it never shows the expert, and it replays the base modelBase modelThe general model that experts are trained on top of. Antumbra keeps one small local base model and adds experts to it as small adapters.'s own answers to 325 everyday prompts that no behaviour governs, so the expert doesn't forget how to do everything else. An expert is admitted only if every behaviour it was taught clearly beats the base model on the held-back tasks, and the everyday answers hold.

Here's what that did for four of my own rules, on 18 held-back tasks each:

The middle column surprised me. Recall found memories for every task, and where it surfaced the rule, the small model still didn't apply it. Recalled text in front of an unrelated task cost it more than half of those. Ten examples per behaviour turned out to be enough, and nine behaviours fit in one expert once I halved the learning rate. At the old rate, teaching them together broke it.

What this doesn't show is that it pays off for the large model your agent runs, which may well follow a rule it's given in context. It's for the model Antumbra serves itself, the competence you own.

Handoffs between your machines

I work on more than one computer, and the most useful small thing Antumbra does for me is carry a note from one to another. At the end of a session on one machine, my agent leaves a handoff for the other, or for whichever machine starts a session next. The first session there opens with it, and keeps opening with it until an agent marks it done.

Handoffs are kept as memories in a compartment of your own, marked as volatile: a note meant for tomorrow, not something to keep. One limitation: a handoff reaches a session when it starts, not a session that's already open.

What depends on what

If you keep a lot of repositories, the question that matters before a change is which of the others will feel it. When I change sigilbuzz, that's Oniq, and through Oniq, Pixel Stroke and PolyConsolePolyConsoleA game platform I'm building, with apps on Android and an online social service behind them.. Antumbra keeps a graph of those dependencies, and it starts from the manifests you already have:

antumbra claude dependencies --repos ~/repos

That reads the package.json, Cargo.toml, go.mod, pyproject.toml and requirements.txt files of every repository in that folder, and records a dependency wherever one repository names a package another of them publishes. Evidence can come from other places too, and each kind of source is trusted for as long as it tends to stay true:

Seeing the same edge again renews it, and an edge nobody sees again fades. Your agent asks blast_radius what breaks if a service does, and gets each dependent by its strongest path, with the evidence for every hop. It walks three hops by default and up to six, and it skips pairs weaker than 0.4, so a model's claim on its own doesn't count until something corroborates it.

Seeing what it knows

A memory you can't inspect is one you have to take on faith, so there are two ways to look.

The dashboard is a web page served by Antumbra itself, at http://127.0.0.1:8081/dashboard. You sign in by pasting your token, which is kept only in that browser tab and forgotten when you close it. It's read-only. It shows how much is in your workspace, your experts by status and fitness, your compartments, your documents, and your memories, either found by meaning or listed newest first, each with its network, confidence, the commitCommitA saved snapshot of changes in a repository, identified by a unique hash, so any past state of the code can be named and found again. it was learned at and its links to other memories. It also draws the dependency graph, with the blast radius of any service you pick, and a box lets you try route and answer on a task without writing anything.

The console, antumbra-tui, shows the same store in a terminal, with pages for your experts, your memory, the learning loop, its evaluations, and sovereign mode.

Recall, measured with questions

Something changed since the last article that affects everyone who runs Antumbra, so it belongs here.

Every recall measurement I'd made asked with a fragment: a dozen of a memory's own words, cut from inside it. That's not what the hook sends. The hook sends whatever you typed, which is a question or an instruction in your own words. So I built a set of questions: a small local model read 2,000 memories from my store and wrote one short question that each memory answers, 399 in all. It's a fair way to compare one version of recall with another, though not an absolute grade, since another memory that also answers a question counts as a miss.

The questions found two defects straight away. The exact-word half of recall only matched memories containing every word of the query. A fragment's words are always all in its memory, so every earlier test passed. A question's rarely are, so for real prompts the exact-word half returned nothing. And the per-text calibration I credited in the last article, which took the right memory to first place in 13 of 30 test questions instead of 2, turned out to cost more than it saved once long memories were also indexed in pieces. On questions it was the larger part of the loss, so it's gone.

The no-model baselineBaselineThe simplest point of comparison, used to check that a result beats doing nothing clever. told the story. Plain keyword ranking, with no model at all, found the right memory in its top ten for 87% of the questions. The first stage I had shipped, the part that picks candidates for the rerankerRerankerA second model that reads each search result next to the question and reorders the results by how well they actually answer it., found it for 41%. With both defects fixed, here's what recall as a whole hands back on the same 399 questions:

The time went up because more memories match now. I've since made the parts of a recall run at the same time instead of one after another, so a recall costs its slowest part.

The same questions settled which embedding model to use. Four models trained for questions put the right memory first three to four points more often than all-MiniLM, the small one Antumbra uses. But the reranker reads the top 30, and there every one of them was within half a point of all-MiniLM's 0.965, so the small model stays.

A few other fixes from the same week are worth knowing about:

• Long memories are now also indexed in overlapping pieces of about 400 characters, so a passage from the middle of a long memory can find it. On 400 of my memories, that took the right memory's presence in the top 30 from 0.552 to 0.820.
• The relevance floorRelevance floorA minimum relevance score. Results below it are dropped, so when nothing relevant exists the answer can be nothing instead of the least bad guesses. was judging only the first 900 characters of each memory, the part that's shown, while the reranker had ranked the whole thing. A long memory whose answer sat past the cut ranked first and was then thrown out. The floor now judges the whole memory.
• The floor also silently failed on any query of more than one line, which is what the hook sends when you paste a prompt. On my own server, 100 recalls in 16 hours went out unfiltered before I caught it.
• A prompt that asks for two things at once used to land between them and recall neither. It's now split into its parts, each part is recalled, and the results are merged.
• The first recall after a restart took 5.8 seconds while the models loaded, longer than the session-start hook waits. The server now warms them as it starts, and that recall takes about 0.16 seconds.

What stays on your machine

Antumbra exists so that your work stays on your side, so here's what that means in practice.

• Everything listens on 127.0.0.1. The database and the server only answer your own machine. Opening the server to your network is a setting you change on purpose.
• The containers run with as little as possible. They run as an unprivileged user, with every Linux capability dropped and no way to gain privileges. The server's filesystem is read-only, and secrets reach it through its environment, never on a command line another process could read.
• No telemetryTelemetryUsage data a program sends back to the company that makes it. Some tools also use that connection to decide which of their features to switch on.. Antumbra has no service of its own that your memories pass through, and it sends nothing about you anywhere.
• What does leave, and why. Your agent's model provider sees the context Antumbra adds to your prompts, the same as any other context. The session-start hook asks GitHubGitHubA popular website for hosting code repositories, reviewing changes and running automated checks., through your own gh login, which pull requests merged recently, so memories from a merged branch stay current; ANTUMBRA_REANCHOR=0 turns that off. And the first run downloads what it needs: the Docker images, the Rust crates and the embedding model.
• Forgetting is real. When you or your agent forget a memory, Antumbra writes a tombstone that hides it everywhere it syncs, and a forgotten memory can't be confirmed back into existence. Revoking a compartment you've shared takes effect immediately and fails closed.
• Fully offline is an option. The server can also run over standard input and output with an embedded database file and a single identity: no Docker, no network port, nothing listening at all.

Two things aren't there yet. There's no export command, so the closest thing today is syncing to another database you run. And Antumbra doesn't encrypt the database itself. It lives on your disk under your account, so your disk's own encryption is what protects it.

With a GPU, and with more than one machine

Everything above runs without a GPU. If you have an NVIDIA card, on Linux or on Windows through WSL2, antumbra setup local --gpu adds the learning half: embeddings move into the server, the behaviours you accept are trained into your standing experts on their own, and answer serves experts, with your standing ones blended in. The last article covers the hardware and what it costs. Training needs at least 16 GBGB (gigabyte)About a billion bytes. A feature-length film in high definition is a few gigabytes. of video memory, and the GPU build isn't checked in CICI (continuous integration)Automated checks that build and test every proposed change before it is merged, so problems are caught before they ship. yet. Without a GPU, answer escalatesEscalateWhat Antumbra does when no local expert covers a task: it says so, and the agent you brought does the work instead. cleanly and nothing else changes.

If you'd rather keep one memory for all your machines, run Antumbra on one of them, or on a small server at home, and connect the rest with a token from that server:

antumbra setup hosted https://antumbra.home.example --token-file ~/antumbra-token.txt

Setup checks that the server accepts the token, saves it where only you can read it, and connects Claude Code to it. A handoff left on your desktop then reaches your laptop through that one store.

What you're allowed to do with it

Antumbra is source-available under the Elastic License 2.0. You can run it for yourself or inside your own organization, read it, change it and share it. What the license rules out is offering it to other people as a hosted or managed service. It isn't an open source license as the OSI defines one, and I'd rather say so up front than have you find out later.

What's still missing

Antumbra is out, but it's 0.1.0, and a few things I want before I'd call it finished aren't there yet:

• Setup doesn't start the reranker yet. Without it, recall still searches by meaning and by exact words, but it can't say "nothing relevant", which was the headline of the last article. With a GPU the reranker takes 65 to 80 msms (millisecond)A thousandth of a second.. On a CPUCPU (central processing unit)A computer's main general-purpose processor. it takes seconds, too slow to sit in front of every prompt, so it isn't on by default yet.
• Setup advertises all 33 tools. The seventeen-tool agent profile isn't its default yet.
• Claude Code is the only agent I've tested. Others are on the list.

The first two articles asked you to take my word for what Antumbra does. Now you don't have to. Run it on your own machine, against your own work, see every memory it keeps, and take it out in four steps if it isn't worth it to you. The steps are at antumbrahq.ai/start, and the source is on GitHub.