How do I use Hivelore?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Hivelore Before editing PaymentService, show me relevant team decisions and known issues." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Hivelore

by Doucs91

Overview Schema Related Servers Score Discussions

TypeScript

Local

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.

npm License Node

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

hivelore init creates a .ai/ context policy layer in your repo.
Agents start every session with get_briefing — one MCP call that returns small default context plus deeper breadcrumbs ranked by task relevance.
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.
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.

Harness concern	Hivelore role
Feedforward guidance	`get_briefing`, module context, skills, decisions, gotchas, failed attempts
Feedback and gates	MCP ordering policy, `pre_commit_check`, Git hooks, CI enforcement, stale-anchor detection
Knowledge lifecycle	Git-native Markdown records, path/symbol anchors, confidence, retirement, linting
Boundaries	Hivelore complements unit/e2e tests, type checks, runtime traces, security scanners, and LLM evals; it does not try to replace them

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.

Harness dimension	Question it answers	Hivelore today
Maintainability	Is the code clean? (patterns, footguns, conventions)	✅ Covered — executable sensors + anti-pattern gate
Architecture fitness	Does it respect the team's structural decisions?	🟡 Partly — anchored `decision`/`architecture` memories + decision-coverage gate
Behaviour	Does the code do the functionally correct thing?	🟡 Bridged — command sensors route your own tests to lessons (see below)

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).

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> --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

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

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 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)

One knob decides what refuses: enforcement.posture.

posture	what refuses
`advisory`	nothing — everything is reported. For adopting Hivelore on a repo mid-flight
`balanced` (default)	deterministic, code-bound findings only: block sensors, anchored anti-patterns, stale anchors on files you touched, artifact hygiene
`strict`	the above, plus the process gates (briefing, recap, decision coverage, bootstrap) at the sharing points — `pre-push` and CI

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: the repo's knowledge-layer health percentage is a measurement of your baseline, reported but never a verdict on your change.

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.

Stage	Command	What it does
Set up	`hivelore init`	Create `.ai/`, bridge files, MCP config, hooks, CI
	`hivelore doctor`	Check the install is healthy
	`hivelore agent setup`	Wire your AI client (MCP, hooks)
Before editing	`hivelore briefing`	Feedforward context — the CLI mirror of `get_briefing`
Capture knowledge	`hivelore memory save`	Record a decision / convention / gotcha
	`hivelore memory tried`	Record a failed approach so it isn't repeated
	(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
Retrieve	`hivelore memory search` · `get`	Find, then read a record
Feedback	`hivelore sensors check`	Scan the diff against documented lessons
Gate	`hivelore enforce finish`	Exit gate before you call the task done
Sync	`hivelore sync`	Re-check stale anchors, refresh bridge files
Close	`hivelore session end`	Save a recap for the next session

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).

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

Gate	What it checks
First-agent bootstrap	On a cold corpus, the first agent is asked to fill the knowledge layer: 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. Reports by default; refuses at `posture: "strict"`
Briefing loaded	Agent loaded fresh context breadcrumbs before editing. Reports by default
Decision coverage	Changed files are covered by relevant anchored decisions in the last briefing. Reports by default
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`)
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
Stale anchors	Memories anchored to deleted/moved paths block — but only when the anchor is on a file this change touches. Stale anchors elsewhere are corpus maintenance, reported as a warning
Session recap	Agent captured what changed and what remains before closing. Reports by default
CI enforcement	Required check blocks merge on any gate failure

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.

Source	What it seeds	Quality gate
Stack packs (`--stack auto`, opt-in)	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
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)
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

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).

Agent	File	Agent	File
Claude Code	`CLAUDE.md`	Cline	`.clinerules`
Cursor	`.cursor/rules/haive-memories.mdc`	Windsurf	`.windsurfrules`
Codex / generic	`AGENTS.md`	Continue	`.continuerules`
GitHub Copilot	`.github/copilot-instructions.md`	Cody	`.sourcegraph/cody-rules.md`
Gemini CLI	`GEMINI.md`	Zed	`.rules`
Aider	`CONVENTIONS.md`	Roo	`.roo/rules/haive.md`

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

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

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

MCP tools reference

Tool	Description
`get_briefing`	⭐ Project context + decisions + gotchas + ranked breadcrumbs in one call
`mem_save`	Save repo policy knowledge (decision, gotcha, convention, attempt, architecture)
`mem_tried`	Record a failed approach so future agents do not repeat it
`mem_search`	Full-text or semantic search across context records
`mem_relevant_to`	Ranked context records for a task when project context is already loaded
`mem_get`	Fetch one context record after a compact briefing/search result
`mem_update`	Amend an existing record in place — add the anchor paths a lesson was missing
`propose_sensor`	⭐ Turn a captured lesson into a validated guardrail. You write the pattern; Hivelore proves it is silent on your current code and fires on the mistake before it is trusted to block
`report_friction`	Record friction with Hivelore itself, locally. Never sends anything — a human reviews with `hivelore report` and decides what becomes an issue
`code_map`	Look up symbols without manual grep when code-map is indexed
`code_search`	Semantic search over exported symbols (needs `@hivelore/embeddings` + `hivelore index code-search`)
`mem_verify`	Check anchor freshness, detect stale records
`scaffold_test`	Generate a pending post-incident test from a lesson + the `sensors propose --kind test` line to arm it (monorepo-aware)
`pre_commit_check`	Diff against known gotchas, decisions, and stale anchors
`mem_session_end`	Save end-of-session recap for the next agent

MCP profiles keep the product focused:

HAIVE_TOOL_PROFILE=enforcement (default): compact coding-agent harness.
HAIVE_TOOL_PROFILE=maintenance: corpus review, lifecycle, distillation, code-search, and project-context maintenance.
HAIVE_TOOL_PROFILE=experimental / 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

Prompt	Description
`post_task`	⭐ Post-task checklist — capture learnings before closing every session
`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
`bootstrap_project`	Analyze the codebase and write `.ai/project-context.md`

Packages

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

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.

Available Tools

15 tools

code_mapA

Look up where symbols (classes, functions, interfaces) are defined in the codebase.

USE INSTEAD OF grepping when you need to find where something lives. Requires hivelore index code to have been run (done automatically in autopilot mode).

TIP: include symbols in get_briefing directly for auto-lookup at session start.

PARAMETERS: symbol — name or partial name to search (e.g. 'PaymentService') file — filter by file path substring max_files — cap on results (default 40)

RETURNS: { available: bool, files: [{ path, exports: [{ name, kind, line, description }] }] } If available: false → run hivelore index code first.

ParametersJSON Schema

Name	Required	Description
`file`	No	Filter to files whose path contains this substring
`paths`	No	Filter to files under any of these path prefixes (e.g. ['packages/mcp/src/tools/', 'src/auth/']). OR-joined with `file` substring; useful to get a focused view of one module.
`symbol`	No	Filter to files exporting a symbol whose name contains this substring
`max_files`	No	Cap on returned files (hard limit, applied after token budget)
`max_tokens`	No	Approximate token budget for the response. When the matching set exceeds it, files are ranked by export density (exports per LOC) and the highest-signal ones are kept first. Omit to disable budgeting (legacy behavior).

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations, so description carries full burden. It discloses the return shape (available flag, files with exports), the prerequisite (index already run), and behavior when the index is unavailable (run hivelore index code first). This gives strong context for a read-only lookup tool, though it doesn't discuss auth or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear sections (description, usage note, tip, parameters, returns). Front-loaded purpose. Each sentence earns its place; the tip is genuinely useful. Slight redundancy with the PARAMETERS section duplicating schema, but not enough to penalize.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter tool with no output schema, the description is complete: it provides the return shape, an availability flag with fallback instruction, and the required precondition. The schema handles token-budget details, so nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds an example ('PaymentService'), clarifies partial-name matching, and includes the get_briefing auto-lookup tip, going beyond the schema for symbol and file parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb+resource: 'Look up where symbols (classes, functions, interfaces) are defined in the codebase.' Distinct from grep and sibling code_search by explicitly saying 'USE INSTEAD OF grepping when you need to find where something lives.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit use case: 'USE INSTEAD OF grepping when you need to find where something lives.' Also mentions prerequisite (hivelore index) and a tip to include symbols in get_briefing. Could strengthen by explicitly naming sibling code_search as an alternative for full-text search, but this is already good.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

