hive-exp

AI Agent Experience Management System — structured, cross-agent, human-reviewed knowledge for your AI tools.

What is hive-exp?

When an AI agent solves a non-trivial problem — a TypeScript compiler error, a broken build, a failing test — the solution disappears the moment the session ends. The next time the same error appears (in a different project, by a different agent, even by the same agent tomorrow), the work starts from zero. hive-exp fixes this by recording experiences: structured JSON objects with a canonical signal → strategy → outcome shape, persisted locally and queryable in milliseconds.

Knowledge does not stay siloed per-agent. Because hive-exp speaks the Model Context Protocol (MCP), Claude Code, Codex, Gemini CLI, Cursor, and Windsurf all read and write the same experience store. An experience recorded by Claude Code while fixing a TypeScript path alias issue is immediately available to Codex the next time it encounters the same signal. The experience store is a shared brain, not a per-agent scratch pad.

Humans stay in the loop. Experiences start as provisional and can only be promoted to the trusted zone by an explicit human action — via the CLI or the dashboard. Confidence decays over time using an exponential half-life model; experiences that accumulate consecutive failures or go 30 days without a single reference are auto-archived. The dashboard gives you a live view of every experience, its current confidence, and its usage statistics.

Related MCP server: cortex-brain

Quick Start

# Install CLI globally
npm install -g hive-exp

# Initialize for your AI agents (auto-detects installed agents)
hive-exp init --force

# Or run the MCP server directly
npx @hive-exp/mcp

Agent Configuration

hive-exp init --force writes the correct snippet automatically. To configure manually:

Claude Code — ~/.mcp.json

{
  "mcpServers": {
    "hive-exp": {
      "command": "npx",
      "args": ["-y", "@hive-exp/mcp"]
    }
  }
}

Codex — ~/.codex/config.toml

[mcp_servers.hive-exp]
type = "stdio"
command = "npx"
args = ["-y", "@hive-exp/mcp"]

Gemini CLI — ~/.gemini/mcp.json

{
  "mcpServers": {
    "hive-exp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@hive-exp/mcp"],
      "env": {}
    }
  }
}

Antigravity — ~/.gemini/antigravity/mcp_config.json

{
  "mcpServers": {
    "hive-exp": {
      "command": "npx",
      "args": ["-y", "@hive-exp/mcp"]
    }
  }
}

Cursor — .cursor/mcp.json

{
  "hive-exp": {
    "command": "npx",
    "args": ["-y", "@hive-exp/mcp"]
  }
}

Windsurf — .windsurf/mcp.json

{
  "hive-exp": {
    "command": "npx",
    "args": ["-y", "@hive-exp/mcp"]
  }
}

CLI Commands

MCP Tools

The MCP server exposes five tools to connected agents:

Dashboard

# Start the dashboard (requires the CLI to be installed)
hive-exp dashboard

# Or start directly from source
npx tsx apps/dashboard/src/server.ts

The dashboard runs at http://localhost:3333 and shows all experiences, their current confidence scores, usage statistics, and a promotion queue for human review.

Architecture

packages/core/           — Core library (schema, events, signer, sanitizer, consensus, cron)
packages/mcp/            — MCP Server (5 tools, stdio transport, zero external dependencies)
packages/signer-ed25519/ — Optional Ed25519 signer (drop-in replacement for HMAC-SHA256)
apps/cli/                — CLI tool (10 commands)
apps/dashboard/          — Web dashboard (Express + HTML/CSS/JS)
hooks/                   — Claude Code PostToolUse hook (signal-detector.py)

Data is stored under ~/.hive-exp/ by default:

~/.hive-exp/
├── experiences/
│   ├── provisional/   — New, unreviewed experiences
│   ├── promoted/      — Human-confirmed trusted experiences
│   ├── archived/      — Auto-archived (zero-ref, low-confidence, consecutive fail)
│   └── superseded/    — Dedup-superseded experiences (backup)
├── events/            — Append-only JSONL event log (yyyy-mm.jsonl)
├── db.sqlite          — SQLite projection for fast queries
└── signal-conventions.yaml

How It Compares

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.

Python SDK coming soon.