{"id":51723160,"url":"https://github.com/Doucs91/hivelore","last_synced_at":"2026-08-05T22:00:37.219Z","repository":{"id":357050514,"uuid":"1221117334","full_name":"Doucs91/hivelore","owner":"Doucs91","description":"Policy enforcement layer for AI coding agents — briefing gates, team memory, Git/CI checks","archived":false,"fork":false,"pushed_at":"2026-07-28T18:11:34.000Z","size":5356,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-28T20:06:10.760Z","etag":null,"topics":["ai","ai-agents","claude","cli","copilot","cursor","developer-tools","mcp","model-context-protocol","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Doucs91.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-25T19:21:46.000Z","updated_at":"2026-07-28T18:12:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Doucs91/hivelore","commit_stats":null,"previous_names":["doucs91/haive","doucs91/hivelore"],"tags_count":145,"template":false,"template_full_name":null,"purl":"pkg:github/Doucs91/hivelore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doucs91%2Fhivelore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doucs91%2Fhivelore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doucs91%2Fhivelore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doucs91%2Fhivelore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Doucs91","download_url":"https://codeload.github.com/Doucs91/hivelore/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doucs91%2Fhivelore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36322586,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-08-05T02:00:06.619Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","claude","cli","copilot","cursor","developer-tools","mcp","model-context-protocol","typescript"],"created_at":"2026-07-17T15:00:32.875Z","updated_at":"2026-08-05T22:00:37.205Z","avatar_url":"https://github.com/Doucs91.png","language":"TypeScript","funding_links":[],"categories":["Harnesses \u0026 orchestration"],"sub_categories":["Agent infrastructure"],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/Doucs91/hivelore\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/Doucs91/hivelore/main/packages/vscode/media/logo.svg\" alt=\"Hivelore logo\" width=\"96\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eHivelore\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eThe deterministic policy gate for agent-written code — it refuses the commit that repeats a mistake your team already paid for.\u003c/strong\u003e\u003cbr/\u003e\n  \u003cem\u003eA repo-native context policy for coding-agent harnesses; the rules live as team memory. Formerly published as \u003ccode\u003ehAIve\u003c/code\u003e (\u003ccode\u003e@hiveai/*\u003c/code\u003e).\u003c/em\u003e\n\u003c/p\u003e\n\nHivelore 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.**\n\nA 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.\n\n\u003e 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.\n\n[![npm](https://img.shields.io/npm/v/@hivelore/cli?color=blue)](https://www.npmjs.com/package/@hivelore/cli)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)\n[![CI](https://github.com/Doucs91/hivelore/actions/workflows/ci.yml/badge.svg)](https://github.com/Doucs91/hivelore/actions/workflows/ci.yml)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/demo/hivelore-demo.gif\" alt=\"A captured lesson attaches a validated guard; the commit that reintroduces the mistake is refused — same diff, same verdict on every machine\" width=\"720\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003csub\u003e\u003cb\u003eCapture a mistake → attach a validated guard → the commit that repeats it is refused.\u003c/b\u003e Same diff, same verdict, on every machine and in CI. \u003ca href=\"#the-60-second-proof\"\u003eReproduce it in 60 seconds ↓\u003c/a\u003e\u003c/sub\u003e\u003c/p\u003e\n\n---\n\n## The problem\n\nAI 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.\n\nMost teams work around this with instructions and hope:\n\n- *\"Please read our architecture decisions first.\"*\n- *\"Don't repeat the migration mistake from last sprint.\"*\n- *\"Remember to capture what you learned.\"*\n- *\"Don't merge code that invalidates a team decision.\"*\n\nThose rules are easy to skip. Hivelore turns them into **repo-native context policy**.\n\n---\n\n## How it works\n\n```\nAI agent ──▶ Hivelore briefing ──▶ code change ──▶ Hivelore policy gate ──▶ merge\n                  ▲                                       │\n                  └── context breadcrumbs · decisions · gotchas · anchors\n```\n\n1. `hivelore init` creates a `.ai/` context policy layer in your repo.\n2. Agents start every session with `get_briefing` — one MCP call that returns small default context plus deeper breadcrumbs ranked by task relevance.\n3. 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.\n4. `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.\n\n\u003e **Memory is the substrate. Context enforcement is the product promise.**\n\u003e AI changes should not enter the codebase without consulting the team's current knowledge.\n\n## Where Hivelore fits in the harness\n\nHarness 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.\n\n| Harness concern | Hivelore role |\n|---|---|\n| **Feedforward guidance** | `get_briefing`, module context, skills, decisions, gotchas, failed attempts |\n| **Feedback and gates** | MCP ordering policy, `pre_commit_check`, Git hooks, CI enforcement, stale-anchor detection |\n| **Knowledge lifecycle** | Git-native Markdown records, path/symbol anchors, confidence, retirement, linting |\n| **Boundaries** | Hivelore complements unit/e2e tests, type checks, runtime traces, security scanners, and LLM evals; it does not try to replace them |\n\nThe 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.\n\n### Scope \u0026 boundaries — the three harnesses\n\nHarness engineering regulates three different things about agent-written code. Hivelore deliberately\ncovers two of them and **treats the third as out of scope, for now.**\n\n| Harness dimension | Question it answers | Hivelore today |\n|---|---|---|\n| **Maintainability** | Is the code clean? (patterns, footguns, conventions) | ✅ **Covered** — executable sensors + anti-pattern gate |\n| **Architecture fitness** | Does it respect the team's structural decisions? | 🟡 **Partly** — anchored `decision`/`architecture` memories + decision-coverage gate |\n| **Behaviour** | Does the code do the *functionally correct* thing? | 🟡 **Bridged** — command sensors route your own tests to lessons (see below) |\n\n**Why no behaviour harness yet.** Verifying functional correctness needs an *oracle* — an independent\nsource of truth for what the code *should* do — and that oracle problem (plus the trap of an agent\ngrading its own work) is the least-mature part of the field. That territory belongs to your tests,\nproperty-based checks, and LLM-evals; Hivelore does not try to replace them. What Hivelore *does* do is carry\nthe **unguessable intent** a behaviour test would otherwise have to encode (`status must be OK/KO`,\n`public ids = id + 100000`) as feedforward context and deterministic sensors — a partial, static slice\nof behaviour control, not a runtime functional oracle.\n\n**The bridge exists (v0.33.0): command sensors.** A lesson can carry a *command* instead of a regex —\nyour own test or invariant script. When a diff touches the sensor's paths, the gate executes it and a\nnon-zero exit refuses the commit with the lesson as the message. Hivelore does not invent the oracle\n(the unsolved problem); it **routes the oracle your team already owns** to the lesson it protects:\n\n```bash\nhivelore memory tried \\\n  --what \"refund exceeded the captured amount\" \\\n  --why-failed \"prod incident #442 — refunds must clamp to capture\" \\\n  --paths src/payments/ \\\n  --sensor-command \"npx vitest run tests/payments/refund-invariants.spec.ts\"\n# → validated (the oracle must PASS on the current tree), then enforced at commit + CI\n#   Saved team-scoped by default: an enforced lesson must travel to every machine and CI.\n```\n\nRules that keep it honest: opt-in per repo (`enforcement.runCommandSensors: true` — it executes\nrepo-authored commands), a proposal whose oracle *fails on the presumed-correct tree* is rejected,\nan oracle that is still a **pending stub** cannot arm a block sensor, and an **unrunnable** command\n(not found, timeout) warns but never blocks — a broken harness must not masquerade as a failing test.\nCommands run with a **scrubbed environment** (test-runner basics only — no cloud credentials or\ntokens). And you can make the guarantee demonstrable: `--red-ref \u003cpre-fix-commit\u003e` replays the\nincident in a scratch worktree and requires the oracle to FAIL there — the sensor then records\n`red_proven: true`, shown in the prevention receipt. A crash is **not** a RED: if the oracle errors\nbefore reaching its assertion on the incident state (the guarded code doesn't exist yet, an import\nor syntax error, \"no tests found\"), the replay reports `red-unrunnable` and refuses to claim proof.\nFull behaviour verification (test generation, LLM evals) remains your test suite's job.\n\nSince v0.43.0, prove-RED is mandatory for a blocking shell/test sensor: an oracle without a\nreproducible incident state remains `warn`. CI can also set `commandSensorUnrunnable: \"block\"` so a\nmissing required oracle fails as a broken harness, and `sensorWeakeningGate: \"block\"` so protection\ncannot be silently demoted or removed.\n\n**The on-ramp (v0.36.0): scaffold the test from the incident.** A command sensor needs a test to\nroute — so Hivelore generates the skeleton from the lesson. `hivelore sensors scaffold \u003cmemory-id\u003e`\n(or the `scaffold_test` MCP tool, so agents do it in-session) detects your test framework\n(vitest / jest / pytest / go), writes a **pending** test carrying the incident's provenance in its\nheader, and prints the exact `sensors propose --kind test` line to arm it. It never arms a sensor\nitself (`propose_sensor` stays the sole validated writer); the stub stays pending so the suite is\ngreen until you write the assertion. In a **monorepo**, the framework and location come from the\npackage that owns the lesson's anchor paths (a lesson under `packages/api/` scaffolds into\n`packages/api/tests/…`), not the repo root — and a lesson that **spans several packages** scaffolds\none pending test per owning package, all armed by a single sensor whose oracle chains their run\ncommands. A scaffold left pending or never armed is an open loop: `doctor` and `enforce finish`\nnudge it (`post-incident-test-unarmed`) until the oracle is routed.\n\n**Pass the incident and the stub writes itself around the fix (v0.46.0).** Add `--red-ref \u003cpre-fix-commit\u003e`\nand the scaffold names the symbols the fix (`red_ref..HEAD`) actually touched and pre-fills the example\naround them — `import { refund } …`, `expect(refund(/* incident input */)).toBe(/* post-fix expected */)`\ninstead of a blank `subjectUnderTest()`. It stays a **pending, commented** stub (no live import, suite\nstays green) — a deterministic head-start, never an LLM guessing your assertion.\n\n```bash\nhivelore sensors scaffold 2026-07-03-attempt-refund-exceeds-capture --red-ref \u003cpre-fix-commit\u003e\n# → tests/incidents/refund-exceeds-capture.test.ts (pending; names the touched symbols from the fix)\n#   then: fill the assertion → run it → arm it with the printed propose command.\n```\n\n**Lower the cost of expressing the invariant (v0.48.0): `--style`.** The behaviour harness leaves the\n*oracle* to you — so the scaffold offers the two deterministic ways to make that cheaper (no LLM\nguessing your assertion):\n\n- `--style property` — a [fast-check](https://github.com/dubzzz/fast-check) / Hypothesis skeleton:\n  state the invariant **once** (`refund(a, b) ≤ b`) and it is checked over many generated inputs.\n- `--style differential --reference \u003cimpl\u003e` — state **no** invariant at all: assert the subject\n  *agrees* with a reference implementation (a legacy version, a second impl) for all generated inputs.\n\n```bash\nhivelore sensors scaffold \u003clesson\u003e --red-ref \u003cpre-fix-commit\u003e --style property\nhivelore sensors scaffold \u003clesson\u003e --style differential --reference ../legacy/refund\n```\n\nBoth stay pending, commented stubs (the suite stays green) and arm through the same validated\nprove-RED path once you fill them in.\n\n**Measure the behaviour harness (v0.45.0).** `hivelore doctor` reports, per main code area, how much of\nthe behaviour surface is guarded: `Behaviour harness: X/N area(s) guarded by a behavioural oracle\n(K armed, P red-proven)` — so the branch's progress is visible, not guesswork. The human `stats receipt`\nprints the same line as a footer. Since **v0.47.0** the finding closes the loop to action: for each\nuncovered area it prints the exact `hivelore sensors scaffold \u003clesson\u003e --red-ref \u003cpre-fix-commit\u003e`\ncommand in its Suggested commands (or a `memory tried … then scaffold` line when no lesson exists yet).\n\n\u003e See [`STABILITY.md`](./STABILITY.md) for the frozen 1.0 surface and [`CONTRIBUTING.md`](./CONTRIBUTING.md) to extend Hivelore.\n\n### Executable memory sensors\n\nSome `gotcha` and `attempt` memories can now carry a `sensor` block: a deterministic guardrail that\nscans the diff. Three shapes, one validation doctrine (silent on correct code, fires on the mistake):\n\n- **regex** — matched on added lines; the simple, dependency-free default.\n- **ast** — an [ast-grep](https://ast-grep.github.io) *structural* pattern\n  (`stripe.paymentIntents.create($$$)` with `absent: idempotencyKey`): comments and string literals\n  can never false-positive, and \"X without Y\" is expressed on the call itself. Needs the optional\n  `@ast-grep/napi` engine — without it the sensor is unrunnable (warn, never block).\n- **shell/test** — a command routing your own test as the oracle (the behaviour bridge, below).\n\nSensors turn a documented lesson into a repeatable feedback signal, independent of embeddings or\nmodel judgment. Autogenerated sensors start as `warn`; humans promote vetted ones to `block`. The\ndoctrine is also enforced against *inversion*: a `block` pattern that matches the lesson's own\nrecommended fix (its `Instead, use:` snippet) is refused (`fires-on-correct`) — it would block the\ncorrect code and never the mistake.\n\n```bash\nhivelore sensors list\nhivelore sensors check                          # scans git diff --cached\nhivelore sensors propose \u003clesson\u003e --from-fix \u003cpre-fix-ref\u003e   # MINE the pattern from the fix diff\nhivelore sensors promote \u003cid\u003e --yes             # promote a vetted sensor to block\nhivelore sensors export --format grep\n```\n\n**Cheaper arming (`--from-fix`).** Authoring a discriminating regex is the main cost between a\ndocumented lesson and an enforced one — so let the fix write it. `sensors propose --from-fix\n\u003cpre-fix-ref\u003e` mines the pattern from the fix diff: the line the fix **removed** is the mistake\n(`pattern`), the line it **added** is the correct marker (`absent`). You confirm a candidate instead of\nauthoring a regex — and it still passes the full validation (silent-on-current, fires-on-bad,\nnot-inverted) before it can block.\n\n---\n\n## Install\n\n```bash\nnpm install -g @hivelore/cli\n# Optional: local semantic search (downloads ~110MB model once)\nnpm install -g @hivelore/embeddings\n```\n\n---\n\n\u003ca id=\"the-60-second-proof\"\u003e\u003c/a\u003e\n## The 60-second proof — watch a lesson stop a commit\n\n\u003e This is the exact flow shown in the demo above.\n\nMemory tools remember; Hivelore's difference is that a remembered lesson can **refuse the commit\nthat repeats it**. Try it on any git repo:\n\n```bash\nhivelore init -y                     # .ai/ layer + git hooks + bridges for the agents you actually use (detected)\n\n# 1. Capture a failed approach (agents do this via the mem_tried MCP tool)\nhivelore memory tried \\\n  --what \"importing moment.js\" \\\n  --why-failed \"bundle bloat — team standard is date-fns\" \\\n  --instead \"date-fns\" --paths src/\n#    → prints the new memory id, e.g. 2026-07-02-attempt-importing-momentjs\n\n# 2. Give the lesson teeth: a validated, deterministic guardrail\nhivelore sensors propose 2026-07-02-attempt-importing-momentjs \\\n  --pattern \"from ['\\\"]moment['\\\"]\" --severity block\n#    Hivelore validates it first: silent on your current code, fires on the mistake.\n\n# 3. Reintroduce the mistake — the commit is refused\necho \"import moment from 'moment';\" \u003e\u003e src/dates.ts\ngit add . \u0026\u0026 git commit -m \"add date helper\"\n#    ✗ Block sensor fired — importing moment.js: use date-fns  (exit 2)\n```\n\nSame diff, same answer, on every machine and in CI — the gate is deterministic by design.\nEverything lives as reviewable Markdown in `.ai/`, versioned with your code. `rm -rf .ai` undoes it all.\n\n---\n\n## Quick start\n\n### 1. Initialize your project\n\n```bash\ncd my-project\nhivelore init          # Creates .ai/, bridge files, MCP config, hooks, CI template\n```\n\n`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.\n\n### 2. Connect your AI client\n\n**Claude Code** (`~/.claude.json`):\n```json\n{\n  \"mcpServers\": {\n    \"hivelore\": {\n      \"command\": \"hivelore\",\n      \"args\": [\"mcp\", \"--stdio\", \"--root\", \"/absolute/path/to/my-project\"]\n    }\n  }\n}\n```\n\n**Cursor** (`~/.cursor/mcp.json`):\n```json\n{\n  \"mcpServers\": {\n    \"hivelore\": {\n      \"command\": \"hivelore\",\n      \"args\": [\"mcp\", \"--stdio\", \"--root\", \"/absolute/path/to/my-project\"]\n    }\n  }\n}\n```\n\n**VS Code**:\n```bash\ncode --add-mcp '{\"name\":\"hivelore\",\"command\":\"hivelore\",\"args\":[\"mcp\",\"--stdio\",\"--root\",\"/path/to/project\"]}'\n```\n\n### 3. Bootstrap your project context\n\nIn your AI client, invoke the `bootstrap_project` MCP prompt. The agent analyzes your codebase and writes `.ai/project-context.md` automatically.\n\n### 4. Start work through Hivelore\n\nEvery session starts with one call:\n\n```\nget_briefing(task: \"add a Stripe payment integration\", files: [\"src/payments/PaymentService.ts\"])\n```\n\nThe agent gets project context + relevant module contexts + ranked context breadcrumbs in one shot — no more grepping to rediscover what the team already knows.\n\nFor CLI agents without native MCP, wrap them:\n\n```bash\nhivelore run -- claude --dangerously-skip-permissions -p \"$(cat task.md)\"\n```\n\nCheck the selected mode any time:\n\n```bash\nhivelore agent status\nhivelore agent setup          # re-run setup later\nhivelore agent setup --yes    # approve user-level MCP config without prompting\n```\n\n### 5. Gate commits and pull requests\n\n```bash\nhivelore enforce install       # Installs Git hooks + CI enforcement template\nhivelore enforce status        # Current enforcement posture\nhivelore enforce check         # Pre-commit policy gate\nhivelore enforce ci            # CI entrypoint (exits 1 on violations)\n```\n\n**Where the gate blocks.** At a local commit, only **deterministic content** findings block — an\nanchored anti-pattern or a sensor firing on your diff. The process/state gates (briefing loaded,\nbootstrap, session recap) are advisory there and **enforce at the sharing points** (`pre-push`, CI),\nwhere the code leaves your machine. A passing commit-time gate prints one line; `--verbose` shows every\ncheck. This keeps quick local iteration friction-free while the team's knowledge is still enforced\nbefore anything is shared. If a git hook was left broken by an old install, `hivelore doctor --fix`\nregenerates it.\n\n---\n\n## CLI at a glance — the golden path\n\n`hivelore --help` shows only the commands you use day to day. Everything else (review, import,\ndiagnostics, benchmarks) is one `hivelore --advanced --help` away — the focused surface is deliberate,\nnot a missing feature.\n\n| Stage | Command | What it does |\n|---|---|---|\n| **Set up** | `hivelore init` | Create `.ai/`, bridge files, MCP config, hooks, CI |\n| | `hivelore doctor` | Check the install is healthy |\n| | `hivelore agent setup` | Wire your AI client (MCP, hooks) |\n| **Before editing** | `hivelore briefing` | Feedforward context — the CLI mirror of `get_briefing` |\n| **Capture knowledge** | `hivelore memory save` | Record a decision / convention / gotcha |\n| | `hivelore memory tried` | Record a failed approach so it isn't repeated |\n| | *(passive)* | Session failures observed by the hooks are **auto-distilled into `proposed` drafts** at session end — review with `memory list --status proposed`; they never self-validate and never carry sensors |\n| **Retrieve** | `hivelore memory search` · `get` | Find, then read a record |\n| **Feedback** | `hivelore sensors check` | Scan the diff against documented lessons |\n| **Gate** | `hivelore enforce finish` | Exit gate before you call the task done |\n| **Sync** | `hivelore sync` | Re-check stale anchors, refresh bridge files |\n| **Close** | `hivelore session end` | Save a recap for the next session |\n\n**One vocabulary across CLI and MCP.** The memory verbs mirror the MCP tool names, so an agent learns\nthem once: `hivelore memory save/search/get/delete` ↔ `mem_save`/`mem_search`/`mem_get`/`mem_delete`\n(the older `add`/`query`/`show`/`rm` still work as aliases).\n\n---\n\n## Try it on your repo (5 minutes, reversible)\n\nWant to evaluate Hivelore on a real codebase that isn't a toy? It is non-destructive — everything it\nwrites lives under `.ai/` plus a few bridge files, all removable.\n\n```bash\ncd your-project\nnpm install -g @hivelore/cli\nhivelore init -y            # seeds stack packs + git-history scars; writes .ai/ and bridges\nhivelore briefing --task \"the change you're about to make\" --files path/to/file\nhivelore doctor             # health + coverage report\nhivelore sensors check      # scan your staged diff against documented lessons\nhivelore eval --fail-under 50   # retrieval + sensor quality on your own corpus\n```\n\nTo remove everything Hivelore added: `rm -rf .ai CLAUDE.md AGENTS.md GEMINI.md .cursorrules .clinerules\n.continuerules .windsurfrules .rules CONVENTIONS.md .github/copilot-instructions.md` and drop the\n`.github/workflows/hivelore-*.yml` files. Feedback from a repo that isn't ours is the most valuable thing\nyou can send — please [open an issue](https://github.com/Doucs91/hivelore/issues) with what worked and what didn't.\n\n## What Hivelore enforces\n\n| Gate | What it checks |\n|---|---|\n| **First-agent bootstrap** | On a **cold corpus**, the first agent is forced to fill the knowledge layer before its commit/finish can pass: a filled project-context, a module context per component, an anchored memory per main code area, and a **sensor per main code area**. The trigger is corpus state — once the baseline exists the gate is silent for every later agent. Tunable via `enforcement.bootstrapGate` (`off` · `warn` · `block` (default)); only bites when production code is in play |\n| **Briefing loaded** | Agent loaded fresh context breadcrumbs before editing |\n| **Decision coverage** | Changed files are covered by relevant anchored decisions in the last briefing |\n| **Anti-pattern matching** | Anti-patterns relevant to the diff are surfaced at the gate; a **validated block sensor** that fires on the added lines **blocks** the commit. Hardness is tunable via `enforcement.antiPatternGate` (`off` · `review` · `anchored` (default) · `strict`) |\n| **Gate-surface integrity** | A diff that **weakens a sensor** (block→warn demotion, changed/removed oracle, broadened suppression, deleted block-sensor memory) is surfaced for review (`sensor-weakened`) — the gate lives in `.ai/`, so weakening it must never sail through unmentioned |\n| **Stale anchors** | Memories anchored to deleted/moved paths are flagged |\n| **Session recap** | Agent captured what changed and what remains before closing |\n| **CI enforcement** | Required check blocks merge on any gate failure |\n\n\u003e **What \"block\" means here.** Hivelore's gate is deterministic by design: the only thing that\n\u003e hard-blocks a commit is a **validated sensor** firing on the added lines — same diff, same answer,\n\u003e on every machine and in CI. Anchor, literal-token, and semantic matches (however strong) are\n\u003e **surfaced for review**, never blocked: relevance signals vary across environments and\n\u003e co-occurrence is not reintroduction. `propose_sensor` is the path from a captured lesson to a\n\u003e blocking guardrail. Tighten or loosen with `enforcement.antiPatternGate`; everything else is\n\u003e enforced as *process* (was the context loaded, were decisions surfaced, is the recap present).\n\n---\n\n## Cold start — value in session one\n\nAn empty corpus is worth nothing, so `hivelore init` seeds from signals the repo already has — and every\nseed passes a **quality floor** so cold-start never ships generic, guessable advice. A seed earns its\nplace only if it carries an enforceable sensor or is concrete and non-generic.\n\n| Source | What it seeds | Quality gate |\n|---|---|---|\n| **Stack packs** | Detected-framework traps (Next/Nest/Prisma/Flask/Rails/Tailwind/Docker… 20+ packs), with **block sensors** where high-signal | specificity floor — generic advice is dropped, audited in CI |\n| **Git history** (`--seed`, on by default) | Draft memories from revert/hotfix/workaround commits — your repo's real scars | noise-subject denylist (merge/bump/deps/wip/format dropped) |\n| **Scanner findings** (`hivelore ingest`) | SonarQube / SARIF / ESLint / `npm audit` findings as proposed, anchored memories with sensors | auto-fixable **stylistic** rules dropped (incl. Sonar numeric keys); `--include-stylistic` to keep |\n\n```bash\nhivelore init                                   # Detect stack + seed packs + seed git history\nhivelore ingest --from sonar issues.json --min-severity major\nhivelore ingest --from eslint report.json\nhivelore ingest --from sarif report.sarif --dry-run   # Preview without writing\n```\n\nIngested and git-seeded memories land as `proposed` (warn-only sensors). Review them with\n`hivelore memory list --status proposed`; promote vetted sensors to `block` with `hivelore sensors promote`.\n\n---\n\n## .ai/ directory layout\n\n```\nyour-project/\n├── .ai/\n│   ├── project-context.md          # Shared project overview\n│   ├── modules/                    # Per-component context files\n│   │   ├── backend/context.md\n│   │   └── frontend/context.md\n│   └── memories/\n│       ├── personal/               # Private — gitignored\n│       ├── team/                   # Shared — committed to git\n│       └── module/\u003cname\u003e/          # Module-scoped memories\n├── CLAUDE.md                       # Auto-generated bridge (Claude Code)\n├── AGENTS.md / GEMINI.md / …       # …and 10 more native bridges (see below)\n└── .github/\n    ├── copilot-instructions.md     # Auto-generated bridge for Copilot\n    └── workflows/\n        ├── hivelore-sync.yml       # Anchor verification on merge\n        └── hivelore-enforcement.yml # Required policy gate\n```\n\n### Native bridges — meet every agent where it is\n\nFor CLI/IDE agents without MCP, `hivelore init` generates native config files from the **same** corpus, so\nthe team's memories and **block sensors** travel to whatever agent a developer uses — not just an empty\ntemplate, the enforcement edge too. `hivelore sync` keeps them fresh; never hand-edit them (regenerate with\n`hivelore bridges sync`).\n\n| Agent | File | Agent | File |\n|---|---|---|---|\n| Claude Code | `CLAUDE.md` | Cline | `.clinerules` |\n| Cursor | `.cursor/rules/haive-memories.mdc` | Windsurf | `.windsurfrules` |\n| Codex / generic | `AGENTS.md` | Continue | `.continuerules` |\n| GitHub Copilot | `.github/copilot-instructions.md` | Cody | `.sourcegraph/cody-rules.md` |\n| Gemini CLI | `GEMINI.md` | Zed | `.rules` |\n| Aider | `CONVENTIONS.md` | Roo | `.roo/rules/haive.md` |\n\n```bash\nhivelore bridges list                 # Show target status\nhivelore bridges sync --all           # Regenerate every native bridge\nhivelore init --bridge-targets cursor,copilot   # Or scope to specific agents\n```\n\n---\n\n## Context policy records\n\n| Type | Description |\n|---|---|\n| `decision` | Architectural or design choices the team has locked in |\n| `gotcha` | Non-obvious constraints, known footguns, subtle invariants |\n| `convention` | Naming, patterns, style rules specific to this codebase |\n| `attempt` | Failed approaches — so agents don't repeat them |\n| `architecture` | Component boundaries, interfaces, data flow |\n\nAll records can be anchored to file paths and symbol names. When anchored code changes, Hivelore flags the record as potentially stale.\n\n---\n\n## MCP tools reference\n\n| Tool | Description |\n|---|---|\n| `get_briefing` | ⭐ Project context + decisions + gotchas + ranked breadcrumbs in one call |\n| `mem_save` | Save repo policy knowledge (decision, gotcha, convention, attempt, architecture) |\n| `mem_tried` | Record a failed approach so future agents do not repeat it |\n| `mem_search` | Full-text or semantic search across context records |\n| `mem_relevant_to` | Ranked context records for a task when project context is already loaded |\n| `mem_get` | Fetch one context record after a compact briefing/search result |\n| `code_map` | Look up symbols without manual grep when code-map is indexed |\n| `mem_verify` | Check anchor freshness, detect stale records |\n| `scaffold_test` | Generate a pending post-incident test from a lesson + the `sensors propose --kind test` line to arm it (monorepo-aware) |\n| `pre_commit_check` | Diff against known gotchas, decisions, and stale anchors |\n| `mem_session_end` | Save end-of-session recap for the next agent |\n\nMCP profiles keep the product focused:\n\n- `HAIVE_TOOL_PROFILE=enforcement` (default): compact coding-agent harness.\n- `HAIVE_TOOL_PROFILE=maintenance`: corpus review, lifecycle, distillation, code-search, and project-context maintenance.\n- `HAIVE_TOOL_PROFILE=experimental` / `full`: legacy aliases for `maintenance` (the experimental\n  diagnostics were removed in v0.32.0 — months of usage showed a single call across all of them).\n\n---\n\n## MCP prompts reference\n\n| Prompt | Description |\n|---|---|\n| `post_task` | ⭐ Post-task checklist — capture learnings before closing every session |\n| `bootstrap_repo` | ⭐ First-agent bootstrap — fills the whole knowledge layer the bootstrap gate requires (project-context, module contexts, anchored memories, a validated sensor per main area). Tailors a concrete checklist from the current corpus state and drives `bootstrap_project_save` → `mem_save` → `propose_sensor` until ready |\n| `bootstrap_project` | Analyze the codebase and write `.ai/project-context.md` |\n\n---\n\n## Packages\n\n| Package | Install | Description |\n|---|---|---|\n| [`@hivelore/cli`](./packages/cli) | `npm i -g @hivelore/cli` | Main product: init, enforce, run agents, briefing, memory, sync, CI/Git hooks |\n| [`@hivelore/mcp`](./packages/mcp) | bundled into `@hivelore/cli` | Policy-aware MCP server |\n| [`@hivelore/core`](./packages/core) | dependency | Types, schema, anchors, policy primitives, token budgets |\n| [`@hivelore/embeddings`](./packages/embeddings) | `npm i -g @hivelore/embeddings` | Optional: local semantic ranking (bge-small-en-v1.5, fully offline) |\n\n**Also in this repo:** a [VS Code extension](./packages/vscode) (surfaces memories inline + a Strategic\nCockpit over the CLI's observability) and a [GitHub Action](./packages/github-action) (posts relevant\nteam memories as a PR comment so reviewers and agents never miss a non-obvious constraint).\n\n**The PR loop.** Review feedback is team truth in the making: reply **`/hivelore remember \u003crule\u003e`**\non any review thread and the Action acknowledges it with the exact persist command; or run\n`hivelore ingest --from github-pr \u003cnumber\u003e` to turn a PR's human review instructions\n(\"never…\", \"always…\", \"prefer X instead\") into `proposed`, file-anchored memories — each one a\ncandidate for `sensors propose`, which is the step no inferential review bot can take.\nWith `persist-review-learnings` enabled (default), the Action creates a dedicated branch and PR\ncontaining the proposed memory; when repository write permission is unavailable, it falls back to\nthe local ingest command. Top-level PR comments and review-thread replies follow the same path.\n\n**Structural sensors.** `sensors propose --kind ast` accepts either a concise `--pattern` or a full\nast-grep `--rule \u003cjson\u003e` (`inside`/`has`/`not`/`all`/`any`). JavaScript/TypeScript are built in;\nPython, Go, Rust, and Java are optional language packages shipped with the CLI. Rules still pass\nHivelore's silent-on-current/fires-on-bad validation before they can block.\nNested relational rules are not recursive by default: add `\"stopBy\":\"end\"` when `has` or `inside`\nmust search every descendant, for example `{\"has\":{\"kind\":\"interpolation\",\"stopBy\":\"end\"}}`.\n\n---\n\n## Adaptive briefing\n\nA briefing only earns its place when it carries unguessable knowledge, so `get_briefing` returns\n`briefing_value: \"high\" | \"low\"`. When nothing team-specific matches the files/task, the auto-generated\nproject context is trimmed to a one-line note (config: `adaptiveBriefing`, default on) — so Hivelore\nsurfaces deeper context only when it actually knows something the model doesn't.\n\n---\n\n## CLI reference\n\n```bash\n# Setup\nhivelore init [--with-ci] [--no-bridges]         # Initialize .ai/ + bridge files + seed stack/git\nhivelore init --bridge-targets \u003call|csv\u003e         # Scope generated bridges to specific agents\nhivelore enforce install                         # Install Git hooks + CI enforcement\nhivelore enforce status                          # Enforcement posture report\nhivelore bridges list/sync [--all]               # Inspect / regenerate native agent bridges\nhivelore index code                              # Build .ai/code-map.json\nhivelore index code --status [--json]            # Report code-map / code-search index freshness\n\n# Daily use\nhivelore briefing [--task \u003ctext\u003e] [--files] [--json]   # Print context + relevant memories\nhivelore run -- \u003cagent command\u003e                  # Wrap any CLI agent in Hivelore session\nhivelore enforce check [--stage pre-commit]      # Policy gate\nhivelore enforce ci                              # CI entrypoint\nhivelore enforce finish                          # Final agent-exit gate: commit/push + version/tag protocol\nhivelore coverage [--source git|agent|both]      # Find changed files no memory covers\nhivelore sync [--since \u003cref\u003e] [--embed]          # Verify anchors + auto-promote\nhivelore sensors list/check/export/promote       # Operate executable memory sensors\n\n# Memory\nhivelore memory save --type \u003ctype\u003e --body \"\u003ctext\u003e\" [--paths \u003ccsv\u003e]  # Save a memory (anchor to files)\nhivelore memory list [--scope] [--status]        # List memories\nhivelore memory search \u003ctext\u003e                    # Full-text / semantic search\nhivelore memory get \u003cid\u003e                         # Read one record\nhivelore memory approve [\u003cid\u003e|--all]             # Mark as validated\nhivelore memory promote \u003cid\u003e                     # personal → team\nhivelore memory tried [--sensor-pattern \u003cre\u003e]    # Record a failed approach (one-shot guardrail)\nhivelore memory conflicts [\u003ca\u003e \u003cb\u003e] [--yes]      # List conflict candidates / resolve one pair\nhivelore memory verify [--update] [--json]       # Check anchor freshness\nhivelore memory import --from \u003cfile\u003e [--changelog]  # Import docs or a CHANGELOG as memories\nhivelore memory seed [stack|--git]               # Re-seed stack packs / git-history scars\n\n# Cold start (seed from existing signals)\nhivelore ingest --from sonar|sarif|eslint|npm-audit \u003cfile\u003e  # Scanner findings → anchored memories\nhivelore ingest --from \u003cfmt\u003e \u003cfile\u003e --dry-run    # Preview without writing\n\n# Indexes (symbol map + semantic search)\nhivelore index code [--status]                   # Build .ai/code-map.json / report freshness\nhivelore index memories                          # Build the semantic index (first run: ~110MB model)\nhivelore index query \u003ctext\u003e                      # Semantic search over memories\n\n# Release protocol\nhivelore release bump \u003cpatch|minor|major\u003e        # Lockstep version bump + CHANGELOG scaffold\nhivelore release tag                             # Tag vX.Y.Z at HEAD, push branch + tag\nhivelore release ship                            # After the bump commit: pull --rebase → tag+push → poll CI\n\n# Diagnostics\nhivelore doctor                                  # Analyze setup, emit recommendations\nhivelore eval --fail-under 80                    # Retrieval + sensor quality gate\nhivelore eval --semantic-ranking                 # Real embeddings lane (requires index)\nhivelore selftest                                # Self-test MCP tools (latency + payloads)\n```\n\n`hivelore eval` auto-synthesizes retrieval cases from anchored memories and, when present, also loads\n`.ai/eval/spec.json` for labeled retrieval/sensor cases. This repo uses that file to keep executable\nmemory sensors in CI, so a broken guardrail is caught before release.\nCommitted regression baselines use only versioned team/module memories and deterministic\nanchor/lexical ranking; local usage counters, personal memories, and optional embedding caches cannot\nmake a baseline pass locally but fail in a clean CI clone. Semantic search remains exercised by the\nembeddings/search test suites and by a separate `--semantic-ranking` CI lane backed by\n`.ai/eval/semantic-baseline.json`. That lane fails closed when the package or index is unavailable.\n\n`hivelore doctor` reports local setup drift that can make agents misdiagnose the repo: missing `pnpm`,\nstale workspace `dist` artifacts, global CLI/MCP version skew, outdated code-search indexes, and low\nmemory-anchor coverage.\n\n---\n\n## Multi-component projects\n\nFor 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.\n\n```bash\nmkdir -p .ai/modules/backend .ai/modules/frontend\n\ncat \u003e .ai/modules/backend/context.md \u003c\u003c 'EOF'\n# Module: backend\n- Spring Boot, Java 17, PostgreSQL\n- Always filter by tenantId in every repository query\n- Never modify existing Flyway migrations — create V{N+1}__desc.sql\nEOF\n\ncat \u003e .ai/modules/frontend/context.md \u003c\u003c 'EOF'\n# Module: frontend\n- React 19, TypeScript, TanStack Query v5\n- All API calls go through hooks in features/\u003cdomain\u003e/api/\n- Env vars must start with VITE_ to be exposed to the client\nEOF\n```\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/Doucs91/hivelore.git\ncd Hivelore\npnpm install\npnpm -r build    # Build all packages\npnpm -r test     # Run tests\n```\n\nRequires Node 20 LTS+, pnpm 9+.\n\n---\n\n## Contributing\n\nIssues and PRs are welcome. Please open an issue before starting significant work so we can align on direction.\n\n---\n\n## License\n\nApache 2.0 — see [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDoucs91%2Fhivelore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDoucs91%2Fhivelore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDoucs91%2Fhivelore/lists"}