Hivelore

Hivelore

Your team's hard-won lessons, briefed into every agent session — and enforced at commit time. Repo-native memory and context policy for coding-agent harnesses. Formerly published as hAIve (@hiveai/*).

Hivelore is the team-knowledge layer inside an AI coding-agent harness. It gives agents a feedforward briefing before work starts, then adds feedback gates in MCP, Git hooks, CI, and wrappers so changes cannot quietly bypass repo policy.

A capable model already knows generic best practice. What it cannot guess is your team's arbitrary, repo-specific knowledge: that public ids are id + 100000 prefixed AC-, that the status field must be "OK"/"KO", that you never edit an applied migration. Left to itself, a confident agent invents a plausible answer - clean, tested, green, and wrong by policy. Hivelore carries that unguessable knowledge into the task and blocks the change that's about to violate it.

Hivelore's job is not to replace tests, linters, or observability. It makes the repo-specific knowledge those tools cannot infer available, auditable, and enforceable.

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. Hivelore turns them into repo-native context policy.

How it works

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

1. hivelore 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, Hivelore detects stale anchors.
4. hivelore enforce check and CI enforcement block unsafe states: missing briefing, stale critical decisions, an anchored anti-pattern your diff is about to repeat, 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.

Where Hivelore fits in the harness

Harness engineering is about the environment around the model: feedforward guidance before it acts, feedback sensors after it acts, and workflow gates that keep bad states from landing. Hivelore owns the repo-specific context policy part of that harness.

The narrow positioning is intentional: Hivelore is not a general memory database or an agent dashboard. It is the control layer that helps coding agents act with the validated, non-obvious knowledge of the team.

Scope & boundaries — the three harnesses

Harness engineering regulates three different things about agent-written code. Hivelore deliberatelycovers two of them and treats the third as out of scope, for now.

Why no behaviour harness yet. Verifying functional correctness needs an oracle — an independentsource of truth for what the code should do — and that oracle problem (plus the trap of an agentgrading its own work) is the least-mature part of the field. That territory belongs to your tests,property-based checks, and LLM-evals; Hivelore does not try to replace them. What Hivelore does do is carrythe unguessable intent a behaviour test would otherwise have to encode (status must be OK/KO,public ids = id + 100000) as feedforward context and deterministic sensors — a partial, static sliceof behaviour control, not a runtime functional oracle.

A future, opt-in command/test sensor lane (already scaffolded behindenforcement.runCommandSensors) is the planned bridge toward real behaviour feedback without dilutingthe narrow scope. Until then, treat the behaviour harness as your responsibility, not Hivelore's.

See STABILITY.md for the frozen 1.0 surface and CONTRIBUTING.md to extend Hivelore.

Executable memory sensors

Some gotcha and attempt memories can now carry a sensor block: a deterministic regex guardrailthat scans the added lines of a diff. Sensors turn a documented lesson into a repeatable feedbacksignal, independent of embeddings or model judgment. Autogenerated sensors start as warn; humans canpromote high-confidence ones to block.

hivelore sensors list
hivelore sensors check              # scans git diff --cached
hivelore sensors promote <id> --yes # promote a vetted sensor to block
hivelore sensors export --format grep

Install

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

The 60-second proof — watch a lesson stop a commit

Memory tools remember; Hivelore's difference is that a remembered lesson can refuse the committhat repeats it. Try it on any git repo:

hivelore init -y                     # .ai/ layer + git hooks + 12 agent bridges

# 1. Capture a failed approach (agents do this via the mem_tried MCP tool)
hivelore memory tried \
  --what "importing moment.js" \
  --why-failed "bundle bloat — team standard is date-fns" \
  --instead "date-fns" --paths src/
#    → prints the new memory id, e.g. 2026-07-02-attempt-importing-momentjs

# 2. Give the lesson teeth: a validated, deterministic guardrail
hivelore sensors propose 2026-07-02-attempt-importing-momentjs \
  --pattern "from ['\"]moment['\"]" --severity block
#    Hivelore validates it first: silent on your current code, fires on the mistake.

# 3. Reintroduce the mistake — the commit is refused
echo "import moment from 'moment';" >> src/dates.ts
git add . && git commit -m "add date helper"
#    ✗ Block sensor fired — importing moment.js: use date-fns  (exit 2)