code_searchA

Semantic search over the codebase — finds exported symbols (functions, classes, interfaces) related to a natural-language query. Replaces blind grep when you don't know the exact symbol name.

Requires hivelore index code-search to have been run (builds embeddings for every exported symbol from the code-map). Falls back to a notice when index is missing.

PARAMETERS: query — natural language (e.g. 'function that hashes passwords', 'JWT signing') k — number of top hits (default 5) min_score — minimum cosine similarity (default 0.2; try 0.3+ for stricter)

RETURNS: { available: bool, hits: [{ file, name, kind, line, description?, score }] }

ParametersJSON Schema

Name	Required	Description
`k`	No	Number of top hits to return.
`query`	Yes	Natural-language description of what you are looking for in the codebase (e.g. 'function that hashes passwords', 'JWT signing logic', 'route registration').
`min_score`	No	Minimum cosine similarity. Hits below this threshold are dropped to avoid noise. Try 0.3+ for stricter matching.

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the dependency on a pre-built index, the fallback notice if the index is missing, the return format (including `available`, `hits` with fields like file, name, kind, line, description, score), and the effect of `min_score` in dropping low-similarity hits. It also scopes the search to exported symbols only, which is non-obvious behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded: a crisp purpose statement, a usage rule with alternative, a prerequisite/fallback note, then compact PARAMETERS and RETURNS blocks. Every sentence contributes value, and there is no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a search tool with 3 parameters, no output schema, and no annotations, the description fully covers the essentials: what the tool does, when to use it, prerequisites, fallback behavior, parameter meanings, and return structure. It leaves no critical operational question unanswered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description's PARAMETERS section largely paraphrases the schema: examples for query and the min_score tip ('try 0.3+ for stricter') are already present in the schema. No new meaning is added beyond the structured definitions, so it stays at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool performs 'Semantic search over the codebase' and 'finds exported symbols (functions, classes, interfaces) related to a natural-language query'. It distinguishes itself from blind grep, and in the context of siblings like code_map, it emphasizes natural-language search over exact matching, giving it a distinct purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says 'Replaces blind grep when you don't know the exact symbol name', providing a clear when-to-use scenario and an alternative. It also discloses a prerequisite ('Requires `hivelore index code-search` to have been run') and the fallback behavior when the index is missing, giving the agent clear conditionals.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_briefingA

⭐ DEFAULT-FIRST for coding agents on any repo where hivelore init ran: call this BEFORE changing source or project config for the current goal (unless the developer explicitly opts out). One-shot onboarding: everything relevant in a single call under a token budget.

PROGRESSIVE DISCLOSURE — after this, drill down only if needed: mem_relevant_to / mem_search (compact lists) → mem_get (full body + anchors).

RETURNS (in order of priority): 0. action_required — ⚠️ HANDLE THIS FIRST if non-empty (see protocol below)

last_session — recap of the previous session (goal, what was done, next steps)
project_context — .ai/project-context.md (auto-generated from code-map if template)
module_contexts — relevant .ai/modules//context.md based on files being edited
memories — ranked team memories relevant to your task
symbol_locations — file:line:kind for any requested symbols (no grep needed)
setup_warnings — actionable warnings if setup is incomplete
decay_warnings — memories not read in >90 days (consider reviewing)

⚠️ ACTION_REQUIRED PROTOCOL — MANDATORY: If action_required[] is non-empty, STOP and for each item:

Show the developer the exact developer_message field verbatim
Wait for explicit human confirmation ('yes', 'go ahead', 'oui', etc.)
Only then proceed with any code changes NEVER act autonomously on cross-repo breaking changes, dep bumps, or contract diffs.

KEY PARAMETERS: task — what you are about to do (1–2 sentences) — ALWAYS provide this files — files you are about to edit — surfaces anchored memories symbols — symbol names to look up in the code-map (e.g. ['PaymentService']) format — 'full' (default) | 'compact' (1-line) | 'actions' (bullet-first excerpts) budget_preset — 'quick' | 'balanced' | 'deep' — scales max_tokens/memories/module contexts

EXAMPLE USAGE: get_briefing({ task: 'add a Stripe payment integration', files: ['src/payments/'], symbols: ['PaymentService'] })

CONFIDENCE LEVELS in memories: authoritative — validated + read 10+ times (highest trust) trusted — validated or proposed + read 3+ times low — proposed, few reads (take with caution) unverified — draft (unverified: true flag set)

Replaces 4–5 separate tool calls. Prefer this first; use mem_search / mem_get only for follow-up.

ParametersJSON Schema

Name	Required	Description	Default
`task`	No	What you are about to do, in 1–2 sentences. Used to rank relevant memories semantically.
`files`	No	Project-relative file paths the agent is currently looking at or about to edit
`track`	No	Increment read_count on returned memories
`format`	No	Output format: 'full' returns memory bodies (honors token budget via truncation); 'compact' returns a 1-line summary per memory (call mem_get for detail); 'actions' squeezes bodies to actionable bullet lines — fewer tokens vs full.	full
`symbols`	No	Symbol names to look up in the code-map (e.g. ['PaymentService', 'TenantFilter']). Returns the file(s) exporting each symbol so agents don't need to grep. Requires `hivelore index code` to have been run.
`semantic`	No	Use semantic ranking when a task is provided (requires `hivelore embeddings index`).
`max_tokens`	No	Approximate token budget for the entire briefing. Each section is allocated a share and truncated to fit.
`max_memories`	No	Cap on memories surfaced regardless of token budget
`budget_preset`	No	Shortcut token budget: 'quick' minimizes tokens/skip module CONTEXT slices; 'balanced' mirrors historical defaults; 'deep' uses a larger briefing. When set, overrides max_tokens, max_memories, and include_module_contexts.
`deterministic`	No	Ignore machine-local usage/impact signals so repeated evaluations rank the shared corpus reproducibly.
`include_stale`	No	Include stale memories (excluded by default — they may be outdated)
`memory_scopes`	No	Restrict the candidate corpus to selected scopes. Omit to include every scope.
`min_semantic_score`	No	Floor for semantic-only memory hits (cosine). The default (0) is not 'keep everything': on a corpus large enough to characterize a distribution, an adaptive floor at the corpus mean+½σ is applied so the undifferentiated mass of weak hits is trimmed while the top hit is always kept. Set an explicit value to raise the bar further; it never lowers the adaptive one. Has no effect on memories matched via anchor/module/literal — those are always kept.
`dedupe_project_context`	No	Token saver (default ON): skip re-emitting the project-context body if an identical copy was already sent within the last few minutes this session (the agent still has it). Set false to always include it.
`include_module_contexts`	No	Include the `.ai/modules/<name>/context.md` slices inferred from `files` (default ON). Set false to keep the briefing to project context + memories. Overridden by `budget_preset` when that is set.
`include_project_context`	No	Include the `.ai/project-context.md` body (default ON). Set false when the agent already has the project overview and you only want the module/memory layers — see `dedupe_project_context` for the automatic, session-aware version of the same saving.

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden, and it delivers: it discloses the priority-ordered return sections, the mandatory STOP-and-wait action protocol, confidence levels, token-budget truncation behavior, and that memory read counts can be incremented via the track parameter. It also warns about cross-repo breaking changes and contract diffs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with clear sections, priority numbering, and a front-loaded core directive. Some redundancy exists—'Replaces 4–5 separate tool calls' echoes the opening 'one-shot onboarding,' and 'KEY PARAMETERS' largely repeats schema fields—so not every sentence earns maximum credit, but the organization mitigates the length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema, the description makes the return contract explicit by enumerating all result sections in priority order and explaining the action_required protocol. It also provides invocation guidance, parameter semantics, example usage, and confidence-level interpretation. Nothing essential for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful usage nuance beyond the schema by explaining task should 'ALWAYS' be provided, files surface anchored memories, symbols eliminate grep, and budget_preset scales tokens/memories/module contexts. It does not cover every parameter in prose, but the schema already documents them thoroughly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: a one-shot onboarding/briefing tool to call before changing source or project config. It explicitly distinguishes itself from siblings by positioning mem_search/mem_get as follow-up tools and mem_relevant_to/mem_search as drill-down alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance ('call this BEFORE changing source or project config'), when-not-to-use guidance ('unless the developer explicitly opts out'), and names alternatives ('use mem_search / mem_get only for follow-up'). The mandatory action_required protocol also tells the agent exactly how to behave when the response demands it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mem_getA

