vantabrain

██████████                                      ·�·
                █▓       ░██                                           ✧
                █▒        ██ T H E   P I N A C L E  O F  H A K C I N G   Q U A L I T Y
    █████████████░        █████████████████ ████████████ ████████████      ████████████
   ██         ███░        ███▓▒▒▒▒▒▒▒▒▒▒▒██ █▒▒▒▒▒▒▒▒▓████        █████████▓          ▒█
   ██  ✧      ███         ███▒▒▒▒▒▒▒▒▒▒▒▒▓██████████████▓        ███▓▒      ▒▓░       ▒█
   ██         ███        ░██▓▒▒▒▒▒▒▒▒▒▒▒▒▒▓██▓▒▒▒▒▒▒▒▒█▓        ███░       ░██░       ▒█
   ██         ███        ▒██▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒██▓▒▒▒▒▒▒▒▓▒        ██  ▓        ██░  ◆   ▓█
   ██         ██▓        ███▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒█▓▒▒▒▒▒▒▒▓▒       ██   █        ██░       ▓
   ██         ██▒        ██▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓▒▒▒▒▒▒▒▓▒      ██    █        ▓█████████
   ██     ★              ██▒▒▒▒▒▒▒▒█▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▒   ▒███████ █░       ░▓        █
   ██         ░░         ██▒▒▒▒▒▒▒▒██▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓█ ▓        ░█ ▓       ░▒       ░█
   ██         ██░       ░█▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓█ █░        ▒ █                ░█
   ██   ·     ██        ▓█▒▒▒▒▒▒▒▒▒██▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓█ █░        ▒ █░               ▒█
    ██████████  ███████████▓██▓▓█▓█  █▓▒▒▒▒▒▒▒▒▒▓██▓██   █▓▓▓▓▓▓▓█    █▓▓▓▓▓▓/\▓▓▓▓▓▓██ 
  .:/____________________ █▓██▓██ ________ ████▓█▓████ _ ________________.  /  \.______\:.
     _ __ _______________  ██▓██ __________ █▓▓▓██ ██ __________________. \/ /\.____ ___
                             █▓█             ██▓██                       \  /
                              ██               ███                        \/

Persistent memory and session governance for AI coding agents.

What it is

vantabrain is a self-hosted memory layer for AI coding agents. It exposes a vault of notes (kernel, learnings, patterns, sessions, projects) to any agent that speaks the Model Context Protocol, surfaces fleet and account state through a web dashboard, and ships an optional Jira integration that turns tickets into the unit of accountability for AI sessions.

It is built for engineers who want their AI tools to remember what happened yesterday across machines, accounts, and projects, without trusting a third party to hold that memory. Bring your own PostgreSQL, point your AI agent at the MCP server, and the vault is yours.

Architecture

flowchart LR
  subgraph clients["Clients"]
    cc["Claude Code"]
    other["Any MCP client"]
    cli["CLI (Ink TUI)"]
    vsx["VS Code extension"]
  end

  subgraph core["Core"]
    mcp["MCP server<br/>(23 tools)"]
    web["Web dashboard<br/>:3300"]
    auth["Auth service<br/>:3200 (optional)"]
  end

  subgraph data["Data"]
    pg[("PostgreSQL<br/>+ pgvector")]
  end

  subgraph optional["Optional"]
    jira["Jira integration<br/>(dc CLI + daemon)"]
    jiraapi["Jira REST API"]
  end

  cc -- "stdio MCP" --> mcp
  other -- "stdio MCP" --> mcp
  cli -- "http" --> web
  vsx -- "http" --> web
  mcp <--> pg
  web <--> pg
  auth <--> pg
  mcp -. "JWT (multi-user)" .-> auth
  jira <--> pg
  jira <--> jiraapi

Quick start

Install

curl -fsSL https://raw.githubusercontent.com/haKC-ai/vantabrain/main/install.sh | bash

Or clone and run components manually:

git clone https://github.com/haKC-ai/vantabrain.git
cd vantabrain

Configure

cp .env.example .env
$EDITOR .env       # set DATABASE_URL (required), JIRA_* (optional), etc.

Every variable is documented in docs/env-vars.md.

Run

# MCP server (stdio)
cd mcp && npm install && node server.js

# Web dashboard (separate terminal)
cd web && npm install && npm run dev      # http://localhost:3300

# Optional Jira integration
cd integrations/jira && pip install -e . && dc bootstrap

