Get started

Set it up once. Every session after remembers.

A SurrealDB store and the Antumbra MCP server run in Docker, embeddings come from a local ollama, and three hooks connect Claude Code. It runs on macOS, Windows and Linux, bound to localhost.

Private preview. No version has been tagged yet, and the repository is private while Antumbra is in preview. These are the documented steps for anyone with access; the one-line installers below go live with the first release.

Just looking

See the console first.

The operator console renders against a seeded, throwaway in-memory store, with nothing else to set up: the population, memory, the loop, evals and the sovereign-mode page.

From a clone
cargo run -p antumbra-tui -- --demo

The full setup

Seven steps from a clone to a first session.

You need git, Rust through rustup (the repository pins its toolchain), Docker, and ollama. The first builds compile the whole dependency graph once.

  1. Clone it and pull the embedding model

    all-minilm is a 384-dimension model that matches the store's vectors. On Linux, start ollama with OLLAMA_HOST=0.0.0.0 so the Dockerized server can reach it.

    Shell
    git clone https://github.com/Oneiriq/antumbra.git
cd antumbra
ollama pull all-minilm

  2. Install the console and the CLI

    Both land in ~/.cargo/bin. With just installed, just install builds all three binaries instead.

    Shell
    cargo install --path crates/antumbra-cli --locked
cargo install --path crates/antumbra-tui --locked

  3. Configure the secrets

    Copy the example and set three values: SURREAL_PASS, a strong database password; ANTUMBRA_JWT_SECRET, 32 random bytes in base64; and ANTUMBRA_SURREAL_DATA, an absolute directory for the database files, outside the repository. On Linux, make it writable by uid 65532.

    macOS and Linux
    cp docker/.env.example docker/.env
openssl rand -base64 32
mkdir -p ~/.antumbra/surrealdb
    Windows, PowerShell
    Copy-Item docker/.env.example docker/.env
[Convert]::ToBase64String((1..32 | % { Get-Random -Max 256 }))

  4. Start the stack

    The first run builds the server image once. When it is up, antumbra-surrealdb reports healthy, the database listens on ws://127.0.0.1:8000 and the MCP server on http://127.0.0.1:8081, both bound to localhost.

    Shell
    docker compose -f docker/docker-compose.yml up -d
docker compose -f docker/docker-compose.yml ps

  5. Mint an access token

    The server verifies a signed token on every call; the token is the identity. This one is long-lived and still expires. Keep it in ~/.antumbra/token.txt, where the hooks look for it.

    Shell
    docker compose -f docker/docker-compose.yml run --rm antumbra-mcp \
  --mint-token --tenant ws:default --user user:default --token-ttl-days 365

  6. Connect Claude Code

    Point Claude Code at the server, with a headers helper that reads the token from its file, so the token never sits in a settings file. Set ANTUMBRA_URL, ANTUMBRA_WORKSPACE_ID and ANTUMBRA_HOST_ID in the agent's environment, then add the hooks from scripts/hooks/README.md: a bash set for macOS and Linux and a PowerShell set for Windows.

    macOS and Linux
    claude mcp add-json antumbra --scope user '{"type":"http","url":"http://127.0.0.1:8081/mcp","headersHelper":"bash ~/.claude/antumbra-mcp-headers.sh"}'
    Windows, PowerShell
    claude mcp add-json antumbra --scope user '{"type":"http","url":"http://127.0.0.1:8081/mcp","headersHelper":"powershell -NoProfile -NonInteractive -File C:\Users\<you>\.claude\antumbra-mcp-headers.ps1"}'
    .claude/settings.json, excerpt, macOS and Linux
    {
  "autoMemoryEnabled": false,
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command",
      "command": "bash ./scripts/hooks/antumbra-session-start.sh", "timeout": 10 }]}],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command",
      "command": "bash ./scripts/hooks/antumbra-prompt-recall.sh", "timeout": 20 }]}],
    "Stop": [{ "hooks": [{ "type": "command",
      "command": "bash ./scripts/hooks/antumbra-capture.sh", "timeout": 5 }]}],
    "PreCompact": [{ "hooks": [{ "type": "command",
      "command": "bash ./scripts/hooks/antumbra-capture.sh", "timeout": 5 }]}]
  }
}

    Turning off Claude Code's own file memory makes Antumbra the one store: one set of permissions, one thing to back up.

  7. Add a GPU, when you have one

    Everything above runs without a GPU. With an NVIDIA card on Linux, or Windows through WSL2, the GPU build also serves answers from trained experts and consolidates memory into experts on its own.

    Shell
    docker compose -f docker/docker-compose.yml -f docker/docker-compose.gpu.yml up -d

The hooks

What each one does.

Each ships as a bash script and a PowerShell script with the same behavior, about twenty lines apiece.

ScriptEventWhat it does
antumbra-session-startSessionStartRecalls standing conventions and the memories for this repository and branch, tags each git anchor live, not on HEAD or orphaned, and stays under Claude Code's 10,000-character limit.
antumbra-prompt-recallUserPromptSubmitRecalls the three memories most relevant to each message, scoped to the repository and branch.
antumbra-captureStop, PreCompactAsks the agent to store what it learned, with provenance, before the turn ends or the context is compacted.
strip-attributionPreToolUseStops commits and pull requests that carry model-vendor attribution, so the work is credited to you.

With the first release

Prebuilt installers.

Release builds cover macOS on Apple silicon and Intel, Linux on x86-64 and ARM, and Windows on x86-64, with shell, PowerShell and MSI installers. Swap antumbra-tui for antumbra-cli or antumbra-mcp. They resolve once the first version is tagged.

macOS and Linux
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Oneiriq/antumbra/releases/latest/download/antumbra-tui-installer.sh | sh
Windows, PowerShell
irm https://github.com/Oneiriq/antumbra/releases/latest/download/antumbra-tui-installer.ps1 | iex

Questions

Before you start.

Does my code or memory leave my machine?

Not unless you send it somewhere. The store, the embedder and the reranker run where you run them, and the containers bind to localhost. Antumbra has no service of its own that your memories pass through.

Which agents does it work with?

Claude Code is the agent the hooks are written and tested for. Any MCP client can use the tools over stdio or HTTP; hooks for other agents are planned.

Do I need a GPU?

No. Memory, recall and routing run without one. Training experts and answering from them need an NVIDIA GPU; without one, the answer tool escalates cleanly and everything else works.

How is this different from a memory layer?

A memory layer helps a fixed model remember. Antumbra also checks each memory against your repository before it is used, and trains what keeps proving true into small experts you own.

Can a teammate see my memories?

Only what you share. Memories live in compartments you own; sharing one is explicit, and revoking it takes effect at once, enforced in the database engine.

Why build it this way?

The case for memory you own, and for small experts over renting your competence, in the author's words.

Why I'm building Antumbra How memory works