Hivelore

Hivelore is the enforcement layer inside an AI coding-agent harness. It briefs agents with the team's non-obvious knowledge before they act, then turns each hard-won lesson into a deterministic gate — in MCP, Git hooks, and CI — that blocks the change about to repeat it. Same diff, same verdict, on every machine. Memory is the substrate; the gate is the product.

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.

Related MCP server: MCP Memory Server

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.

For the changes prompted by the September 18 client reports, including evidence checks, quieter briefings and completion scoped to a task, see the implementation notes.

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 deliberately covers 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 independent source of truth for what the code should do — and that oracle problem (plus the trap of an agent grading 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 carry the 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 slice of behaviour control, not a runtime functional oracle.

The bridge exists (v0.33.0): command sensors. A lesson can carry a command instead of a regex — your own test or invariant script. When a diff touches the sensor's paths, the gate executes it and a non-zero exit refuses the commit with the lesson as the message. Hivelore does not invent the oracle (the unsolved problem); it routes the oracle your team already owns to the lesson it protects:

hivelore memory tried \
  --what "refund exceeded the captured amount" \
  --why-failed "prod incident #442 — refunds must clamp to capture" \
  --paths src/payments/ \
  --sensor-command "npx vitest run tests/payments/refund-invariants.spec.ts"
# → validated (the oracle must PASS on the current tree), then enforced at commit + CI
#   Saved team-scoped by default: an enforced lesson must travel to every machine and CI.

Rules that keep it honest: opt-in per repo (enforcement.runCommandSensors: true — it executes repo-authored commands), a proposal whose oracle fails on the presumed-correct tree is rejected, an oracle that is still a pending stub cannot arm a block sensor, and an unrunnable command (not found, timeout) warns but never blocks — a broken harness must not masquerade as a failing test. Commands run with a scrubbed environment (test-runner basics only — no cloud credentials or tokens). And you can make the guarantee demonstrable: --red-ref <pre-fix-commit> replays the incident in a scratch worktree and requires the oracle to FAIL there — the sensor then records red_proven: true, shown in the prevention receipt. A crash is not a RED: if the oracle errors before reaching its assertion on the incident state (the guarded code doesn't exist yet, an import or syntax error, "no tests found"), the replay reports red-unrunnable and refuses to claim proof. Full behaviour verification (test generation, LLM evals) remains your test suite's job.

Since v0.43.0, prove-RED is mandatory for a blocking shell/test sensor: an oracle without a reproducible incident state remains warn. CI can also set commandSensorUnrunnable: "block" so a missing required oracle fails as a broken harness, and sensorWeakeningGate: "block" so protection cannot be silently demoted or removed.

The on-ramp (v0.36.0): scaffold the test from the incident. A command sensor needs a test to route — so Hivelore generates the skeleton from the lesson. hivelore sensors scaffold <memory-id> (or the scaffold_test MCP tool, so agents do it in-session) detects your test framework (vitest / jest / pytest / go), writes a pending test carrying the incident's provenance in its header, and prints the exact sensors propose --kind test line to arm it. It never arms a sensor itself (propose_sensor stays the sole validated writer); the stub stays pending so the suite is green until you write the assertion. In a monorepo, the framework and location come from the package that owns the lesson's anchor paths (a lesson under packages/api/ scaffolds into packages/api/tests/…), not the repo root — and a lesson that spans several packages scaffolds one pending test per owning package, all armed by a single sensor whose oracle chains their run commands. A scaffold left pending or never armed is an open loop: doctor and enforce finish nudge it (post-incident-test-unarmed) until the oracle is routed.

Pass the incident and the stub writes itself around the fix (v0.46.0). Add --red-ref <pre-fix-commit> and the scaffold names the symbols the fix (red_ref..HEAD) actually touched and pre-fills the example around them — import { refund } …, expect(refund(/* incident input */)).toBe(/* post-fix expected */) instead of a blank subjectUnderTest(). It stays a pending, commented stub (no live import, suite stays green) — a deterministic head-start, never an LLM guessing your assertion.

hivelore sensors scaffold 2026-07-03-attempt-refund-exceeds-capture --red-ref <pre-fix-commit>
# → tests/incidents/refund-exceeds-capture.test.ts (pending; names the touched symbols from the fix)
#   then: fill the assertion → run it → arm it with the printed propose command.

Lower the cost of expressing the invariant (v0.48.0): --style. The behaviour harness leaves the oracle to you — so the scaffold offers the two deterministic ways to make that cheaper (no LLM guessing your assertion):

• --style property — a fast-check / Hypothesis skeleton: state the invariant once (refund(a, b) ≤ b) and it is checked over many generated inputs.

• --style differential --reference <impl> — state no invariant at all: assert the subject agrees with a reference implementation (a legacy version, a second impl) for all generated inputs.

hivelore sensors scaffold <lesson> --red-ref <pre-fix-commit> --style property
hivelore sensors scaffold <lesson> --style differential --reference ../legacy/refund

Both stay pending, commented stubs (the suite stays green) and arm through the same validated prove-RED path once you fill them in.

Measure the behaviour harness (v0.45.0). hivelore doctor reports, per main code area, how much of the behaviour surface is guarded: Behaviour harness: X/N area(s) guarded by a behavioural oracle (K armed, P red-proven) — so the branch's progress is visible, not guesswork. The human stats receipt prints the same line as a footer. Since v0.47.0 the finding closes the loop to action: for each uncovered area it prints the exact hivelore sensors scaffold <lesson> --red-ref <pre-fix-commit> command in its Suggested commands (or a memory tried … then scaffold line when no lesson exists yet).

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 guardrail that scans the diff. Three shapes, one validation doctrine (silent on correct code, fires on the mistake):

• regex — matched on added lines; the simple, dependency-free default.

• ast — an ast-grep structural pattern (stripe.paymentIntents.create($$$) with absent: idempotencyKey): comments and string literals can never false-positive, and "X without Y" is expressed on the call itself. Needs the optional @ast-grep/napi engine — without it the sensor is unrunnable (warn, never block).

• shell/test — a command routing your own test as the oracle (the behaviour bridge, below).

• checklist — a required verification, not a pattern: when a change touches the scoped paths, the gate prints the step to perform ("run the GPU browser check of the PDF viewer — headless CI cannot see this failure"). At block severity the commit message must carry Hivelore-Checked: <memory-id> — the author's explicit statement that it was done. This is the guard for knowledge no code pattern can express: a caveat that only shows up on a device, a rollout step, a manual migration check.

Sensors turn a documented lesson into a repeatable feedback signal, independent of embeddings or model judgment. Autogenerated sensors start as warn; humans promote vetted ones to block. The doctrine is also enforced against inversion: a block pattern that matches the lesson's own recommended fix (its Instead, use: snippet) is refused (fires-on-correct) — it would block the correct code and never the mistake.

hivelore sensors list
hivelore sensors check                          # scans git diff --cached
hivelore sensors propose <lesson> --kind checklist --paths 'config/security/**' \
  --message 'Run the GPU browser check of the PDF viewer'   # a required verification
hivelore sensors propose <lesson> --from-fix <pre-fix-ref>   # MINE the pattern from the fix diff
hivelore sensors promote <id> --yes             # promote a vetted sensor to block
hivelore sensors export --format grep

Cheaper arming (--from-fix). Authoring a discriminating regex is the main cost between a documented lesson and an enforced one — so let the fix write it. sensors propose --from-fix <pre-fix-ref> mines the pattern from the fix diff: the line the fix removed is the mistake (pattern), the line it added is the correct marker (absent). You confirm a candidate instead of authoring a regex — and it still passes the full validation (silent-on-current, fires-on-bad, not-inverted) before it can block.

Install

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

Verify the complete integration

Run hivelore agent check --exercise --json to exercise MCP briefing, targeted hook context, and a validated sensor against good and bad code in an isolated temporary repository. It also reports first-edit latency and ten-sample median/p95 timings for reads, repeated edits and shell calls. This is a synthetic installation proof, not a productivity benchmark. New projects default to local task completion and draft capture; existing policies remain intact. See the audit fixes and upgrade guide.

After upgrading, run hivelore agent setup --no-global to repair managed legacy Git hooks, then restart your AI client. A successful fresh handshake does not upgrade a running conversation. hivelore agent check --json lists known live MCP versions and remaining migration work. Legacy CI workflows receive a .candidate replacement for review; custom hook commands are preserved.

Complete policies and traceable outcomes

Short applicable policies are injected before edits. When a policy cannot fit, the hook emits an explicit instruction not delivered pointer instead of silently dropping its exceptions. Partial briefings do not count as complete consultation. Use mem_get with the hook’s session_id, or hivelore memory get <id> --session-id <session>, to read and credit the whole policy.

mem_feedback is available in the default MCP profile. Report applied/rejected, or corrected/verified with a commit, test-report or incident reference. An optional catch_id links feedback to an interception listed by hivelore stats outcomes. Linked verification requires a preceding correction. Reports distinguish declared outcomes from a subsequent observed silent sensor check; they do not authenticate references or infer bugs avoided/time saved.

Benchmark reports require at least 10 distinct tasks × 3 repetitions, comparable model, checkout, budget and prompt metadata, independent evaluation attestations, and matching protocol.json/run.json manifests to qualify as decision-ready. Repeating one task or removing an arm cannot satisfy a prepared protocol. This grade describes evidence completeness, not proven superiority or authenticated execution.

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

This is the exact flow shown in the demo above.

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

hivelore init -y                     # .ai/ layer + git hooks + bridges for the agents you actually use (detected)

# 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"
#    🛡️  A documented lesson refused this commit — about the change you just made:
#        • 2026-07-02-attempt-importing-momentjs (src/dates.ts)  use date-fns
#          import moment from 'moment';

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":"hivelore","command":"hivelore","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 check          # initialize the server and discover its tools
hivelore agent setup          # re-run setup later
hivelore agent setup --yes    # approve user-level MCP config without prompting

Setup migrates obsolete haive MCP commands, including Codex user configuration, and preserves other servers and JSONC comments. It supports Claude Code, Cursor, VS Code, Windsurf, Codex, and detected Gemini CLI/Roo Code configurations. Restart the client after setup, then call get_briefing in a new session: a successful server check does not prove that an existing session has access. See MCP connection troubleshooting.

5. Gate commits and pull requests

hivelore enforce install       # Installs Git hooks + CI enforcement template
hivelore enforce status        # Current enforcement posture
hivelore enforce check --stage pre-commit  # Scan the staged change
hivelore enforce ci            # CI entrypoint (exits 1 on violations)

One knob decides what refuses: enforcement.posture.

mode, processGate and humanCommits are the individual switches a posture sets; pin one explicitly to override the posture for that switch alone. hivelore doctor always prints the effective posture and any overrides, so what the gate will do is never a guess.

One rule is not a posture knob and is not negotiable: process gates never refuse a local commit, at any posture. Blocking them on every pre-commit is what trains the --no-verify reflex on cold repos. A passing commit-time gate prints one line; --verbose shows every check. If a git hook was left broken by an old install, hivelore doctor --fix regenerates it.

When something does refuse, it names the line.

🛡️  A documented lesson refused this commit — about the change you just made:
    • 2026-07-02-attempt-importing-momentjs (src/dates.ts)  use date-fns, not moment
      import moment from 'moment';

One lesson, one line, with the file and the offending source. No composite score of any kind: the gate reports what refused the change and what to do about it, and stays silent otherwise.

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.

Exhaustive command manual: packages/cli/README.md documents every command with its flags and examples. It is the reference; this page is the concepts. Each claim lives in exactly one of the two.

One vocabulary across CLI and MCP. The memory verbs mirror the MCP tool names, so an agent learns them 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).

Audit your agent rules in 10 seconds — no install, no init

Most repositories now tell their agents what to do in CLAUDE.md, AGENTS.md or .cursor/rules. Compliance with prose is probabilistic, and studies of public instruction files find only a small fraction of their rules backed by any real control. rules audit reads your instruction files and tells you which rules are enforced, which are mechanically checkable but unenforced, and which are legitimately judgment — read-only, on any repository:

npx @hivelore/cli rules audit
#   25 rules — 12 enforced by a gate · 6 checkable but unenforced · 7 judgment
#   Enforceable coverage: 67% of the rules a machine could check are actually checked.
#   CLAUDE.md:55  NEVER run `npm publish` from an agent.   signals: code token, command

Each checkable rule is one sensors propose away from being refused by the gate instead of hoped for. --fail-under <pct> turns it into a CI check.

Is it preventing mistakes, or performing ceremony?

hivelore report harness answers with counts, case by case: every sensor with its runs, catches, live hivelore:allow waivers and last hit (and the ones never evaluated); the most-surfaced memories and whether anyone reported applying them; validated memories never surfaced in 60 days (archive candidates); anchors that no longer exist; decisions past their expires_when date. Nothing is inferred — no "time saved", no unverifiable totals.

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 it writes 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/hivelore-*.yml files. Feedback from a repo that isn't ours is the most valuable thing you can send — please open an issue with what worked and what didn't.

What Hivelore enforces

What "block" means here. The gate spends its refusals only where it has deterministic, code-bound evidence: a validated sensor firing on the added lines, an anchored anti-pattern, a stale anchor on a file you touched — same diff, same answer, on every machine and in CI. Anchor, literal-token, and semantic matches (however strong) are surfaced for review, never blocked: relevance signals vary across environments and co-occurrence is not reintroduction. propose_sensor is the path from a captured lesson to a blocking guardrail.

The process gates report; they do not refuse. Since v0.55.0, "you did not load a briefing" and "you did not write a session recap" are requests, not verdicts on your diff. The reason is empirical: a field report had two pushes refused carrying tested code with a green quality gate and zero violations — every penalty was a process one, none was about the code. The next thing a developer learns is --no-verify, which costs them the whole gate, sensors included, and a gate that gets bypassed protects nothing. Set enforcement.posture: "strict" if you want the workflow enforced too.

Cold start — value in session one

hivelore init can seed from signals the repo already has, and every seed passes a quality floor so cold-start never ships generic, guessable advice.

Stack packs are opt-in since v0.55.0 (--stack auto). Seeding them by default filled a new corpus with advice nobody wrote for the repo, and the first briefing of a real session read thin · must_read=0 useful=0 background=3 — all three being stack-pack platitudes occupying the briefing without teaching anything. An empty corpus is more honest: it says plainly that it needs filling. Git-history seeding stays on in autopilot, because a revert in your history is your scar.

hivelore init                                   # Initialize + seed from git history
hivelore init --stack auto                      # ...and add starter packs for the detected stack
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 with hivelore 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
│   ├── code-map.json               # Symbol index — deterministic, safe to commit
│   ├── .runtime/                   # Local session state — gitignored
│   └── .cache/                     # Indexes, churn, telemetry — gitignored
├── 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/
        ├── hivelore-sync.yml       # Anchor verification on merge
        └── hivelore-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, so the team's memories and block sensors travel to whatever agent a developer uses — not just an empty template, the enforcement edge too. hivelore sync keeps them fresh; never hand-edit them (regenerate with hivelore 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

Default profile — the tools agents actually use:

Maintenance profile (HIVELORE_TOOL_PROFILE=maintenance) adds, among others:

MCP profiles keep the product focused:

• HIVELORE_TOOL_PROFILE=enforcement (default): the eight tools above. Fewer tools, fewer wrong choices.

• HIVELORE_TOOL_PROFILE=maintenance: corpus review, lifecycle, distillation, search, code-map/code-search, and project-context maintenance.

• HAIVE_TOOL_PROFILE=experimental / full: legacy aliases for maintenance (the experimental diagnostics 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 Strategic Cockpit over the CLI's observability) and a GitHub Action (posts relevant team memories as a PR comment so reviewers and agents never miss a non-obvious constraint).

The PR loop. Review feedback is team truth in the making: reply /hivelore remember <rule> on any review thread and the Action acknowledges it with the exact persist command; or run hivelore ingest --from github-pr <number> to turn a PR's human review instructions ("never…", "always…", "prefer X instead") into proposed, file-anchored memories — each one a candidate for sensors propose, which is the step no inferential review bot can take. With persist-review-learnings enabled (default), the Action creates a dedicated branch and PR containing the proposed memory; when repository write permission is unavailable, it falls back to the local ingest command. Top-level PR comments and review-thread replies follow the same path.

Structural sensors. sensors propose --kind ast accepts either a concise --pattern or a full ast-grep --rule <json> (inside/has/not/all/any). JavaScript/TypeScript are built in; Python, Go, Rust, and Java are optional language packages shipped with the CLI. Rules still pass Hivelore's silent-on-current/fires-on-bad validation before they can block. Nested relational rules are not recursive by default: add "stopBy":"end" when has or inside must search every descendant, for example {"has":{"kind":"interpolation","stopBy":"end"}}.

Adaptive briefing

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

Anchors are weighted by how much they actually discriminate

An anchor match is the strongest ranking signal there is — when the anchor is specific. On a file every commit touches it is almost none. Measured on this repo: package.json is touched by 106 of 149 commits, so every lesson anchored to it declared itself must_read on every release commit. The median commit had 34 memories claiming the top rank for 8 slots, and which 8 surfaced was arbitrary.

Since v0.57.0 a match is weighted by how rare the matched path is — plain IDF, applied to anchors. An anchor touched by more than 35% of recent commits needs corroboration (a strong semantic hit or a symbol match) before it outranks everything, and specificity breaks ties within a tier. Measured over 25 real commits, briefing slots spent on a low-information anchor fell from 17% to 4%.

Churn is one cached git log, invalidated by HEAD. Too small a sample — a shallow clone, a young repo — is reported as unknown and ranks exactly as before, never as "everything is common".

hivelore doctor reports memory-broad-anchors, naming the memories that claim nearly every change and the share of commits each anchor covers. The fix is always additive: give the lesson the precise path it is really about.

CLI reference

# Setup
hivelore init [--with-ci] [--no-bridges]         # Initialize .ai/ + bridge files + seed from git history
hivelore init --stack auto                       # Opt in to generic starter packs for the detected stack
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, CI, npm + GitHub Release
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
hivelore sensors propose <id> --pattern <re>     # Turn a lesson into a VALIDATED guardrail
hivelore report list|submit|dismiss              # Friction agents hit with Hivelore itself

# 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
hivelore release ship                            # After the bump commit: pull --rebase → tag+push → poll CI

# Diagnostics
hivelore doctor                                  # Analyze setup, emit recommendations
hivelore eval --fail-under 80                    # Retrieval + sensor quality gate
hivelore eval --semantic-ranking                 # Real embeddings lane (requires index)
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 executable memory sensors in CI, so a broken guardrail is caught before release. Committed regression baselines use only versioned team/module memories and deterministic anchor/lexical ranking; local usage counters, personal memories, and optional embedding caches cannot make a baseline pass locally but fail in a clean CI clone. Semantic search remains exercised by the embeddings/search test suites and by a separate --semantic-ranking CI lane backed by .ai/eval/semantic-baseline.json. That lane fails closed when the package or index is unavailable.

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 low memory-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.