# Optional VS Code extension
code --install-extension vscode/vantabrain-0.2.5.vsix

Wire Claude Code to the MCP server by copying _claude/settings.template.json to ~/.claude/settings.json and adjusting the paths.

Features

• MCP server — 23 tools covering vault recall, capture, fleet status, account routing, and live session management. See docs/mcp-tools.md.
• Web dashboard — Hono server on :3300 with a SPA showing session activity, account usage, fleet state. See docs/architecture.md.
• CLI — Ink-based TUI for routing, enrollment, status, account switching, live mode.
• VS Code extension — six sidebar panels, two status-bar indicators, and a Live Brain HUD webview. Talks only to the local dashboard. See vscode/README.md.
• Auth service — optional Hono service that issues JWTs after TOTP verification. Off by default.
• Jira integration — Python dc CLI for session governance and ticket lifecycle. See docs/jira-integration.md.
• Claude Code wiring — ships generic agent definitions and a /vantabrain skill router under _claude/.

MCP tools

Tool	Description
get_kernel	Pull identity, patterns, anti-patterns, rules, tools. Call at session start.
recall	Load relevant notes by topic.
remember	Write a fact, decision, or architecture note. Compressed before storage.
learn	Append a new learning. Idempotent on similar slugs.
session_log	End-of-session log with optional learned / used / errors / next arrays.
track_pattern	Record a pattern that worked or didn't.
link_notes	Add a wikilink between two notes.
vault_status	Note counts by directory, recent activity log, git status.
fleet_status	Local Claude Code projects plus remote SSH hosts.
route_status, route_set_policy, route_handoff	Multi-account routing.
live_toggle, session_list, session_resume	Live-mode session management.

Full signatures and inputs: docs/mcp-tools.md.

Optional Jira integration

The integrations/jira/ subtree ships a self-contained Python package (micromanage) that adds session governance and ticket lifecycle management on top of any Atlassian Jira project. It is optional — the MCP server, dashboard, and CLI all work without it.

flowchart TB
  user["Developer"]
  cli["dc CLI"]
  hook["git pre-commit / pre-push hooks"]
  sweeper["Sweeper daemon<br/>(systemd)"]
  pg[("PostgreSQL")]
  jira["Jira REST API<br/>(your-jira-project)"]

  subgraph states["Session lifecycle"]
    direction LR
    active["Active"] --> idle["Idle<br/>(15 min)"]
    idle --> stale["Stale<br/>(2 hours)"]
  end

  user -- "dc session start" --> cli
  user -- "dc ticket claim PROJ-N" --> cli
  cli <--> pg
  cli <--> jira
  hook -- "verify CLAIM/PROGRESS" --> cli
  sweeper <--> pg
  sweeper -- "post STALE comment" --> jira
  cli --> states

Set JIRA_PROJECT_KEY, JIRA_URL, JIRA_USER_EMAIL, JIRA_API_KEY, and DATABASE_URL, then run dc bootstrap. Full docs at integrations/jira/README.md.

Configuration

Variable	Required	Purpose
DATABASE_URL	yes	PostgreSQL connection string. pgvector extension required.
BRAIN_HOME	no	Where the repo is checked out. Defaults to $HOME/VantaBrain.
JWT_SECRET	only if running auth/	Signs refresh tokens.
BRAIN_AUTH_URL	only if multi-user	MCP server requires JWTs from this URL.
JIRA_URL, JIRA_USER_EMAIL, JIRA_API_KEY, JIRA_PROJECT_KEY	only for dc CLI	All four required for the Jira integration. dc fails loud if any is unset.
DASHBOARD_URL	no	Web dashboard URL. Defaults to http://localhost:3300.

Full list in docs/env-vars.md. See .env.example for placeholder values.

Development

Run tests locally:

# MCP server tests
cd mcp && npm install && node --test test/

# Jira integration tests
cd integrations/jira && pip install -e '.[dev]' && pytest -v

Run the secret-scan checks locally before opening a PR:

# gitleaks (filesystem mode, mirrors CI)
gitleaks detect --no-git --redact

# trufflehog (filesystem mode, mirrors CI)
trufflehog filesystem . --no-update --json

Both checks run on every PR and push to main via .github/workflows/ci.yml. Do not weaken them.

See CONTRIBUTING.md for PR conventions.

Security

Report vulnerabilities through GitHub's private reporting — see SECURITY.md.

License

MIT — see LICENSE.