io.github.Doucs91/hivelore

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.

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

⭐ 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/<name>/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…

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 }

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 }

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.

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 }

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 }

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

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: [Diff-scan layer: the COMBINED check (sensors + anti-patterns + stale). `hivelore enforce check` is the gate that runs this at commit time.] 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) 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 }

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 }