agentibrain-kernel

A standalone brain + knowledge-base kernel for Claude Code agent fleets. Bring your own vault, your own LLM keys, your own embeddings. Runs on a laptop, a server, or a Kubernetes cluster.

Quick Start

Two ways in. Pick by whether you intend to change the kernel's code.

Run it (pip — no clone)

pip install agentibrain agentihooks
agentibrain install             # or: agentibrain install --ollama   (no API key needed)
agentibrain check               # verify
agentibrain update              # later: upgrade from PyPI (--check to look first)

install renders the stack into ~/.agentibrain/, seeds the vault, completes ~/.agentibrain/.env and starts everything, plus the agentihooks wiring most people forget. Re-run it any time: it reuses what exists and only adds what is missing. --s3-bucket swaps bundled MinIO for S3.

That is the whole brain: postgres, redis, minio, embeddings, brain-api, tick-cron, tick-drain, amygdala, mcp. Images come from ghcr.io/the-cloud-clockwork/agentibrain-*:dev — public, no login. Nothing is built locally.

Order matters: scaffold before up. The vault is a bind-mount source, so a container that reaches it first would own it as root. install sequences them in that order for you.

Develop it (clone — builds from source)

git clone https://github.com/The-Cloud-Clockwork/agentibrain-kernel.git
cd agentibrain-kernel
pip install -e .                # installs the `agentibrain` CLI
bash local/bootstrap.sh         # NO sudo — pins repo path + vault (~/agentibrain-vault), migrates if needed
agentibrain build               # build images from ./services, then start

This path also mounts your Claude Code transcripts and the agentihooks marker outbox, which the pip path leaves out. To seed the vault from those transcripts:

EXTRACT_ON_BOOT=1 agentibrain build tick-cron
agentibrain logs tick-cron --since 5m      # look for "[tick-cron] extraction:"

~/.agentihooks must exist before the first up on this path (bootstrap.sh creates it); otherwise Docker auto-creates it root-owned and agentihooks cannot write to it.

Daily driver — from any directory, no flags, no ports

agentibrain check               # deep verify: vault write, hello-embedding, pong completion
agentibrain status              # compose ps + shallow health
agentibrain logs <service> -f   # e.g. tick-cron, brain-api
agentibrain build               # after any git pull / code change (clone path)
agentibrain sync --check        # re-ingest everything: buffers + raw/, narrated progress

build/up/down/logs/status auto-locate the stack (checkout you are standing in → pinned repo → ~/.agentibrain), so they work from ~ or anywhere else. Full CLI reference: docs/CLI.md.

What works before you add any API key

Ingest, vault-text kb_search, brain_get_arc, and the deterministic half of every tick — the stack is useful out of the box. agentibrain check reports broken until you set keys, because two dependencies are genuinely unconfigured: semantic search and AI synthesis. Both are off, nothing else is.

No API key? Bundle a local model

agentibrain install --ollama    # pulls llama3.2:3b + nomic-embed-text on first start

This points both halves at a bundled Ollama — chat (AI ticks, kb_brief) and embeddings (semantic search) — so the stack needs no API key anywhere. llama3.2:3b runs on an 8 GB machine. For a larger one, export BRAIN_OLLAMA_CHAT_MODEL before the install that creates the deployment (llama3.1:8b at 16 GB, qwen2.5:14b at 32 GB+); settings take the BRAIN_ prefix. Once the stack exists install reuses it, so the model is fixed at creation and --ollama on a later install does nothing.

The first up downloads roughly 2.5 GB of weights and the models stay in a named volume across restarts.

Configure your LLM provider (optional)

install writes ~/.agentibrain/.env with the generated secrets and every stack setting at its default, then names the inference keys it left for you. Add them to the file, or pass --openai-key / --llm-gateway-url to install (they only fill keys the file lacks); the names are not guessable (the embeddings service reads LLM_API_KEY, never OPENAI_API_KEY).

Set at minimum one API key to enable semantic search:

# Required for embeddings (semantic search) — OpenAI or any compatible provider
LLM_API_KEY=<your-openai-key>
LLM_API_BASE=https://api.openai.com/v1    # or your LiteLLM proxy

# Required for AI tick + kb_brief synthesis — any OpenAI-compatible endpoint
INFERENCE_URL=https://api.openai.com/v1
INFERENCE_API_KEY=<your-openai-key>

No provider configured and no --ollama? The brain still works — brain_ingest, kb_search (vault text), brain_get_arc all function. Only semantic search and AI synthesis are off.

Free local alternative: agentibrain install --ollama (above) on the pip path. On the clone path, use the overlay:

docker compose -f compose.yml -f local/compose.ollama.yml up -d
docker compose exec ollama ollama pull llama3.2

The overlay wires chat only; semantic search still needs an embeddings key. --ollama wires both.

Wire Claude Code

Add to your project or user MCP config (e.g. ~/.claude/.mcp.json):

{
  "mcpServers": {
    "agentibrain": {
      "type": "sse",
      "url": "http://localhost:8104/sse"
    }
  }
}

Restart Claude Code, run /mcp — you'll see agentibrain with 6 tools:

Wire agentihooks profile (required for full brain injection)

agentihooks is required for the full brain experience. Without it, you get the HTTP API and MCP tools — but agents won't receive automatic context injection (hot arcs, signals, broadcasts), won't have their @marker comments captured, and won't see amygdala alerts. The hooks layer (brain_adapter, brain_writer_hook, amygdala_hook) is what makes the brain live inside Claude Code sessions. API-only usage (curl / SDK) works without agentihooks.

Install agentihooks (PyPI):

pip install agentihooks

Then link the brain profile so your agents get brain MCP tools + marker rules + broadcast channel config:

agentibrain install              # or: agentibrain install --ollama

One command sets the machine up: it reuses or renders a local stack, scaffolds the vault, starts it, completes ~/.agentibrain/.env with BRAIN_URL beside the bearer and agentihooks' brain settings at their defaults, creates the marker outbox, and links the brain profile that ships inside the installed package — identical from a PyPI wheel and from a source checkout. --ollama bundles Ollama for chat and embeddings, so the stack needs no API key and makes no external call.

There is one config file, and it is the brain's own. ~/.agentibrain/.env already feeds docker compose; agentihooks reads it too and adopts BRAIN_URL and KB_ROUTER_TOKEN from it, so the bearer is never copied and a rotation cannot go stale somewhere else. Only those connection keys are adopted — that file's database, object-store and provider credentials never enter a session's environment. An explicit setting in ~/.agentihooks/*.env still outranks the discovery, and the process environment outranks both. agentibrain check reports what agentihooks itself resolved and probes it with the hook's own bearer.

AGENTIBRAIN_HOME moves that directory, and both projects honour it — the kernel resolves it on every call, so exporting it relocates the config, the rendered stack and the file agentihooks reads, together. It defaults to ~/.agentibrain.

Point agentihooks at an arbitrary directory instead with agentihooks link-profile link <path>.

One brain, many machines

Inference belongs to the stack, not to the machine running Claude Code. You do not need an API key, a gateway or Ollama on every laptop — you need one brain that has them, and a BRAIN_URL on everything else.

# the machine that hosts the brain
agentibrain install                          # or --ollama if it has no provider

# every other machine — no stack, no vault, no key
agentibrain install --brain-url http://<host>:8103 --token <bearer>

--brain-url makes the install client-only: it skips the stack and the vault, writes that machine's own ~/.agentibrain/.env with just the URL and the bearer, and links the profile. --token also reads KB_ROUTER_TOKEN from the environment, the same as check, tick and sync. The bearer is whatever KB_ROUTER_TOKEN the hosting machine generated — copy it from that machine's ~/.agentibrain/.env. To repoint a client later, edit its own file; there is nothing to reinstall.

What this gives you:

• SessionStart — brain_adapter calls /feed and injects hot arcs, signals, operator intent, and tick diffs as BROADCAST blocks into every agent session
• Every turn — amygdala_hook polls /signal for nuclear/critical alerts
• Every 30 turns — brain_adapter re-fetches /feed and re-injects if content changed
• SessionStop — brain_writer_hook scans transcripts for @lesson, @milestone, @signal, @decision markers and POSTs them to /marker

Test it (raw HTTP)

TOK=$(grep ^KB_ROUTER_TOKEN ~/.agentibrain/.env | cut -d= -f2)   # clone path: ./.env

# Write something to the brain
curl -X POST http://localhost:8103/ingest \
  -H "Authorization: Bearer $TOK" \
  -F "message=The quick brown fox jumped over the lazy dog"

# Search for it
curl -X POST http://localhost:8103/search \
  -H "Authorization: Bearer $TOK" \
  -H "Content-Type: application/json" \
  -d '{"query": "fox"}'

Content lands in the vault at raw/inbox/ (~/agentibrain-vault by default). The tick drains it to a region dir, recomputes heat, and updates brain-feed.

Force a tick on demand (don't wait for the 2h scheduled cycle):

agentibrain tick --no-ai --wait                 # deterministic-only, blocks until done
agentibrain tick --wait                         # full AI tick
agentibrain tick --dry-run --wait               # read-only verify, no writes

The tick-drain service polls brain-feed/ticks/requested/ every 30s, coalesces pending requests by kind into one brain_tick.py run each, then refreshes the semantic index — same behaviour as the K8s tick-drain CronJob. Scheduled ticks still run every TICK_INTERVAL_SECONDS (default 2h) via tick-cron.

Verify the whole stack in one command:

agentibrain check          # 0 clean · 1 broken · 2 degraded (targets localhost:8103)

Two questions, because a stack can pass one and fail the other:

• Dependencies — a real vault write, an embeddings → Postgres round-trip with dimension validation, a real completion through the inference gateway.
• Pipeline — whether data is actually moving: markers arriving, the tick queue draining and succeeding, arcs ranked, lessons reconciled and fed back, signals broadcasting, the feed reaching a session, every producer present in the index. Each stage reports the evidence behind its verdict.

Both run server-side, so --brain-url answers for a brain on another machine. --deps-only, --pipeline-only and --json narrow or machine-read it. Full CLI reference: docs/CLI.md.

See local/README.md for full local docs, troubleshooting, port overrides, and inference modes.

agentibrain is a pillar of the agenti ecosystem alongside agenticore · agentihooks · agentibridge — and the brain layer every other pillar plugs into. It is self-contained: ships its own services, Helm charts, brain-keeper agent definition, and brain profile overlays, so any fleet of Claude Code agents can read from and write back to a single HTTP brain.

Why

AI agents have no long-term memory. Every session boots blind and forgets everything it learned the moment it exits. The usual fix — "ask the model to remember" — leaks state into prompts, burns tokens, and can't be shared across sessions.

agentibrain is the filesystem-first alternative. Memory lives outside the model, in a structured markdown vault you can open in Obsidian. A scheduled tick (deterministic + LLM-assisted) writes hot arcs, signals, decay, and synthesis into the vault. A single HTTP kernel fans that vault out to every agent in your fleet over a tiny REST contract.

Four services, one vault, one HTTP contract — no AWS lock-in, no proprietary storage, no vendor SDK.

What you get

flowchart LR
    %% =======================
    %% Agent fleet (consumers)
    %% =======================
    subgraph FLEET["Agent fleet"]
        direction TB
        A1["Claude Code<br/>(laptop)"]
        A2["agenticore pods<br/>(K8s)"]
        A3["scheduled jobs<br/>(cron)"]
    end

    %% =======================
    %% The kernel
    %% =======================
    subgraph KERNEL["agentibrain-kernel"]
        direction TB
        subgraph EDGE["Edge — HTTP &amp; MCP"]
            direction TB
            KB["brain-api :8103<br/>/feed · /signal · /marker<br/>/tick · /ingest<br/>/vault/list · /vault/read<br/>/vault/search · /vault/write_inbox"]
            MCP["mcp :8104<br/>kb_search · kb_brief<br/>brain_search_arcs<br/>brain_get_arc"]
        end
        subgraph CORE["Embed"]
            direction TB
            EMB["embeddings :8102<br/>pgvector ingest + query"]
        end
        subgraph LOOP["Brain loop"]
            direction TB
            TICK["brain-ops<br/>cluster · synthesise · inject<br/>(every 2 h)"]
        end
    end

    %% =======================
    %% Inference
    %% =======================
    LITELLM["LiteLLM gateway<br/>(external)"]

    %% =======================
    %% Persistence
    %% =======================
    subgraph STATE["State"]
        direction TB
        VAULT[("Markdown vault<br/>frontal-lobe · amygdala<br/>pineal · left · right<br/>brain-feed")]
        PG[("Postgres + pgvector<br/>arc embeddings")]
        REDIS[("Redis streams<br/>events:brain")]
    end

    %% =======================
    %% Wiring
    %% =======================
    A1 -->|HTTP · Bearer| KB
    A2 -->|HTTP · Bearer| KB
    A3 -->|cron| KB
    A1 ==>|MCP| MCP
    A2 ==>|MCP| MCP

    KB --> EMB
    KB --> LITELLM
    KB -. "vault read/write" .-> VAULT
    KB -. "/signal" .-> REDIS

    MCP --> EMB
    MCP --> KB

    EMB <--> PG

    TICK --> VAULT
    TICK --> EMB
    TICK -. "hot-arc fan-out" .-> REDIS

    %% =======================
    %% Styling (GitHub-safe)
    %% =======================
    classDef client fill:#06b6d4,stroke:#0284c7,color:#fff
    classDef edge fill:#8b5cf6,stroke:#7c3aed,color:#fff
    classDef core fill:#10b981,stroke:#059669,color:#fff
    classDef loop fill:#f59e0b,stroke:#d97706,color:#fff
    classDef store fill:#6366f1,stroke:#4338ca,color:#fff
    classDef ext fill:#94a3b8,stroke:#64748b,color:#fff
    class A1,A2,A3 client
    class KB,MCP edge
    class EMB core
    class TICK loop
    class VAULT,PG,REDIS store
    class LITELLM ext

Plus an opt-in brain-keeper agent (ops oracle for triage, enrichment, replay) and six Helm charts for Kubernetes (brain-api, embeddings, mcp, brain-ops, brain-keeper).

Install

0. CLI only (PyPI)

See Quick Start — pip install agentibrain is the supported way to run the kernel without a clone. The wheel carries the CLI, the vault-layout templates, the compose template and the SQL migrations.

agentibrain update keeps it current. It resolves how this copy was installed — venv/pip, uv tool, pipx, or an editable checkout — and upgrades that one, comparing against PyPI first so an up-to-date install runs nothing. An editable checkout is left alone; update it with git pull.

agentibrain update                     # upgrade if PyPI has a newer release
agentibrain update --check             # report only, install nothing
agentibrain update --index-url <url>   # upgrade from a custom package index

1. Laptop (Docker Compose)

git clone https://github.com/The-Cloud-Clockwork/agentibrain-kernel.git
cd agentibrain-kernel
./local/bootstrap.sh           # writes .env (random tokens) + scaffolds ~/agentibrain-vault
docker compose up -d           # 8 containers come up

Note: the default Compose stack builds the 4 service images locally from services/*/Dockerfile on first run (~5 min). To pull pre-built images instead, see Images & forking.

Smoke test:

TOK=$(grep ^KB_ROUTER_TOKEN ~/.agentibrain/.env | cut -d= -f2)   # clone path: ./.env
curl -H "Authorization: Bearer $TOK" http://localhost:8103/feed | jq .

You should see hot_arcs, inject_blocks, entries. On a fresh vault these arrays start mostly empty — they fill as ticks run and as you write markers.

Add a local LLM (Ollama, no API key needed):

docker compose -f compose.yml -f local/compose.ollama.yml up -d
docker compose exec ollama ollama pull llama3.2

Three more inference overlays in examples/compose/ — Ollama, OpenAI direct, LiteLLM gateway. Full local guide: local/README.md.

Updating a Compose deployment

Because Compose builds from this source tree, new code reaches your containers only when you rebuild. docker compose up -d on its own reuses the existing image and silently keeps running the old code:

git pull
agentibrain build                # = docker compose up -d --build, auto-locates the stack
docker compose ps

Volumes and the vault survive; only down -v destroys them. Per-service rebuilds, branch choice (dev vs main), and how to verify the new code is actually live: local/README.md.

2. Server (Docker Compose, headless)

Same compose.yml works on any Linux box with Docker. Bind the vault to a real path, point your fleet at it via BRAIN_URL. No Kubernetes required.

What is reachable, and what is not. Postgres, Redis, MinIO, embeddings and Ollama bind 127.0.0.1 — nothing outside the machine has any business reaching them, and several still carry generated default credentials. Only brain-api (8103) and mcp (8104) are published on all interfaces, because a client-only install needs exactly those two. Narrow them with BIND_HOST:

BIND_HOST=127.0.0.1 docker compose up -d   # loopback only; put a proxy in front

Auth fails closed. brain-api refuses to serve without a bearer: every endpoint answers 503 until KB_ROUTER_TOKEN (or KB_ROUTER_TOKENS, a comma-separated list) is set. install always generates one, so an empty token set means the deployment is misconfigured — never that it wanted to be public. Put a reverse proxy in front for TLS if you expose it beyond a trusted network; the bearer is authentication, not transport security.

3. Kubernetes (Helm)

Six charts ship in helm/ — brain-api, embeddings, mcp, brain-ops, brain-keeper. The first four depend on tcc-k8s-service-template:0.3.8 (vendored as .tgz under each chart's charts/ for offline install). brain-ops is a custom 3-template chart for the CronJob + amygdala consumer.

Step 1 — Scaffold the vault on persistent storage

Copy the template tree straight onto the volume:

git clone https://github.com/The-Cloud-Clockwork/agentibrain-kernel
cp -r agentibrain-kernel/agentibrain/templates/vault-layout/* /mnt/<your-export>/

The kernel images expect this layout under /vault (see docs/VAULT-SCHEMA.md). Idempotent — re-running just refreshes any missing files.

Step 2 — Provision Secrets

Path A — plain Opaque Secret (simplest, no External Secrets Operator):

./local/k8s-bootstrap.sh --apply -n <your-namespace>

Creates three Secrets (agentibrain-router-secrets, embeddings-secrets, agenticore-secrets) with random tokens. Tokens persist in local/.k8s-tokens for re-use.

Path B — External Secrets Operator (GitOps-tracked): Wire your secrets manager (OpenBao / AWS Secrets Manager / Vault) via an ESO ClusterSecretStore, then set externalSecret.enabled: true in your values overlay. Full walkthrough: docs/SECRETS.md.

Step 3 — helm install the six charts

helm install agentibrain-brain-api    ./helm/brain-api    -f values-brain-api.yaml
helm install agentibrain-embeddings   ./helm/embeddings   -f values-embeddings.yaml
helm install agentibrain-mcp          ./helm/mcp          -f values-mcp.yaml
helm install agentibrain-brain-ops   ./helm/brain-ops   -f values-brain-ops.yaml   # singleton, deploy ONCE per cluster
helm install agentibrain-brain-keeper ./helm/brain-keeper -f values-brain-keeper.yaml # OPTIONAL ops oracle (see note below)

Each values-*.yaml overlay sets:

• extraVolumes → NFS server + path or PVC claim for the vault from step 1 (brain-api mounts vault at /vault)
• env.variables.INFERENCE_URL + BRAIN_CLASSIFY_MODEL + BRAIN_BRIEF_MODEL → your LLM gateway + model names
• secrets.external.secretRef → the Secret from step 2

Sample overlays + ArgoCD Application CRs ship in examples/ — copy, replace every <your-*> placeholder, deploy.

Note on brain-keeper — this StatefulSet is the optional ops-oracle agent for triage / enrichment / replay. It runs the agenticore image, which is built and published by that upstream repo, not by this kernel. The brain functions fully without brain-keeper — skip the chart if you don't need it, or fork agenticore and override image.repository to deploy under your own namespace.

Optional — ArgoCD instead of helm install

Same outcome, declarative. Copy examples/argocd/ into your platform repo, swap placeholders, kubectl apply -f the agentibrain-root.yaml. ArgoCD picks up the per-service Apps and the chart sources point back at this kernel repo via multi-source.

Once running, every agent in your fleet gets two env vars and consumes the brain over HTTP:

BRAIN_URL: http://agentibrain-brain-api.<your-namespace>.svc:8080
KB_ROUTER_TOKEN: <from-the-secret-in-step-2>

Architecture reference: docs/architecture/ARCHITECTURE.md. Generic deployment guide: docs/DEPLOYMENT.md.

Connect Claude Code

After install, register the kernel's MCP server with Claude Code so the agent can reach the brain via six tools (kb_search, kb_brief, brain_search_arcs, brain_get_arc, brain_ingest, brain_tick).

Laptop (Docker Compose)

Add to ~/.claude/.mcp.json or your project-local .mcp.json:

{
  "mcpServers": {
    "agentibrain": {
      "type": "sse",
      "url": "http://localhost:8104/sse"
    }
  }
}

Restart Claude Code, then verify with /mcp — the agentibrain server should appear with 6 tools (mcp__agentibrain__kb_search, etc.).

Note: the local compose stack runs mcp-proxy without auth (localhost-only). For production deployments, set MCP_PROXY_API_KEY on the container and use x-api-key header.

Kubernetes (agent-mode pod)

For Claude Code running in agent mode inside a pod, point at the in-cluster Service URL of the mcp chart:

{
  "mcpServers": {
    "agentibrain": {
      "type": "sse",
      "url": "http://agentibrain-mcp.<your-namespace>.svc:8080/sse",
      "headers": {
        "x-api-key": "${MCP_PROXY_API_KEY}"
      }
    }
  }
}

Inject MCP_PROXY_API_KEY via envFrom: secretRef: from the K8s Secret backing the mcp chart (agentibrain-mcp-secrets by default).

agentihooks profile (required for Claude Code brain injection)

agentihooks (PyPI) is the hook framework that wires AgentiBrain into Claude Code sessions. Without it, agents can query the brain via MCP tools but won't receive automatic context injection, marker capture, or amygdala alerts.

pip install agentihooks
agentibrain install

The brain profile registers three hooks:

The bundled profile ships the local SSE server only. agentibrain/profiles/brain/.claude/.mcp.json contains a single entry — agentibrain-local (type: sse → http://localhost:8104/sse), pointing at the local Docker-Compose stack. No remote entry is bundled: the mcp chart's Service is ClusterIP with no Ingress, so agentibrain-mcp.<ns>.svc:8080 resolves only inside the cluster — usable from in-cluster agent pods (see Kubernetes above), unreachable from anywhere else.

To reach the brain MCP from outside the cluster, expose it on a routable surface — an Ingress, or behind an MCP gateway — then add your own entry. Whichever you choose, authenticate with the x-api-key header (not Authorization: Bearer), path /mcp (streamable HTTP) or /sse, key MCP_PROXY_API_KEY.

Full reference (incl. LiteLLM gateway path): docs/MCP.md.

Images & forking

The kernel publishes 4 service images via GitHub Actions. Standard consumers don't build anything — pull and go.

CI: .github/workflows/docker-build.yml runs on every push to dev (→ :dev). main is the snapshot branch — reached only by a reviewed dev → main PR, it publishes no image and deploys nothing. :latest does not exist; a config naming it will fail to pull.

For forkers: push to your fork's dev or main, the same workflow runs under your namespace and publishes to ghcr.io/<your-org>/agentibrain-*. Edit each chart's image.repository (or your values overlay) to point at your namespace. The vendored tcc-k8s-service-template-0.3.8.tgz makes helm install work offline; refresh from upstream with helm dep update helm/<chart>.

The agenticore image used by the optional brain-keeper chart is built by the agenticore repo, not here.

HTTP contract

Bearer auth via KB_ROUTER_TOKEN on every endpoint. Base URL below is $BRAIN_URL.

GET /feed — hot arcs + inject blocks

curl -s "$BRAIN_URL/feed" -H "Authorization: Bearer $KB_ROUTER_TOKEN"

{
  "hot_arcs":      [ { "id", "title", "content", "priority", "ttl", "severity" }, ... ],
  "inject_blocks": [ ... ],
  "entries":       [ ... ],
  "generated_at":  "2026-04-27T18:08:00+00:00",
  "hash":          "c4d87ac3f961be48",
  "entry_count":   5
}

Cached server-side for FEED_CACHE_TTL_SECONDS (default 30s). Read on every agent's SessionStart.

GET /health — liveness probe

Returns { "status": "ok" }.

GET /signal — current amygdala alert

Empty amygdala-active.md → { "active": false, ... }. Dedup via hash.

POST /marker — emit a brain marker

curl -s -X POST "$BRAIN_URL/marker" \
  -H "Authorization: Bearer $KB_ROUTER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: session-abc-first-lesson" \
  -d '{"type":"lesson","content":"NFS dirs need 777 for UID 1000 writers","attrs":{"source":"deploy"}}'

Idempotency-key window 1h (configurable via IDEMPOTENCY_TTL_SECONDS). Replay returns the original response with idempotent_replay: true.

POST /tick — request a manual agentibrain tick

File-protocol: writes a request to brain-feed/ticks/requested/. The tick-drain worker picks it up and moves it to completed/ or failed/. Poll GET /tick/{job_id}.

CLI wrapper: agentibrain tick [--dry-run] [--no-ai] [--wait]. With --wait, blocks until the job leaves requested/.

POST /ingest — universal ingest

Free-text in. The model named in BRAIN_CLASSIFY_MODEL classifies via your inference gateway (any OpenAI-compatible — see docs/GATEWAY-CONTRACT.md), fans URLs/repos/files to artifact-store, drops a markdown note in raw/inbox/. Spec: api/openapi.yaml.

POST /ingest_with_files — multipart ingest

Same as /ingest but accepts file attachments as multipart/form-data.

POST /index_artifact — sole brain-side embedding write

Per-artifact embedding write surface. Called by ingest pipelines after artifact-store accepts a blob. Every embed flows through this endpoint. Spec: api/openapi.yaml.

Vault endpoints

All vault reads and writes flow through brain-api (which mounts /vault directly):

Vault schema

Obsidian-compatible folder tree, writable by humans and by kernel services. agentibrain scaffold is the authoritative writer of the schema marker; local/bootstrap.sh invokes it on first run.

<vault>/
  .brain-schema           # version marker (JSON)
  README.md  CLAUDE.md    # vault rules for AI agents

  # Cognitive regions (owned by brain-ops + daemons)
  raw/{inbox,articles,media,transcripts}/
  clusters/               # canonical arc storage
  brain-feed/             # /feed reads here, /tick writes ticks/requested/
  amygdala/               # /marker type=signal lands here
  frontal-lobe/{conscious,unconscious}/
  pineal/                 # joy + breakthrough region

  # Knowledge base (operator owns — agents curate)
  identity/               # who you are — root node
  left/                   # technical hemisphere — projects, research, reference, decisions, incidents
  right/                  # creative hemisphere — ideas, strategy, life, creative, risk
  bridge/                 # cross-hemisphere synthesis
  daily/                  # append-only daily logs

  templates/mubs/         # VISION SPECS BLOCKS TODO STATE BUGS KNOWN-ISSUES ENHANCEMENTS MVP PATCHES

Scaffold is idempotent. Schema-version mismatch is a hard error unless --force-upgrade is passed. Full reference: docs/VAULT-SCHEMA.md.

Configuration

Local mode reads from .env (generated by bootstrap.sh). K8s mode reads from a Secret (Opaque or ESO-synced from your secret store — see docs/SECRETS.md).

Observability

The kernel ships a starter Grafana dashboard at observability/brain-health.json — drop it into Grafana to get an immediate picture of the brain's pulse: hot arcs, emergency signals, broadcast traffic, tick cadence, memory markers, and hook health. 27 panels across six brain regions (frontal lobe · amygdala · broadcast cortex · pineal · hippocampus · hook observability), so the layout maps onto the same terminology the kernel uses internally.

How to wire it. The JSON is a mock — every panel queries a grafana-clickhouse-datasource with uid: clickhouse, against the brain.* schema that services/brain-ops writes into ClickHouse on every tick (brain.tick_health, brain.signals, brain.arcs, brain.lessons, brain.embeddings, …). To go from mock to live:

1. Import — in Grafana, Dashboards → New → Import → paste observability/brain-health.json.
2. Datasource — install the ClickHouse datasource plugin, point it at the ClickHouse instance the brain-ops writes to, and either name its uid clickhouse or remap the dashboard's datasource at import time.
3. Schema — the queries assume the brain-ops's default table layout. If you've renamed tables or split databases, edit the panel rawSql blocks — column names match the BrainTickHealth model in services/brain-ops/brain_tick.py.
4. Refresh — default cadence is 30s over a now-6h window; override per your appetite.

If you don't run ClickHouse, the JSON is still useful as a panel layout reference — swap each rawSql for the equivalent in your TSDB of choice and keep the structure.

Development

git clone https://github.com/The-Cloud-Clockwork/agentibrain-kernel
cd agentibrain-kernel
python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'

pytest tests/unit                              # scaffold + compose tests
PYTHONPATH=services/brain-api:. pytest services/brain-api/tests -q   # service tests

docker build -t agentibrain-brain-api:local services/brain-api

Workflow: dev is the working branch and the deploy branch. CI on dev ships :dev GHCR images automatically. main is vestigial.

Status

v0.1.x — stable. Six Helm charts. Four service images auto-published to GHCR (:dev only — nothing publishes :latest). HTTP contract frozen at v1. Generic OpenAI gateway — kernel speaks chat-completions to any compatible upstream (LiteLLM, OpenAI, Ollama, vLLM, …). Brain-blind boundary in place since 2026-04-26 (artifact-store no longer auto-embeds; every embed flows through POST /index_artifact). Vault read/write absorbed into brain-api directly via vault_reader module — no separate reader service.

The kernel is self-contained and the canonical source of truth for everything brain-related — services, Helm charts, brain-keeper agent definition (agents/brain-keeper/), brain profile overlays (agentibrain/profiles/brain/), and the vault layout schema. All deployment-specific plumbing (cluster namespaces, model name aliases, secret-store paths, NFS hosts) lives in your own platform repo, not here.

Maturity tracking is published in docs/architecture/MATURITY.md.

Further reading

• docs/architecture/ARCHITECTURE.md — full kernel design
• docs/architecture/CLUSTERS.md — arc lifecycle
• docs/architecture/KEEPER.md — brain-keeper agent
• docs/architecture/MARKERS.md — marker grammar
• docs/architecture/SYMBIOSIS.md — relation to agenticore + agentihooks
• docs/architecture/TELEMETRY.md — OTel + Langfuse
• docs/MCP.md — MCP server, Claude Code wiring, LiteLLM gateway
• docs/SECRETS.md — Opaque Secrets vs ESO
• docs/DEPLOYMENT.md — multi-source ArgoCD pattern
• docs/VAULT-SCHEMA.md — vault layout v1
• api/openapi.yaml — HTTP contract

License

MIT.