HAIve

Repo-native context enforcement for AI coding agents.

hAIve turns repo knowledge into enforceable breadcrumbs for agents: load the right context before edits, carry architectural decisions and gotchas into the task, record what was learned, and pass Git/CI policy gates before changes enter the codebase.

npm License Node CI

---

The problem

AI coding agents are powerful, but they often act with incomplete repo context. Compaction, parallel sessions, agent switches, and stale advisory docs all create the same failure mode: the agent changes code without carrying the team's current decisions into the work.

Most teams work around this with instructions and hope:

• "Please read our architecture decisions first."
• "Don't repeat the migration mistake from last sprint."
• "Remember to capture what you learned."
• "Don't merge code that invalidates a team decision."

Those rules are easy to skip. hAIve turns them into repo-native context policy.

---

How it works

AI agent ──▶ hAIve briefing ──▶ code change ──▶ hAIve policy gate ──▶ merge
                  ▲                                       │
                  └── context breadcrumbs · decisions · gotchas · anchors

1. haive init creates a .ai/ context policy layer in your repo.
2. Agents start every session with get_briefing — one MCP call that returns small default context plus deeper breadcrumbs ranked by task relevance.
3. Decisions, gotchas, failed attempts, and session recaps live as Markdown files anchored to the code paths they describe. When code moves, hAIve detects stale anchors.
4. haive enforce check and CI enforcement block unsafe states: missing briefing, stale critical decisions, known anti-patterns, or uncaptured session knowledge.

Memory is the substrate. Context enforcement is the product promise. AI changes should not enter the codebase without consulting the team's current knowledge.

---

Install

npm install -g @hiveai/cli
# Optional: local semantic search (downloads ~110MB model once)
npm install -g @hiveai/embeddings

---

Quick start

1. Initialize your project

cd my-project
haive init          # Creates .ai/, bridge files, MCP config, hooks, CI template

haive init now also runs agent setup. It writes project-level MCP configs, records the best available mode, and asks before changing user-level client configs. In non-interactive shells it skips global config and tells you how to finish setup.

2. Connect your AI client

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "haive": {
      "command": "haive",
      "args": ["mcp", "--stdio", "--root", "/absolute/path/to/my-project"]
    }
  }
}

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "haive": {
      "command": "haive",
      "args": ["mcp", "--stdio", "--root", "/absolute/path/to/my-project"]
    }
  }
}

VS Code:

code --add-mcp '{"name":"haive","command":"haive","args":["mcp","--stdio","--root","/path/to/project"]}'

3. Bootstrap your project context

In your AI client, invoke the bootstrap_project MCP prompt. The agent analyzes your codebase and writes .ai/project-context.md automatically.

4. Start work through hAIve

Every session starts with one call:

get_briefing(task: "add a Stripe payment integration", files: ["src/payments/PaymentService.ts"])

The agent gets project context + relevant module contexts + ranked context breadcrumbs in one shot — no more grepping to rediscover what the team already knows.

For CLI agents without native MCP, wrap them:

haive run -- claude --dangerously-skip-permissions -p "$(cat task.md)"

Check the selected mode any time:

haive agent status
haive agent setup          # re-run setup later
haive agent setup --yes    # approve user-level MCP config without prompting

5. Gate commits and pull requests

haive enforce install       # Installs Git hooks + CI enforcement template
haive enforce status        # Current enforcement posture
haive enforce check         # Pre-commit policy gate
haive enforce ci            # CI entrypoint (exits 1 on violations)

---

What hAIve enforces

Gate	What it checks
Briefing loaded	Agent loaded fresh context breadcrumbs before editing
Decision coverage	Changed files are covered by relevant anchored decisions in the last briefing
Anti-pattern matching	Known bad approaches blocked before commit
Stale anchors	Memories anchored to deleted/moved paths are flagged
Session recap	Agent captured what changed and what remains before closing
CI enforcement	Required check blocks merge on any gate failure

---

.ai/ directory layout

your-project/
├── .ai/
│   ├── project-context.md          # Shared project overview
│   ├── modules/                    # Per-component context files
│   │   ├── backend/context.md
│   │   └── frontend/context.md
│   └── memories/
│       ├── personal/               # Private — gitignored
│       ├── team/                   # Shared — committed to git
│       └── module/<name>/          # Module-scoped memories
├── CLAUDE.md                       # Auto-generated bridge for Claude Code
├── .cursorrules                    # Auto-generated bridge for Cursor
└── .github/
    ├── copilot-instructions.md     # Auto-generated bridge for Copilot
    └── workflows/
        ├── haive-sync.yml          # Anchor verification on merge
        └── haive-enforcement.yml   # Required policy gate

---

Context policy records

Type	Description
decision	Architectural or design choices the team has locked in
gotcha	Non-obvious constraints, known footguns, subtle invariants
convention	Naming, patterns, style rules specific to this codebase
attempt	Failed approaches — so agents don't repeat them
architecture	Component boundaries, interfaces, data flow

