Hivelore

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 }

List memories with optional filters. Use for browsing, not for task onboarding. For task onboarding use get_briefing (ranked + budgeted). For keyword search use mem_search. PARAMETERS: scope — personal | team | module type — convention | decision | gotcha | architecture | glossary status — draft | proposed | validated | stale | rejected tags — filter by tags (AND match) module — filter by module name RETURNS: array of { id, type, scope, status, confidence, tags, created_at }

List memories in 'proposed' status awaiting review, sorted by read count. USE IN MANUAL MODE to see what memories are waiting for human review. New projects disable automatic approval; existing repositories retain their configured policy. High read_count on a proposed memory = many agents found it useful without rejecting it = strong signal to approve. RETURNS: array of { id, type, scope, read_count, created_at, body_preview }

Mark a memory as rejected and record a reason. USE WHEN a memory is factually wrong, outdated, or not useful. Rejection blocks auto-promotion and lowers the memory's trust signal. Rejected memories are excluded from get_briefing by default. PARAMETERS: id — full memory id to reject reason — why this memory is being rejected (stored in frontmatter) RETURNS: { id, previous_status, new_status: 'rejected' }

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

Diagnostics: resolve which project root Hivelore is using (never throws). USE IN multi-root workspaces or when the agent CWD may not be the repo root — mirrors HAIVE_PROJECT_ROOT, findProjectRoot markers, and presence of .ai/memories. PARAMETERS: cwd — optional directory used for discovery when HAIVE_PROJECT_ROOT is unset RETURNS: { ok: true, info: { cwd, resolved_root, haive_project_root_env, … } }

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

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 …

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

Propose a stable `topic` key (topic-upsert) from type + short title. USE BEFORE mem_save when you want deterministic updates to the same memory over time; families mimic Engram-style grouping (architecture/*, bug/*, decision/*, …). PARAMETERS: type — convention | decision | gotcha | architecture | glossary | attempt | session_recap title — phrase to slugify under the suggested family prefix RETURNS: { topic_key, family, type }

Chronological view of related memories: by shared frontmatter.topic OR expanded from a seed id (related_ids, same topic, overlapping anchor paths — one extra hop on related_ids). PARAMETERS: memory_id — optional seed memory id topic — optional topic key (required if memory_id omitted) limit — max entries (default 30) RETURNS: { entries: [{ id, type, scope, created_at, one_line, topic? }], total, notice? }

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 …

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

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 '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 fin…

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=t…

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

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