Fetch a single memory by its full id with all details.

USE WHEN get_briefing / mem_relevant_to / mem_search returned a compact hit and you need the full body, or when you know the exact id of a memory.

PARAMETERS: id — full memory id (e.g. '2026-04-28-gotcha-flyway-strict-no-ddl')

RETURNS: { id, type, scope, status, confidence, body, anchor, tags, usage }

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	Memory id to fetch

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the transparency burden. It conveys a read-only fetch operation implicitly via the verb 'Fetch' and lists the return fields, but it doesn't explicitly state that the tool has no side effects or how it behaves on an invalid/unknown id. This leaves some behavioral context unaddressed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with distinct sections (purpose, usage when, parameters, returns) and is concise without fluff. Each line serves a clear function, and the key purpose is front-loaded, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-parameter fetch tool, the description covers the primary purpose, usage context, parameter format, and return fields. It lacks explicit error behavior or a note on idempotency, but given the tool's simplicity and the provided return schema detail, it is sufficiently complete for an agent to select and invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema only says 'Memory id to fetch' for the id parameter, while the description clarifies that it must be a 'full id' and provides a concrete example format ('2026-04-28-gotcha-flyway-strict-no-ddl'). This adds meaningful parameter semantics beyond the schema, especially given the schema coverage is 100%.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Fetch a single memory by its full id with all details,' a specific verb and resource that clearly defines the tool's scope. It distinguishes itself from sibling tools like mem_search by focusing on fetching a single memory by its unique full id, making its purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states 'USE WHEN get_briefing / mem_relevant_to / mem_search returned a compact hit and you need the full body, or when you know the exact id of a memory,' providing clear trigger conditions. It, however, doesn't formally exclude cases like needing to search without an id, so it stops short of fully explicit when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mem_relevant_toA

One-shot ranked memories for a task — use instead of get_briefing when project context is already loaded and you only want the relevant memory layer.

Second step in progressive disclosure (after get_briefing): narrow here, then mem_get for full text.

Reuses the same ranking pipeline (anchor / module / literal / semantic) but skips project_context, modules, action_required, etc.

PARAMETERS: task — 1–2 sentences describing what you are about to do (required) files — files you'll edit (surfaces anchored memories) limit — cap on returned memories (default 8) min_semantic_score — drop weak semantic hits below this cosine (default 0.25) format — 'full' | 'compact' | 'actions' (inherits get_briefing memory framing)

RETURNS: { task, search_mode, memories: [...], hints?: [...], empty?: true }

ParametersJSON Schema

Name	Required	Description	Default
`task`	Yes	What you are about to do, in 1–2 sentences. Used to rank relevant memories.
`files`	No	Optional: files you are about to edit — surfaces anchored memories.
`limit`	No	Cap on returned memories.
`format`	No	'compact' = id + 1-line summary; 'full' = complete bodies; 'actions' = bullet-first excerpts.	full
`min_semantic_score`	No	Drop weakly-related semantic hits below this cosine threshold.

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Although no annotations exist to provide safety profile, the description discloses the ranking pipeline (anchor/module/literal/semantic), what it skips, and the return shape. It doesn't explicitly state 'read-only', but the retrieval nature is clear; slightly more detail on side effects would be ideal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact, front-loaded with the key differentiator, and uses a clean PARAMETERS block. Every sentence earns its place; no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description includes a RETURNS section outlining the response shape. Combined with explicit workflow guidance and parameter clarifications, it covers the tool's role and behavior thoroughly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining 'inherits get_briefing memory framing' for format, and clarifying the purpose of files ('surfaces anchored memories'). It supports the schema without redundancy.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('ranked memories for a task') and clearly distinguishes from siblings by naming get_briefing as an alternative ('use instead of...'). It also explains the niche ('when project context is already loaded and you only want the relevant memory layer').

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly describes when to use this vs get_briefing, and places it in a progressive disclosure sequence ('Second step... after get_briefing... then mem_get'). Also clarifies what is skipped, leaving no ambiguity about scope.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mem_saveA

Save a piece of knowledge as a persistent memory that survives across AI sessions.

USE THIS WHEN you discover something worth remembering for future sessions:

A project convention (how things are done here)
An architectural decision and its rationale
A gotcha or non-obvious behavior that surprised you
A domain term and what it means in this codebase

DO NOT USE for failed approaches → use mem_tried instead (better structure). For reactive code discoveries during exploration, prefer a compact gotcha via mem_save.

PARAMETERS: type — convention | decision | gotcha | architecture | glossary | attempt slug — short kebab-case id (e.g. 'flyway-no-modify-existing') body — Markdown content with the full knowledge scope — team (shared with all devs) | personal (private) | module (component-scoped) paths — anchor to source files for staleness detection (STRONGLY recommended) topic — stable key for upsert: if a memory with same topic+scope exists, update it in-place

RETURNS: { id, scope, file_path, action: 'created'|'updated', warning?, invalid_paths? } WARNING: if paths point to non-existent files, they will be immediately stale after hivelore sync. DEDUP: identical body content within the same scope is rejected — use mem_update to modify.

ParametersJSON Schema

