AgentiBrain

The brain + KB substrate for Claude Code agent fleets — services, Helm charts, agent definition, profile overlays, and the vault schema, in one self-contained kernel.

Get Started Concepts View on GitHub

---

What you get

flowchart LR
    Agent["Claude Code agent"] -->|HTTP| KB["brain-api\n/feed /signal /marker /tick /ingest"]
    Agent -->|MCP| MCP["agentibrain-mcp\nkb_search · kb_brief · brain_search_arcs · brain_get_arc"]
    MCP -->|/vault/search| KB
    KB --> Vault[("Obsidian vault\nleft / right hemisphere")]
    KB --> Embed["embeddings"]
    Embed --> PG[("Postgres + pgvector")]
    Tick["brain-ops"] --> CH[("ClickHouse\nbrain.tick_health")]
    Tick --> Vault
    Keeper["brain-keeper agent"] --> KB
    Keeper --> MCP

• 4 service images auto-published to GHCR — brain-api, embeddings, mcp, brain-ops.
• 5 Helm charts — brain-api, embeddings, mcp, brain-ops, brain-keeper.
• Brain-keeper agent definition in-tree (agents/brain-keeper/) — drop-in Claude Code custom agent.
• Brain profile overlays for agentihooks — markers, broadcast channels, hook wiring.
• Vault schema v1 — six-region Obsidian vault layout that the kernel writes to.
• HTTP contract frozen at v1 — see api/openapi.yaml.
• Generic OpenAI gateway — kernel speaks chat-completions to any compatible upstream (LiteLLM, OpenAI, Ollama, vLLM, …).

---

Install

The kernel ships in exactly two shapes — Docker Compose for local / isolated environments, Helm for fleet-scale Kubernetes. There is no PyPI / pip install path; the kernel runs as containers, not as a Python library.

1. Local (Docker Compose)

git clone https://github.com/The-Cloud-Clockwork/agentibrain-kernel
cd agentibrain-kernel
./local/bootstrap.sh                  # mints tokens, scaffolds vault + .env
docker compose up -d                  # four services on localhost

See local/README.md for the laptop walkthrough.

2. Kubernetes (Helm)

helm dep update helm/brain-api
helm install brain-api helm/brain-api -n brain --create-namespace
# repeat for embeddings, mcp, brain-ops, brain-keeper

Bare-cluster path with no platform prerequisites — see docs/HELM-QUICKSTART.md. For ArgoCD + ESO + multi-source patterns: docs/DEPLOYMENT.md.

---

Connect Claude Code

Laptop — .mcp.json

{
  "mcpServers": {
    "agentibrain": {
      "url": "http://localhost:8104/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_PROXY_API_KEY}"
      }
    }
  }
}

Agent mode (in-cluster)

{
  "mcpServers": {
    "agentibrain": {
      "url": "http://agentibrain-mcp.<your-namespace>.svc:8080/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_PROXY_API_KEY}"
      }
    }
  }
}

Full wiring + auth notes: docs/MCP.md.

---

Where to next

The sidebar groups every page into four sections — pick the one that matches your goal:

• Concepts — what the brain is, why arcs/markers/MCP, the philosophical groundwork.
• Reference — HTTP API, MCP tools, vault schema, marker grammar, gateway contract.
• Operate — Helm install, deployment patterns, secrets, day-2 ops, troubleshooting.
• Architecture — services, data plane, the brain-keeper agent, telemetry, maturity rubric.

---

Status

v0.1.1 — first stable. Five Helm charts, four service images on GHCR (:dev from dev branch, :latest from main), HTTP contract frozen at v1, brain-blind boundary in place since 2026-04-26 (artifact-store no longer auto-embeds; every embed flows through POST /index_artifact).

The kernel is self-contained and the canonical source of truth for everything brain-related — services, Helm charts, brain-keeper agent definition, brain profile overlays, 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.