All records can be anchored to file paths and symbol names. When anchored code changes, hAIve flags the record as potentially stale.

---

MCP tools reference

Tool	Description
get_briefing	⭐ Project context + decisions + gotchas + ranked breadcrumbs in one call
mem_save	Save repo policy knowledge (decision, gotcha, convention, attempt, architecture)
mem_tried	Record a failed approach so future agents do not repeat it
mem_search	Full-text or semantic search across context records
mem_relevant_to	Ranked context records for a task when project context is already loaded
mem_get	Fetch one context record after a compact briefing/search result
code_map	Look up symbols without manual grep when code-map is indexed
mem_verify	Check anchor freshness, detect stale records
pre_commit_check	Diff against known gotchas, decisions, and stale anchors
mem_session_end	Save end-of-session recap for the next agent

MCP profiles keep the product focused:

• HAIVE_TOOL_PROFILE=enforcement (default): compact coding-agent harness.
• HAIVE_TOOL_PROFILE=maintenance: corpus review, lifecycle, distillation, code-search, and project-context maintenance.
• HAIVE_TOOL_PROFILE=experimental: broader diagnostics such as runtime journal, pattern detection, why-this-file, why-this-decision, and conflict analysis.
• HAIVE_TOOL_PROFILE=full: legacy alias for experimental.

---

MCP prompts reference

Prompt	Description
post_task	⭐ Post-task checklist — capture learnings before closing every session
bootstrap_project	Analyze the codebase and write .ai/project-context.md

---

Packages

Package	Install	Description
@hiveai/cli	npm i -g @hiveai/cli	Main product: init, enforce, run agents, briefing, memory, sync, CI/Git hooks
@hiveai/mcp	bundled into @hiveai/cli	Policy-aware MCP server
@hiveai/core	dependency	Types, schema, anchors, policy primitives, token budgets
@hiveai/embeddings	npm i -g @hiveai/embeddings	Optional: local semantic ranking (bge-small-en-v1.5, fully offline)

---

Benchmark results

Measured on a large Next.js + NestJS monorepo (692 Java + 1 411 TS files), 4 parallel agents, same tasks with and without hAIve:

Metric	Without hAIve	With hAIve	Delta
Tokens consumed	94 559	81 146	−14%
Tool calls	57	17	−70%
Total duration	2 min 45 s	1 min 44 s	−36%
Files read	23	6	−74%
First-pass correctness	✓	✓	—

The main gain isn't token savings — it's eliminating the exploration overhead. Agents with hAIve arrive at the right file, with the right pattern, on the first attempt.

---

CLI reference

# Setup
haive init [--with-ci] [--no-bridges]        # Initialize .ai/ + bridge files
haive enforce install                         # Install Git hooks + CI enforcement
haive enforce status                          # Enforcement posture report
haive index code                              # Build .ai/code-map.json

# Daily use
haive briefing [--task <text>] [--files]     # Print context + relevant memories
haive run -- <agent command>                  # Wrap any CLI agent in hAIve session
haive enforce check [--stage pre-commit]      # Policy gate
haive enforce ci                              # CI entrypoint
haive sync [--since <ref>] [--embed]          # Verify anchors + auto-promote

# Memory
haive memory add --type <type>                # Add a memory
haive memory list [--scope] [--status]        # List memories
haive memory query <text>                     # Full-text search
haive memory approve [<id>|--all]             # Mark as validated
haive memory promote <id>                     # personal → team
haive memory tried                            # Record a failed approach
haive memory verify [--update]                # Check anchor freshness
haive memory import --from <file>             # Import docs as memories

# Semantic search
haive embeddings index                        # Build index (first run: downloads model)
haive embeddings query <text>                 # Semantic search

# Diagnostics
haive doctor                                  # Analyze setup, emit recommendations
haive tui                                     # Interactive terminal dashboard
haive bench                                   # Self-test MCP tools

---

Multi-component projects

For projects with multiple components (frontend/backend/microservices), create one module context per component. get_briefing auto-loads the relevant module context based on the files being edited.

mkdir -p .ai/modules/backend .ai/modules/frontend

cat > .ai/modules/backend/context.md << 'EOF'
# Module: backend
- Spring Boot, Java 17, PostgreSQL
- Always filter by tenantId in every repository query
- Never modify existing Flyway migrations — create V{N+1}__desc.sql
EOF

cat > .ai/modules/frontend/context.md << 'EOF'
# Module: frontend
- React 19, TypeScript, TanStack Query v5
- All API calls go through hooks in features/<domain>/api/
- Env vars must start with VITE_ to be exposed to the client
EOF

---

Development

git clone https://github.com/Doucs91/hAIve.git
cd hAIve
pnpm install
pnpm -r build    # Build all packages
pnpm -r test     # Run tests

Requires Node 20 LTS+, pnpm 9+.

---

Contributing

Issues and PRs are welcome. Please open an issue before starting significant work so we can align on direction.

---

License

Apache 2.0 — see LICENSE.