Name	Required	Description
`body`	Yes	Markdown body of the memory
`slug`	Yes	Short human-readable identifier — becomes part of the filename
`tags`	No	Tags for filtering
`type`	Yes	Kind of memory being saved. Use 'skill' for reusable procedures/playbooks agents should follow for recurring tasks (feedforward harness guide). Use 'attempt' for failed approaches (auto-validated). Use 'session_recap' via mem_session_end instead.
`paths`	No	Anchor paths (file paths this memory references)
`scope`	No	Visibility scope: personal \| team \| module. When omitted, falls back to defaultScope in haive.config.json (default: personal).
`topic`	No	Stable key for this memory. If a memory with the same topic already exists in this scope, it is updated in-place (revision_count++). Use for knowledge that evolves over time.
`author`	No	Author handle or email
`commit`	No	Anchor commit SHA (for staleness detection later)
`domain`	No	Domain (e.g. transactions, billing)
`module`	No	Module name (required when scope=module)
`symbols`	No	Anchor symbols (function/class names this memory references)
`lifecycle`	No	Does this describe code that EXISTS now, or a decision not yet built? 'applied' (default) = reflected in the code; 'planned' = decided but NOT yet implemented (surfaced distinctly so agents don't write code against it as if it were real); 'abandoned' = rejected, kept so it isn't re-tried.
`activation`	No	Only for type='skill'. Progressive-disclosure triggers: the skill is surfaced ONLY when a keyword matches the task or a glob matches the edited files (or always=true). Omit to keep the skill always-eligible.

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden, and it delivers: it discloses that memories persist across sessions, that topic+scope causes in-place update with revision_count++, that identical body is rejected, and warns about paths staleness. It also gives the return shape and action values, so agents understand side effects and outcomes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured into clear sections (purpose, when to use, parameters, returns, warning, dedup) with front-loaded purpose and no filler. Each line adds decision-relevant information, and the formatting makes it scannable for an agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 14 params, nested objects, and no output schema, the description covers the operation's purpose, usage, key parameters, return shape, and a warning about staleness. It leaves some optional parameters (tags, author, lifecycle, activation) to the schema, which is acceptable since schema descriptions are complete; the description could mention type='skill' handling to be fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, giving baseline 3, but the description adds real meaning for key parameters: slug format example, scope semantics (team/personal/module), paths as strongly recommended anchors, topic as upsert key. It omits some schema-described params like tags/author/lifecycle and lists type incompletely (missing skill and session_recap), so it's valuable but not flawless.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Save a piece of knowledge as a persistent memory that survives across AI sessions.' It also distinguishes itself from siblings by explicitly naming mem_tried for failed attempts and mem_update for modifications, making the tool's unique role clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use scenarios (project convention, architectural decision, gotcha, domain term), an explicit exclusion (failed approaches → mem_tried), and an explicit alternative for modification (mem_update). This is model guidance for tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mem_searchA

Search memories by keyword or semantic similarity.

USE WHEN you need to find a specific memory and don't know its id. For session onboarding, use get_briefing instead (richer, ranked, budgeted).

SEARCH MODES: Literal (default): AND search across id, tags, and body — all tokens must match. Falls back to OR automatically if no AND results (partial match). Lexical rank (lexical_rank: true, semantic: false): Okapi-BM25-style scoring on the filtered corpus — good for phrase-like queries without embeddings. Semantic (semantic: true): embedding-based similarity — finds related memories even with different wording. Requires hivelore embeddings index to be built.

PARAMETERS: query — search terms or natural language question scope — filter by personal | team | module type — filter by convention | decision | gotcha | architecture | glossary semantic — true for embedding-based search (requires @hivelore/embeddings) lexical_rank — BM25-style ranking (ignored when semantic is true) limit — max results (default 10)

RETURNS: array of { id, type, scope, status, confidence, body, match_quality }

ParametersJSON Schema

Name	Required	Description
`type`	No	Restrict results to a memory type. session_recap is excluded by default — use type='session_recap' to include them.
`limit`	No	Max results
`query`	Yes	Substring matched against id, tags, and body
`scope`	No	Restrict results to a single scope
`track`	No	Increment read_count on returned memories (used for passive validation)
`module`	No	Restrict results to a module
`status`	No	Filter by a single status. Omit to return all statuses.
`semantic`	No	Use semantic similarity from the embeddings index (requires `hivelore embeddings index`).
`min_score`	No	Minimum cosine similarity (semantic mode only)
`lexical_rank`	No	When true (and semantic is false), rank the filtered corpus with Okapi-BM25-style lexical scoring instead of literal AND/OR. Helps phrase-like queries without embeddings.
`exclude_rejected`	No	When true, exclude memories with status=rejected from results.
`include_session_recap`	No	Include session_recap memories in search results (excluded by default — they surface in get_briefing as last_session).

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Given no annotations, the description carries full burden. It discloses search-mode fallback (AND→OR), lexical ranking behavior, the requirement for an embeddings index, and session_recap exclusion. However, it does not mention the side effect of track=true incrementing read_count (though schema covers this), and it contains an incorrect default limit (10 vs schema's 20), slightly clouding behavioral expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with clear headings (USE WHEN, SEARCH MODES, PARAMETERS, RETURNS) and front-loads the purpose. It is longer than the minimal case but each section earns its place given the tool's complexity. Slight redundancy exists in the PARAMETERS section but it remains readable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main search modes, usage context, and return shape, which is significant given no output schema. However, it omits several schema parameters (status, module, exclude_rejected, include_session_recap) and contains an incorrect default limit, making it not fully reliable for complete understanding without the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description's PARAMETERS section adds a few interactions (e.g., lexical_rank ignored when semantic is true) but includes a serious factual error: limit default is stated as 10 while schema says 20. It also describes query as 'natural language question', which could mislead in literal mode where substring matching is used. These inaccuracies degrade value below baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb+resource: 'Search memories by keyword or semantic similarity.' It further differentiates from siblings by stating 'USE WHEN you need to find a specific memory and don't know its id' and explicitly contrasts with get_briefing, making the tool's purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance: 'USE WHEN you need to find a specific memory and don't know its id' and directs to get_briefing for session onboarding. It also notes that semantic mode requires an embeddings index, setting clear prerequisites for choosing this mode over others.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mem_session_endA

Save an end-of-session recap so the NEXT session starts with fresh context.

CALL THIS before closing any significant working session. In autopilot mode, the MCP server saves a minimal recap automatically on exit — but calling this manually produces a richer, more useful recap.

HOW IT WORKS: uses topic-upsert — one recap per scope is kept and updated in-place (revision_count increments). get_briefing surfaces the latest recap at the very top of the next session's briefing, before project context.

PARAMETERS: goal — what you were trying to accomplish (1–2 sentences) accomplished — what was actually done (bullet list recommended) discoveries — bugs, surprises, missing knowledge found during this session files_touched — key files read or modified (used as anchor for staleness) next_steps — what should happen in the next session or for a teammate scope — personal (default) | team

RETURNS: { id, scope, action: 'created'|'updated', revision_count }

ParametersJSON Schema

Name	Required	Description	Default
`goal`	Yes	What you were trying to accomplish this session (1–2 sentences)
`scope`	No	Visibility: personal = private to you, team = shared with the team	personal
`module`	No	Module name (required when scope=module)
`next_steps`	No	What should happen next (for the next session or a teammate)
`discoveries`	No	Any bugs, inconsistencies, surprises, or missing knowledge found during this session. Empty if nothing surprising was found.
`accomplished`	Yes	What was actually done — bullet list recommended
`files_touched`	No	Key files that were read or modified — used as anchor paths

TDQS

A4.1/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently explains the upserve behavior ('uses topic-upsert — one recap per scope is kept and updated in-place'), mentions that revision_count increments, and describes how get_briefing surfaces the latest recap. This goes beyond a simple write operation and gives the agent a clear mental model of side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized with clear sections (HOW IT WORKS, PARAMETERS, RETURNS) and front-loads the core purpose. It is somewhat long, but each section earns its place. The parameter list duplicates some schema information, but the added context (e.g., files_touched as staleness anchor) justifies the length. Minor redundancy prevents a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers usage, behavior, and the return shape, which is helpful given the absence of an output schema. However, it omits the 'module' parameter and fails to clarify the scope=module requirement, creating ambiguity about when that parameter is needed. This gap makes the description incomplete for a tool with 7 parameters and conditional requirements.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema coverage is 100%, the description's parameter section is misleading and incomplete. It lists scope as 'personal (default) | team' but omits the 'module' option present in the schema enum. It also drops the 'module' parameter entirely, which is required when scope=module. This introduces a conflict with the input schema and fails to add full semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Save an end-of-session recap so the NEXT session starts with fresh context.' It uses a specific action (save) on a specific resource (end-of-session recap) and explains the benefit. It also distinguishes itself from the autopilot auto-save and references get_briefing, setting it apart from sibling memory tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'CALL THIS before closing any significant working session' and contrasts manual use with the autopilot minimal automatic recap. This provides clear usage context. However, it does not explicitly name alternatives or exclusionary conditions (e.g., when not to use it), so it falls slightly short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mem_triedA

Record a FAILED approach so future agents don't repeat the same mistake.

USE THIS IMMEDIATELY when you try something and it doesn't work. This is the most valuable type of negative knowledge — it saves hours of debugging for future agents working on the same codebase.

Auto-validated (no approval cycle). Surfaced FIRST in future get_briefing calls so it's impossible to miss.

PARAMETERS: what — short title of what you tried (e.g. 'importing X with ESM dynamic import') why_failed — the exact error or reason it failed instead — what to do instead (the correct approach) scope — team (default) | personal paths — source files where the issue lives

RETURNS: { id, file_path, action: 'created' }

ParametersJSON Schema

Name	Required	Description
`tags`	No	Tags for filtering
`what`	Yes	Brief description of the approach that was tried
`paths`	No	Anchor file paths this applies to
`scope`	No	Visibility scope. Defaults to personal — EXCEPT when a one-shot `sensor` is attached: an enforced lesson is team truth (the sensor must travel to every machine and CI), so it defaults to team. Pass scope explicitly to override.
`author`	No	Author handle or email
`module`	No	Module name (required when scope=module)
`sensor`	No	ONE-SHOT loop close: validate and attach a sensor in the same call (equivalent to a follow-up propose_sensor). Validated against HEAD — silent on current code, fires on the bad example. If rejected, the attempt is still saved and the verdict tells you how to revise.
`instead`	No	What to use or do instead (recommended alternative)
`why_failed`	Yes	Why it failed or why it should NOT be used

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses useful behavioral traits: 'Auto-validated (no approval cycle)' and 'Surfaced FIRST in future get_briefing calls.' However, the description incorrectly states scope default as 'team (default)' while the schema says it defaults to personal unless a sensor is attached. This contradiction undermines transparency, and the main description omits the sensor validation behavior entirely.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (purpose, usage, behavior, params, returns) and front-loaded intent. However, the PARAMETERS list is incomplete and contains an inaccurate scope default, which reduces the quality of the structure. It's not overlong, but the misinformation detracts from its conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 9 parameters and a complex nested sensor object, but the description omits the sensor feature entirely and misstates scope default. It covers the simple failure-recording case well but is incomplete for advanced usage. Given the schema exists, it doesn't need to duplicate every detail, but it should at least be consistent and hint at the sensor capability.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description's PARAMETERS section adds concise semantics for what/why_failed/instead/paths, but it omits tags, author, module, and sensor. More critically, it states 'scope — team (default) | personal', which contradicts the schema's 'Defaults to personal — EXCEPT when a one-shot sensor is attached: ... defaults to team.' This misinformation actively misleads agents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Record a FAILED approach so future agents don't repeat the same mistake,' which clearly identifies the verb (record), resource (failed approach), and intended purpose. This instantly distinguishes it from sibling tools like mem_save or get_briefing by focusing on negative knowledge.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance: 'USE THIS IMMEDIATELY when you try something and it doesn't work' and explains the value ('saves hours of debugging'). It does not, however, mention when not to use it or directly compare to alternatives like mem_save, so it falls short of a perfect score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mem_updateA

Update the body, tags, or anchor of an existing memory in-place.

USE WHEN a memory exists but its content has become outdated or incomplete. This preserves the memory's id, usage history, and read_count.

For evolving memories that you will update repeatedly, use mem_save with a topic key instead (topic-upsert pattern).

PARAMETERS: id — full memory id to update body — new Markdown content (replaces existing body) tags — new tag list (replaces existing tags) paths — new anchor paths (replaces existing paths) symbols — new anchor symbols (replaces existing symbols)

RETURNS: { id, file_path, updated_fields: string[] }

ParametersJSON Schema

Name	Required	Description
`id`	Yes	Id of the memory to update
`body`	No	New Markdown body — replaces the existing body
`tags`	No	New tags array — fully replaces existing tags
`paths`	No	New anchor paths — fully replaces existing anchor.paths
`author`	No	New author handle or email
`commit`	No	New anchor commit SHA
`domain`	No	New domain label
`symbols`	No	New anchor symbols — fully replaces existing anchor.symbols

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses in-place mutation, that id/usage history/read_count are preserved, that parameters replace existing values, and the return format. Lacks error conditions (e.g., what if memory doesn't exist) but sufficient for typical use.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise and well-structured: a one-sentence summary, usage guidelines paragraph, parameter list, and return format. Every sentence adds value; no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter mutation tool with no output schema and no annotations, the description covers purpose, usage, parameter replacement semantics, and return format. It could briefly note error conditions (e.g., memory not found) but is otherwise complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (each parameter has a detailed description stating replacement semantics). The description adds a concise summary and groups parameters, but adds limited value beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool updates an existing memory in-place, specifying the exact components (body, tags, anchor). It contrasts with sibling mem_save for the topic-upsert pattern, providing clear differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (memory exists, content outdated/incomplete) and when not to (evolving memories: use mem_save with topic key). Provides clear alternative, which is excellent guidance for an AI agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mem_verifyA

Check whether memory anchor paths and symbols still exist in the current code.

USE WHEN you want to know if a specific memory is still valid after a refactor, or to check all memories for staleness (hivelore sync does this automatically).

PARAMETERS: id — check a single memory (omit to check all) update — write 'stale' or 'validated' status back to disk

RETURNS: { results: [{ id, status: 'fresh'|'stale'|'anchorless', reason? }] } Stale means the anchored file/symbol no longer exists at that path. Anchorless means the memory has no paths/symbols — staleness is undetectable.

ParametersJSON Schema

Name	Required	Description	Default
`id`	No	If set, verify only this memory id
`update`	No	Write the resulting status back to disk (status=stale or validated)

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses that the update parameter writes status back to disk, defines all three statuses (fresh, stale, anchorless), and explains the meanings of stale and anchorless. This is comprehensive behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections: purpose, USE WHEN, PARAMETERS, RETURNS. Every sentence provides necessary information without fluff, and the primary purpose is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Without an output schema, the description defines the exact return shape and all possible statuses. It covers both optional parameters, the automatic sync context, and the edge case of anchorless memories. This is complete enough for an agent to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers 100% of parameter descriptions. The description adds the key default that omitting id checks all memories, which is not in the schema. The update parameter is restated but adds no new meaning, so the added value is modest.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Check whether memory anchor paths and symbols still exist in the current code.' This clearly differentiates it from sibling tools like mem_get or mem_search, which retrieve memory content rather than validate existence.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit USE WHEN scenarios: 'after a refactor' or 'to check all memories for staleness.' It also mentions that hivelore sync handles this automatically, giving context for when the tool might not be needed. However, it does not explicitly name alternatives or state when not to use the tool, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pre_commit_checkA

One-shot 'should I block this commit?' check. Combines three signals, all run internally by this one call — you do not invoke them separately:

anti_patterns_check — known gotchas/attempts that match the diff
mem_for_files — conventions/decisions anchored to touched files
mem_verify — memories whose anchors are stale (knowledge may be wrong)

This is the COMBINED diff-scan layer — sensors, anti-patterns and stale anchors in a single call. hivelore enforce check is the git-hook gate that runs the same combination at commit time.

USE FROM A GIT HOOK or before finalizing a non-trivial change.

PARAMETERS: diff — raw unified diff text (e.g. git diff --cached) paths — affected file paths (project-relative) block_on — 'any' | 'high-confidence' (default) | 'never' semantic — use embeddings in anti_patterns_check (default true)

RETURNS: { should_block, summary, warnings, relevant_memories, stale_anchors }

ParametersJSON Schema

Name	Required	Description	Default
`diff`	No	Raw unified diff text to scan. If omitted, only `paths` is used. When called from a pre-commit hook, pipe the output of `git diff --cached`.
`paths`	No	Project-relative paths affected by the change. At least one of `diff` or `paths` should be provided.
`block_on`	No	When to set should_block=true: 'any' = any warning blocks; 'high-confidence' = only warnings from authoritative/trusted memories block; 'never' = report only, never block.	high-confidence
`semantic`	No	Enable semantic search in anti_patterns_check (requires embeddings index).
`anchored_blocks`	No	When true, ALSO block a high-confidence anti-pattern (attempt/gotcha) that is anchored to a touched file AND corroborated by the diff (literal token overlap, or semantic >= 0.45) — not just very strong semantic matches. Powers the 'anchored' enforcement gate. Config/docs-only commits are still downgraded. Default false preserves the soft, semantic-only blocking behavior.

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently explains that the tool combines three internal signals (anti_patterns_check, mem_for_files, mem_verify) without invoking them separately, and clarifies the meaning of parameters like `block_on` and `anchored_blocks`. However, it does not mention side effects on state (e.g., whether memories are modified), auth requirements, or rate limits. It does not contradict any annotations since none exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear lead sentence, bulleted list of internal signals, and parameter definitions. It is front-loaded with the core purpose. The description of the return value is brief but adequate. The only minor inefficiency is perhaps repeating the phrase 'anti_patterns_check' in the semantic parameter description, but overall it is efficient and scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (5 parameters, 3 internal signals), the description covers the purpose, usage, parameter semantics, and output format. No output schema exists, so the description provides a clear return structure (`should_block`, `summary`, etc.). It lacks details on edge cases (e.g., what happens if both `diff` and `paths` are omitted) and does not specify cost or latency implications of the three internal checks, which could be useful for an agent deciding whether to call this tool. Still, it is largely complete for most usage scenarios.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 5 parameters, including defaults and enums. The description adds value by explaining the blocking logic for `block_on` (e.g., 'any' blocks on any warning) and the `anchored_blocks` detailed behavior (token overlap, semantic threshold). This goes beyond the schema by providing the agent with decision guidance, earning a score above baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'One-shot should I block this commit? check', specifying the verb ('check'), resource ('commit'), and scope ('combines three signals'). It distinguishes itself from siblings by noting that the internal signals (anti_patterns_check, mem_for_files, mem_verify) are not invoked separately, making it clear this is a composite tool rather than a memory or code search tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool: 'USE FROM A GIT HOOK or before finalizing a non-trivial change.' It also hints that `hivelore enforce check` is an alternative for git-hook gates, providing context but not confusing the agent. No direct sibling tool does the same thing, so the guidelines are clear and no exclusions are needed beyond what's stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

propose_sensorA

Propose a discriminating sensor for a gotcha/attempt — YOU write the pattern (you understand the code), Hivelore validates it before trusting it to block. This is how a captured lesson becomes a RELIABLE block instead of an advisory note.

USE THIS right after mem_tried / mem_save on a gotcha whose mistake is detectable in code, to upgrade the auto-suggested (warn) sensor into a precise, promotable one.

Write a pattern that matches the FAULTY usage, and — crucially — an absent regex for the CORRECT-usage marker so it fires on the bug only, not every call (e.g. pattern=the API call, absent=the required option).

VALIDATION (a block proposal is accepted ONLY if): the pattern is not brittle, stays SILENT on the current (correct) anchored code, and FIRES on the bad example. A rejected proposal is NOT written — the returned reason/guidance tells you how to revise; then call propose_sensor again.

PARAMETERS: memory_id — the gotcha/attempt to protect pattern — regex matching the faulty usage absent — regex for the correct-usage marker (makes it discriminate) — strongly recommended bad_example— a snippet that SHOULD match (else examples are read from the lesson) severity — 'block' (default) | 'warn'

RETURNS: { accepted, reason?, guidance?, self_check, file_path? }

ParametersJSON Schema

Name	Required	Description	Default
`kind`	No	regex = pattern matched on added diff lines (default). ast = an ast-grep STRUCTURAL pattern (e.g. 'stripe.paymentIntents.create($$$)') matched on the AST of changed files — comments and strings can never false-positive; `absent` is a sub-pattern that must be missing INSIDE the match (requires the optional @ast-grep/napi engine). shell\|test = a COMMAND the gate runs when the diff touches the sensor's paths — routes the team's own oracle (an existing test, an invariant script) to this lesson. Command sensors only execute where enforcement.runCommandSensors=true.	regex
`rule`	No	kind=ast: full ast-grep Rule object (kind/inside/has/not/all/any/etc.). May be used alone or combined with pattern.
`flags`	No	Optional regex flags (e.g. 'i' for case-insensitive).
`paths`	No	Override scope paths. Defaults to the memory's anchor paths.
`absent`	No	Regex for the CORRECT-usage marker (e.g. 'idempotencyKey'). When it appears in the window around a match, the catch is suppressed — this is what makes the sensor discriminate the faulty call from the correct one. STRONGLY recommended for 'X without Y' lessons.
`command`	No	kind=shell\|test: command to execute (e.g. 'npx vitest run tests/payments/refund.spec.ts'). Non-zero exit = the lesson fires.
`message`	No	LLM-facing fix message shown when it fires. Defaults to one derived from the lesson.
`pattern`	No	kind=regex: regex matching the faulty usage; kind=ast: optional structural pattern (may be combined with `rule`).
`red_ref`	No	kind=shell\|test: prove the oracle actually catches the incident. A git ref (commit/branch) of the PRE-FIX state; validation replays it in a scratch worktree and requires the command to FAIL there (RED) in addition to passing on the current tree (GREEN). On success the sensor records red_proven: true — 'the test demonstrably catches the incident', shown in the prevention receipt.
`replace`	No	Set true to DELIBERATELY replace a sensor already hand-authored on this memory. Without it, a second proposal onto a memory that already carries a validated sensor is REFUSED — otherwise the second call silently destroys the first while still answering accepted:true. One memory holds one sensor; use a separate memory for a second, distinct symptom.
`incident`	No	Provenance: the real incident this sensor guards — a ticket/prod ref ('prod #442', 'INC-1029', '2026-06 refund overcharge'). Turns 'a test failed' into 'this reproduces the incident the test exists to prevent'. Surfaced in the block message and the prevention receipt. Strongly recommended for command/test sensors routed from a post-incident test.
`language`	No	kind=ast: explicit built-in/dynamic language name for non-standard file extensions.
`severity`	No	block = hard-fail the gate (accepted ONLY if it passes self-validation). warn = advisory.	block
`memory_id`	Yes	Id of the gotcha/attempt memory this sensor protects.
`timeout_ms`	No	kind=shell\|test: max runtime before the executor kills the command (default 120000).
`bad_example`	No	A code snippet that SHOULD match — proves the sensor catches the mistake. If omitted, examples are read from the lesson body.
`require_present`	No	kind=regex: make this a REQUIRED-PRESENCE invariant instead of a forbidden-pattern one. `pattern` then names a line that must REMAIN in the anchored file; the sensor FIRES when a change REMOVES it. Use for 'do not delete this critical line' lessons a diff-of-added-lines sensor cannot see. Validated by requiring the pattern to be PRESENT in the current anchored code (there must be something to guard).

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full responsibility and does so thoroughly. It discloses the validation process, that rejected proposals are not written, that the return object contains self_check and reason/guidance, and that a second proposal is refused unless replace=true to prevent silent destruction. It also explains the absent-parameter discrimination and the validation criteria (not brittle, silent on correct code, fires on bad example).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with labeled sections (USE THIS, VALIDATION, PARAMETERS, RETURNS). It front-loads purpose and usage before parameters. Every sentence adds necessary context for correct invocation, and the length is justified by the tool's complexity (17 parameters, multiple kinds, validation logic).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for a tool of this complexity. It covers when to use, how to construct the pattern and absent, validation criteria, return values (accepted, reason, guidance, self_check, file_path), and edge cases like replace semantics and the absence of bad_example. There is no output schema, but the description explicitly names the return fields. Nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though schema description coverage is 100%, the tool description adds significant semantic value beyond the schema. It explains the role of 'pattern' vs 'absent', gives an example (pattern=the API call, absent=the required option), and clarifies the meaning of bad_example and severity. It also explains the replace flag's dangerous behavior and how to avoid it, which is not in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Propose a discriminating sensor for a gotcha/attempt') and clearly distinguishes this from sibling memory tools (mem_save, mem_tried) by positioning it as the follow-up step that upgrades a warning to a blocking sensor. It explicitly says 'YOU write the pattern' and explains the validation role of Hivelore, leaving no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit usage guidance is given: 'USE THIS right after mem_tried / mem_save on a gotcha whose mistake is detectable in code'. It also explains when a proposal is rejected and tells the agent to call again, and warns against re-proposing onto a memory with an existing sensor unless replace=true. This is clearer than most tool descriptions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

report_frictionA

Tell Hivelore's maintainer that HIVELORE ITSELF got in your way — a bug in a Hivelore tool, a misleading message, wrong docs, or an improvement idea.

USE THIS WHEN the friction is with Hivelore, not with the project you are working on:

a Hivelore tool or command errored, or did something other than what it documented
a message or return value misled you into a wrong action
the docs/description for a tool were wrong, missing, or contradictory
you can see a concrete improvement to how a Hivelore tool behaves

DO NOT USE for anything about the project's own code → that is mem_tried (a failed approach) or mem_save (a gotcha/convention). This tool is only for feedback ON THE TOOLING.

STAYS LOCAL. Nothing is published: the report is appended to a machine-local journal under .ai/.runtime/ and a human reviews it with hivelore report list before anything reaches a public tracker. Never put secrets or customer code in a report.

EVIDENCE BAR: kind='bug' REQUIRES a runnable repro. Without one the report is still kept, but filed as 'suggestion' — an unreproducible bug claim cannot be acted on.

DEDUPLICATED: reports are fingerprinted on kind+surface+summary. If you get back already_reported=true, the point is already made — do not rephrase and send it again. The occurrence count is what ranks it for the maintainer.

PARAMETERS: kind — bug | suggestion | docs | confusing surface — the Hivelore tool or command involved (e.g. 'mem_save', 'enforce check') summary — one specific line stating the problem (this is the dedup key) expected — what you expected Hivelore to do observed — what it actually did (exact message or output) repro — a command/tool call that reproduces it, runnable as-is (required for 'bug')

RETURNS: { ok, kind, fingerprint, occurrences, already_reported, notice? }

ParametersJSON Schema

Name	Required	Description
`kind`	Yes	'bug' = Hivelore did the wrong thing (REQUIRES `repro`; without one it is filed as a suggestion); 'suggestion' = an improvement idea; 'docs' = the documentation was wrong or missing; 'confusing' = it worked but the output/naming misled you.
`repro`	No	The command or tool call that reproduces it, runnable as-is. Required to file a 'bug'.
`summary`	Yes	One line stating the problem, as specifically as you can. This is the dedup key.
`surface`	Yes	The Hivelore surface involved — an MCP tool or CLI command, e.g. 'mem_save', 'enforce check', 'sensors propose'. Used to group reports, so name the tool, not the file.
`expected`	No	What you expected Hivelore to do.
`observed`	No	What it actually did — the exact message or output.

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and delivers richly. It discloses that reports stay local, are not published, and are reviewed manually. It explains deduplication behavior via fingerprinting and the occurrence counting mechanism, and details the evidence bar where 'bug' requires a repro.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections and front-loaded purpose. It is thorough but not verbose, using bullet-like formatting. A slight deduction for length; while informative, it could be tightened slightly without losing clarity (e.g., 'EVIDENCE BAR' section could be more concise).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 6 parameters, 3 required, no output schema, no annotations, and complexity of deduplication/evidence rules, the description provides comprehensive coverage. It explains return fields, behavior, and constraints, making it complete enough for an agent to invoke correctly without gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds significant value by explaining each parameter's purpose in context (e.g., 'kind' enum meanings, 'surface' grouping logic, 'summary' as dedup key, 'repro' requirement for bugs), but some details like 'expected' and 'observed' are straightforward and the schema already describes them adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool is for reporting friction with Hivelore itself, using specific verbs ('Tell', 'get in your way') and explicitly distinguishes it from sibling tools like mem_tried and mem_save, which are for project-level issues. The scope is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool (list of Hivelore-related issues) and when NOT to use it (project code issues), naming sibling alternatives (mem_tried, mem_save). It also covers deduplication and evidence requirements.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

scaffold_testA

Generate a PENDING post-incident test from a lesson (attempt/gotcha) — the on-ramp to a command sensor. A command sensor routes YOUR test as its oracle, but someone has to write it; this writes the skeleton so you only fill in the assertion.

USE THIS right after mem_tried when the mistake is behavioural (a regex can't express it): it writes a stub carrying the incident's provenance and returns the exact sensors propose --kind test command to arm it.

It DOES NOT arm a sensor — propose_sensor stays the sole validated writer, and the stub is left PENDING (todo/skip) so the suite stays green until you write the assertion. Monorepo-aware: the framework and location come from the package that owns the lesson's anchor paths.

PARAMETERS: memory_id — the attempt/gotcha to scaffold from framework — vitest | jest | pytest | gotest (auto-detected when omitted) out_path — override the test file path (repo-relative) write — write the file (default true); false returns the content for preview

RETURNS: { ok, path, run_command, propose_command, content, written, already_exists, notice }

ParametersJSON Schema

Name	Required	Description
`style`	No	Test shape (default 'example'): 'property' states the invariant once and checks it over many generated inputs (fast-check/Hypothesis); 'differential' asserts the subject agrees with a `reference` implementation for all inputs. Both lower the cost of expressing the invariant.
`write`	No	Write the file to disk (default). false = return the content for preview without writing.
`red_ref`	No	Pre-fix incident commit/ref. When set, the scaffold names the symbols the fix (<red_ref>..HEAD) touched within the lesson's anchor scope and pre-fills the example around them, so the assertion is a targeted edit rather than a blank page. A bad ref falls back to the generic template.
`out_path`	No	Override the generated test file path (repo-relative).
`framework`	No	Test framework. Auto-detected from the package that owns the lesson's anchor paths when omitted.
`memory_id`	Yes	Id of the attempt/gotcha lesson to scaffold a post-incident test from.
`reference`	No	Required for style='differential': import specifier of the reference implementation to compare against.

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite having no annotations, the description discloses key behaviors: it produces a PENDING stub, does not arm a sensor, keeps the suite green, and is monorepo-aware. It also notes the dry-run 'write' parameter behavior. However, it doesn't discuss potential errors or overwrite semantics, so a 4 rather than 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: a clear opening sentence, a bolded usage directive, a non-goal clarification, and a concise parameter summary. It is longer than a single sentence but every line adds value; the only slight redundancy is repeating 'framework auto-detected' which already exists in the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the tool's role, its place relative to propose_sensor, the pending-test behavior, and the return shape. It leaves out explanation of the 'style' and 'red_ref' parameters, but those are fully defined in the schema, so the agent can rely on the schema. Given no output schema, the return field list could be more detailed, but it's sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already documents all 7 parameters at 100% coverage, so the baseline is 3. The description adds only a brief list of four key params and some narrative around their purpose, but does not add meaning beyond the schema for the omitted ones (style, red_ref, reference). It does reinforce that framework auto-detects and write has a preview mode, matching the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Generate a PENDING post-incident test from a lesson (attempt/gotcha)' — a specific verb, resource, and state. It also distinguishes from propose_sensor by explicitly stating it does NOT arm a sensor, making its scope unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance ('USE THIS right after mem_tried when the mistake is behavioural') and a clear exclusion ('It DOES NOT arm a sensor — propose_sensor stays the sole validated writer'). This gives an agent clear decision criteria among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

1 tool updatev0.57.8Sep 2, 2026

Changedget_briefing1 field changed

changedInput schema / properties / min_semantic_score / description

Previous value: -"Drop semantic-only memory hits whose cosine score is below this threshold. Useful to avoid weakly-related noise when the task is short or the corpus is broad. Has no effect on memories matched via anchor/module/literal — those are always kept. Try 0.25–0.4 for stricter matching."New value: +"Floor for semantic-only memory hits (cosine). The default (0) is not 'keep everything': on a corpus large enough to characterize a distribution, an adaptive floor at the corpus mean+½σ is applied so the undifferentiated mass of weak hits is trimmed while the top hit is always kept. Set an explicit value to raise the bar further; it never lowers the adaptive one. Has no effect on memories matched via anchor/module/literal — those are always kept."

2 tool updatesv0.57.7Aug 30, 2026

Changedmem_save1 field changed

addedInput schema / properties / lifecycle

Added value: +{
+  "description": "Does this describe code that EXISTS now, or a decision not yet built? 'applied' (default) = reflected in the code; 'planned' = decided but NOT yet implemented (surfaced distinctly so agents don't write code against it as if it were real); 'abandoned' = rejected, kept so it isn't re-tried.",
+  "enum": [
+    "applied",
+    "planned",
+    "abandoned"
+  ],
+  "type": "string"
+}

Changedpropose_sensor2 fields changed

addedInput schema / properties / replace

Added value: +{
+  "default": false,
+  "description": "Set true to DELIBERATELY replace a sensor already hand-authored on this memory. Without it, a second proposal onto a memory that already carries a validated sensor is REFUSED — otherwise the second call silently destroys the first while still answering accepted:true. One memory holds one sensor; use a separate memory for a second, distinct symptom.",
+  "type": "boolean"
+}

addedInput schema / properties / require_present

Added value: +{
+  "default": false,
+  "description": "kind=regex: make this a REQUIRED-PRESENCE invariant instead of a forbidden-pattern one. `pattern` then names a line that must REMAIN in the anchored file; the sensor FIRES when a change REMOVES it. Use for 'do not delete this critical line' lessons a diff-of-added-lines sensor cannot see. Validated by requiring the pattern to be PRESENT in the current anchored code (there must be something to guard).",
+  "type": "boolean"
+}

2 tool updatesv0.1.1Aug 18, 2026
- Addedmem_update
- Addedreport_friction
13 tool updatesv0.1.0Aug 17, 2026
- First observedcode_map
- First observedcode_search
- First observedget_briefing
- First observedmem_get
- First observedmem_relevant_to
- First observedmem_save
- First observedmem_search
- First observedmem_session_end
- First observedmem_tried
- First observedmem_verify
- First observedpre_commit_check
- First observedpropose_sensor
- First observedscaffold_test

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0

Disambiguation4/5

Most tools target clearly distinct operations: memory CRUD, code lookup, sensor proposal, and commit checking are well-separated. Some overlap exists between mem_search, mem_relevant_to, and get_briefing (all return relevant memories), and between code_map and code_search, but the descriptions provide enough guidance to disambiguate.

Naming Consistency4/5

The mem_ prefix clearly groups memory operations and code_ groups code lookups, which is a strong pattern. A few standalone names (get_briefing, scaffold_test, propose_sensor, pre_commit_check, report_friction) break the prefix scheme, though they still follow a readable verb_noun style.

Tool Count4/5

Fifteen tools sit at the upper edge of the well-scoped range, but each tool has a defensible purpose: memory lifecycle, code intelligence, sensor/test scaffolding, and enforcement. The count feels slightly heavy for a single server but not bloated.

Completeness4/5

The memory surface covers create, read, search, update, verification, and session recap, but there is no delete operation for memories. Sensor and test scaffolding also lack lifecycle management (update/remove), though agents can work around most gaps with mem_update or by proposing replacements.

Maintenance

ActivityActive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

governance-platform A
ai.geodesiclabs
Pre-execution governance for AI agents. Deterministic PASS/FAIL/REVIEW verdicts, replayable proof.
AI & Machine Learning Testing & QA Tools Monitoring
373
architect
com.hirosecure
Security reviews for coding agents: diffs checked against your org policy and live infrastructure.
Security Code Analysis CI/CD & DevOps
1
CoderbudsOAuth
com.coderbuds
Your team's shipping standards, org map and delivery metrics, inside your coding agent.
1
gjallaOAuth
io.gjalla
Production-readiness for your AI coding agents.
Coding Agents Agent Orchestration
22

Related MCP Servers

Knowledge Graph Memory Server
Knowledge & Memory Databases
modelcontextprotocol
A
license
B
quality
A
maintenance
A basic implementation of persistent memory using a local knowledge graph. This lets Claude remember information about the user across chats.
Updated 3 days ago (2026-09-03 01:42 UTC)
9
73,646
90,042
-
MCP Memory Server
Knowledge & Memory Coding Agents Developer Tools
keleshteri
A
license
B
quality
D
maintenance
Gives AI coding assistants persistent memory, safety controls, and project awareness by tracking coding sessions, protecting critical files from modifications, and managing approval workflows with automatic changelog generation.
Updated a year ago (2025-08-30 04:43 UTC)
19
18
MIT
MCP Policy Gatekeeper
Autonomous Agents Security Developer Tools
GILSMON
F
license
A
quality
D
maintenance
Provides real-time policy enforcement for AI coding agents by intercepting and validating their actions against organizational standards like naming conventions, security policies, and compliance rules before execution. Prevents violations through immediate feedback and auto-correction suggestions.
Updated a year ago (2025-10-15 07:07 UTC)
5
-
FlowCheck MCP Server
Version Control Security Monitoring
backslash-ux
A
license
A
quality
D
maintenance
Acts as a production-grade safety layer for AI-assisted coding, monitoring Git hygiene, scanning for security issues (PII, secrets, injection), and enabling semantic history search.
Updated 7 months ago (2026-02-16 07:06 UTC)
9
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Doucs91/hivelore'

If you have feedback or need assistance with the MCP directory API, please join our Discord server