hive-exp

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

<p align="center"> <strong>English</strong> | <a href="README_CN.md">简体中文</a> </p>

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.

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

Command	Description
hive-exp init [--force] [--agent <type>]	Auto-detect AI agents and write MCP configuration
hive-exp add [--file <path>] [--signals ...] [--strategy <name>]	Add a new experience record
hive-exp validate <path>	Validate an experience JSON file against the schema
hive-exp sign <path> [--secret <secret>]	Sign an experience file with HMAC-SHA256
hive-exp query [--signal] [--strategy] [--scope] [--limit] [--format]	Query experiences by signal, strategy, or scope
hive-exp promote <exp_id> [--confirm]	Promote an experience to the trusted zone (human confirmation required)
hive-exp archive <exp_id> [--reason]	Archive an experience (soft delete)
hive-exp stats [--type] [--format]	Show strategy statistics and experience health overview
hive-exp replay [--from <date>] [--verbose]	Rebuild SQLite projection from the event log
hive-exp export [--format] [--min-confidence] [--scope] [--agent] [--promoted-only] [--output]	Export experiences for RAG or external consumption

MCP Tools

The MCP server exposes five tools to connected agents:

Tool	Description
hive_exp_query	Search for experiences matching error signals; returns strategies ranked by success rate and confidence
hive_exp_record	Record a new experience after successfully solving a non-trivial problem
hive_exp_outcome	Record the outcome after applying a strategy from a queried experience
hive_exp_stats	Get strategy statistics and experience health overview (overview, strategy_ranking, at_risk)
hive_exp_promote	Propose promoting an experience to the trusted zone (sets pending_promotion; actual promotion requires human confirmation)

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

Feature	hive-exp	Mem0	Letta	Vector DB
Structured signal→strategy→outcome	Yes	No (free-form text)	No	No
Multi-agent cross-vendor sharing	Yes	No	No	No
Human-in-the-loop promotion	Yes	No	Limited	No
MCP native (zero adapter code)	Yes	No	No	No
Confidence decay + auto-archival	Yes	No	No	No
Zero external dependencies (no Docker/Postgres/Neo4j)	Yes	No	No	No

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.

---

Python SDK coming soon.