Same diff, same answer, on every machine and in CI — the gate is deterministic by design.Everything lives as reviewable Markdown in .ai/, versioned with your code. rm -rf .ai undoes it all.

Quick start

1. Initialize your project

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

hivelore 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": {
    "hivelore": {
      "command": "hivelore",
      "args": ["mcp", "--stdio", "--root", "/absolute/path/to/my-project"]
    }
  }
}

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

{
  "mcpServers": {
    "hivelore": {
      "command": "hivelore",
      "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 Hivelore

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:

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

Check the selected mode any time:

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

5. Gate commits and pull requests

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

CLI at a glance — the golden path

hivelore --help shows only the commands you use day to day. Everything else (review, import,diagnostics, benchmarks) is one hivelore --advanced --help away — the focused surface is deliberate,not a missing feature.

One vocabulary across CLI and MCP. The memory verbs mirror the MCP tool names, so an agent learnsthem once: hivelore memory save/search/get/delete ↔ mem_save/mem_search/mem_get/mem_delete(the older add/query/show/rm still work as aliases).

Try it on your repo (5 minutes, reversible)

Want to evaluate Hivelore on a real codebase that isn't a toy? It is non-destructive — everything itwrites lives under .ai/ plus a few bridge files, all removable.

cd your-project
npm install -g @hivelore/cli
hivelore init -y            # seeds stack packs + git-history scars; writes .ai/ and bridges
hivelore briefing --task "the change you're about to make" --files path/to/file
hivelore doctor             # health + coverage report
hivelore sensors check      # scan your staged diff against documented lessons
hivelore eval --fail-under 50   # retrieval + sensor quality on your own corpus

To remove everything Hivelore added: rm -rf .ai CLAUDE.md AGENTS.md GEMINI.md .cursorrules .clinerules .continuerules .windsurfrules .rules CONVENTIONS.md .github/copilot-instructions.md and drop the.github/workflows/haive-*.yml files. Feedback from a repo that isn't ours is the most valuable thingyou can send — please open an issue with what worked and what didn't.

What Hivelore enforces

What "block" means here. Hivelore's gate is deterministic by design: the only thing thathard-blocks a commit is a validated sensor firing on the added lines — same diff, same answer,on every machine and in CI. Anchor, literal-token, and semantic matches (however strong) aresurfaced for review, never blocked: relevance signals vary across environments andco-occurrence is not reintroduction. propose_sensor is the path from a captured lesson to ablocking guardrail. Tighten or loosen with enforcement.antiPatternGate; everything else isenforced as process (was the context loaded, were decisions surfaced, is the recap present).

Cold start — value in session one

An empty corpus is worth nothing, so hivelore init seeds from signals the repo already has — and everyseed passes a quality floor so cold-start never ships generic, guessable advice. A seed earns itsplace only if it carries an enforceable sensor or is concrete and non-generic.

hivelore init                                   # Detect stack + seed packs + seed git history
hivelore ingest --from sonar issues.json --min-severity major
hivelore ingest --from eslint report.json
hivelore ingest --from sarif report.sarif --dry-run   # Preview without writing

Ingested and git-seeded memories land as proposed (warn-only sensors). Review them withhivelore memory list --status proposed; promote vetted sensors to block with hivelore sensors promote.

.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 (Claude Code)
├── AGENTS.md / GEMINI.md / …       # …and 10 more native bridges (see below)
└── .github/
    ├── copilot-instructions.md     # Auto-generated bridge for Copilot
    └── workflows/
        ├── haive-sync.yml          # Anchor verification on merge
        └── haive-enforcement.yml   # Required policy gate

Native bridges — meet every agent where it is

For CLI/IDE agents without MCP, hivelore init generates native config files from the same corpus, sothe team's memories and block sensors travel to whatever agent a developer uses — not just an emptytemplate, the enforcement edge too. hivelore sync keeps them fresh; never hand-edit them (regenerate withhivelore bridges sync).

hivelore bridges list                 # Show target status
hivelore bridges sync --all           # Regenerate every native bridge
hivelore init --bridge-targets cursor,copilot   # Or scope to specific agents

Context policy records

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

MCP tools reference

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 / full: legacy aliases for maintenance (the experimentaldiagnostics were removed in v0.32.0 — months of usage showed a single call across all of them).

MCP prompts reference

Packages

Also in this repo: a VS Code extension (surfaces memories inline + a StrategicCockpit over the CLI's observability) and a GitHub Action (posts relevantteam memories as a PR comment so reviewers and agents never miss a non-obvious constraint).

Adaptive briefing

A briefing only earns its place when it carries unguessable knowledge, so get_briefing returnsbriefing_value: "high" | "low". When nothing team-specific matches the files/task, the auto-generatedproject context is trimmed to a one-line note (config: adaptiveBriefing, default on) — so Hiveloresurfaces deeper context only when it actually knows something the model doesn't.

CLI reference

# Setup
hivelore init [--with-ci] [--no-bridges]         # Initialize .ai/ + bridge files + seed stack/git
hivelore init --bridge-targets <all|csv>         # Scope generated bridges to specific agents
hivelore enforce install                         # Install Git hooks + CI enforcement
hivelore enforce status                          # Enforcement posture report
hivelore bridges list/sync [--all]               # Inspect / regenerate native agent bridges
hivelore index code                              # Build .ai/code-map.json
hivelore index code --status [--json]            # Report code-map / code-search index freshness

# Daily use
hivelore briefing [--task <text>] [--files] [--json]   # Print context + relevant memories
hivelore run -- <agent command>                  # Wrap any CLI agent in Hivelore session
hivelore enforce check [--stage pre-commit]      # Policy gate
hivelore enforce ci                              # CI entrypoint
hivelore enforce finish                          # Final agent-exit gate: commit/push + version/tag protocol
hivelore coverage [--source git|agent|both]      # Find changed files no memory covers
hivelore sync [--since <ref>] [--embed]          # Verify anchors + auto-promote
hivelore sensors list/check/export/promote       # Operate executable memory sensors

# Memory
hivelore memory save --type <type> --body "<text>" [--paths <csv>]  # Save a memory (anchor to files)
hivelore memory list [--scope] [--status]        # List memories
hivelore memory search <text>                    # Full-text / semantic search
hivelore memory get <id>                         # Read one record
hivelore memory approve [<id>|--all]             # Mark as validated
hivelore memory promote <id>                     # personal → team
hivelore memory tried [--sensor-pattern <re>]    # Record a failed approach (one-shot guardrail)
hivelore memory conflicts [<a> <b>] [--yes]      # List conflict candidates / resolve one pair
hivelore memory verify [--update] [--json]       # Check anchor freshness
hivelore memory import --from <file> [--changelog]  # Import docs or a CHANGELOG as memories
hivelore memory seed [stack|--git]               # Re-seed stack packs / git-history scars

# Cold start (seed from existing signals)
hivelore ingest --from sonar|sarif|eslint|npm-audit <file>  # Scanner findings → anchored memories
hivelore ingest --from <fmt> <file> --dry-run    # Preview without writing

# Indexes (symbol map + semantic search)
hivelore index code [--status]                   # Build .ai/code-map.json / report freshness
hivelore index memories                          # Build the semantic index (first run: ~110MB model)
hivelore index query <text>                      # Semantic search over memories

# Release protocol
hivelore release bump <patch|minor|major>        # Lockstep version bump + CHANGELOG scaffold
hivelore release tag                             # Tag vX.Y.Z at HEAD, push branch + tag

# Diagnostics
hivelore doctor                                  # Analyze setup, emit recommendations
hivelore eval --fail-under 80                    # Retrieval + sensor quality gate
hivelore selftest                                # Self-test MCP tools (latency + payloads)

hivelore eval auto-synthesizes retrieval cases from anchored memories and, when present, also loads.ai/eval/spec.json for labeled retrieval/sensor cases. This repo uses that file to keep executablememory sensors in CI, so a broken guardrail is caught before release.

hivelore doctor reports local setup drift that can make agents misdiagnose the repo: missing pnpm,stale workspace dist artifacts, global CLI/MCP version skew, outdated code-search indexes, and lowmemory-anchor coverage.

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/hivelore.git
cd Hivelore
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.