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.

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

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

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 }

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

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 }

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

1. last_session — recap of the previous session (goal, what was done, next steps)

2. project_context — .ai/project-context.md (auto-generated from code-map if template)

3. module_contexts — relevant .ai/modules//context.md based on files being edited

4. memories — ranked team memories relevant to your task

5. symbol_locations — file:line:kind for any requested symbols (no grep needed)

6. setup_warnings — actionable warnings if setup is incomplete

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

1. Show the developer the exact developer_message field verbatim

2. Wait for explicit human confirmation ('yes', 'go ahead', 'oui', etc.)

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

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 }

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 }

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.

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[] }

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.

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 }

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

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

1. anti_patterns_check — known gotchas/attempts that match the diff

2. mem_for_files — conventions/decisions anchored to touched files

3. 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 }