| name | memory-guide |
| description | Use when the user asks about hoangsa-memory itself — available MCP tools, CLI commands, resources, prompts, skill catalog, or how to drive the memory/graph workflow. Examples: "what hoangsa-memory tools are available?", "how do I use hoangsa-memory?", "what skills do I have?".
|
| metadata | {"version":"0.0.1"} |
hoangsa-memory Guide
Quick reference for every hoangsa-memory MCP tool, resource, prompt, and skill.
hoangsa-memory is a local memory + code-graph server exposed over MCP — it pairs
a hybrid retriever (symbol + BM25 + vector + graph) with a markdown
memory layer (MEMORY.md, LESSONS.md, USER.md) and a PreToolUse
discipline gate.
Always Start Here
For any non-trivial coding task:
- Call
memory_recall with a query derived from the user's intent. The
UserPromptSubmit hook also recalls for context, but that ceremonial
call does not satisfy the discipline gate — only agent-initiated
recalls do (it passes log_event: false; yours defaults to true).
- Read the chunks. Each has
path:line-span you can cite. Bodies are
stripped by default — Read path:L-L on a hit, or pass detail: true.
- Match the task to one of the skills below and follow its workflow.
- After acting, reflect via the
memory_reflect prompt → persist
fact/lesson if durable.
If memory_recall returns (no matches — did you run memory_index?),
stop and run hoangsa-memory index . (CLI) or memory_index (MCP) before
continuing.
Skills
| Skill | When to read it |
|---|
memory-discipline | Before any Write/Edit/Bash — enforces the recall loop. |
memory-reflect | End of session / after a bug fix / "what did we learn". |
memory-exploring | "How does X work?" / architecture questions. |
memory-debugging | "Why does this fail?" / tracing errors. |
memory-impact-analysis | "What breaks if I change X?" / pre-commit safety. |
memory-refactoring | Rename / extract / move / restructure. |
memory-cli | Running hoangsa-memory index, query, memory dream, … |
MCP tools
Retrieval
memory_recall { query, top_k?, scope?, tags?, min_score?, detail?, log_event? } — hybrid recall (symbol + BM25 + graph + markdown +
semantic). Returns ranked chunks with path, line span, preview, and
graph context. scope ∈ curated (default: code + facts/lessons) |
archive (verbatim conversations only) | all. log_event defaults
to true — that log is what proves to hoangsa-cli enforce that you
consulted memory before mutating.memory_index { path? } — walk a source tree, parse it, populate
symbols / call graph / BM25 / chunks. path defaults to ..memory_symbol_context { fqn, limit? } — 360° view of a symbol:
callers, callees, extends, extended_by, references, siblings,
unresolved imports. Pure graph lookup keyed on exact FQN.memory_impact { fqn, direction?, depth? } — BFS blast radius.
direction ∈ up | down | both (default up), depth ∈ [1,8]
(default 3). up answers "what breaks if I change X?".memory_detect_changes { diff, depth? } — feed a unified diff
(stdout of git diff), returns touched symbols + upstream blast
radius per hunk. Ideal as a PR pre-check.memory_event_trace { topic, bus?, limit? } — publishers and
subscribers of an event-bus topic. Use when a pub/sub flow is
decoupled by a broker so memory_symbol_context can't connect the two
halves.
Graph traversal & analytics
Reach for these instead of repeated Grep/Read when tracing how code
connects — one call replaces many searches. Unknown FQNs land in
unresolved; these tools do not error on a bad name.
memory_graph_query { start[], direction?, edge_kinds?, max_depth?, max_nodes?, format? } — BFS from seed symbol(s). direction ∈
out | in | both (default out), edge_kinds ∈ calls, imports, references, extends, declared_in, emits, subscribes. format ∈
json (default) | dot (Graphviz). Answers "who calls X / what does
X reach". truncated is set when max_nodes (default 500) is hit.memory_graph_paths { from, to, edge_kinds?, direction?, max_depth? }
— shortest dependency path A→B. Returns found: false when
unreachable within max_depth (default 10).memory_graph_communities { min_size? } — architecture map:
clusters of tightly-coupled symbols via label propagation over
Calls/Imports/Extends. Answers "what are the main components?" without
reading the tree. Sorted largest-first; min_size defaults to 3.memory_graph_processes { max_depth?, entry_globs? } — execution
flows from entry points down Calls edges. Symbols ending in ::main
are always entry points; add more via entry_globs. Answers "walk me
through what happens from startup".memory_taint_paths { sources?, sinks?, max_depth?, max_findings? }
— security dataflow: can untrusted input reach a dangerous sink?
Traces source→sink over DataDep and Calls edges only, never plain
control flow. Requires an index built with --pdg. Omitting
sources/sinks uses built-in defaults (env vars, stdin, args →
subprocess, eval, fs::write, query).
Memory (read)
memory_wakeup { scope?, include_on_demand? } — compact
one-line-per-entry index of facts, lessons, and preferences. Start
here at session start; it's far cheaper than memory_show. scope ∈
all (default) | facts | lessons | preferences. Only
always-scope facts appear unless include_on_demand: true.memory_detail { id } — full content of one entry. id is an
index from memory_wakeup (e.g. F03, L01) or a heading substring.memory_show — dump MEMORY.md + LESSONS.md + USER.md whole.
Prefer wakeup + detail once memory grows.- Resources:
resources/read with URI hoangsa-memory://memory/MEMORY.md
or hoangsa-memory://memory/LESSONS.md — same data, lighter wire shape.
The audit trail is .hoangsa/memory/memory-history.jsonl; read the file
directly, there is no tool for it.
Memory (write)
memory_remember_fact { text, tags?, scope? } — append a durable
fact. scope: "on-demand" keeps it out of the always-injected set.memory_remember_lesson { trigger, advice, suggested_enforcement?, block_message? } — append a reflective lesson. trigger is a
situation description ("adding a retry to an HTTP call"), not a
command. A trigger that already exists is rejected, with the
existing advice returned — use memory_replace if yours supersedes it.memory_remember_preference { text, tags? } — first-person,
cross-project workflow choice. Lands in USER.md.memory_replace { kind, query, new_text } / memory_remove { kind, query } — edit or drop one entry. kind ∈ fact | lesson | preference. This is how you resolve a cap-exceeded error or a
duplicate trigger.memory_skill_propose { slug, body, source_triggers? } — draft a
new skill from ≥5 related lessons. Lands in
.hoangsa/memory/skills/<slug>.draft/ for user review.memory_skills_list — enumerate installed skills.
Confidence counters are bumped for you — the Stop hook records a success
or failure against every lesson it surfaced (via hoangsa-memory memory lesson-feedback). Pruning is automatic too: the daemon runs the forget
pass (TTL, capacity, decay, quarantine) and, when [dream].enabled, the
dream consolidation pass. There is no MCP tool for either.
Conversation archive
Verbatim conversation history, separate from curated memory. Normally
driven by the PreCompact / SessionEnd hooks; query it when the user
refers to a past discussion rather than to code.
memory_archive_status — sessions, turns, curated count. ~100
tokens; good for orientation.memory_archive_topics { project? } — topics with session and
turn counts.memory_archive_search { query, top_k?, project?, topic? } —
semantic search over archived conversations. Finds past discussions,
decisions, and context. (memory_recall with scope: "archive" or
"all" reaches the same corpus alongside code.)memory_archive_ingest { project?, topic?, refresh?, limit? } —
ingest Claude Code sessions through the daemon so concurrent sessions
don't each reload the ONNX model. Hook-driven; rarely called by hand.memory_turn_save { session_id, role, content, commit_sha?, file_paths? } — save one verbatim turn. commit_sha + file_paths
let memory_archive_search link the turn back to the code state at
that moment.memory_turns_search { query, top_k? } — full-text (FTS5) search
over saved turns, with session context.
MCP prompts
Fetch via prompts/get { name, arguments }:
memory_nudge { intent } — surfaces LESSONS.md entries whose
trigger plausibly applies, and forces you to restate the plan naming
each lesson you're honouring.memory_reflect { summary, outcome? } — end-of-step reflection.
Drives the fact/lesson decision.memory_grounding_check { claim } — verify a factual claim
against the indexed graph before asserting it. Only advertised when
[curation] grounding_check = true (legacy alias: [discipline]).
Enforcement
PreToolUse gating lives in hoangsa-cli hook enforce, not in this
crate. It reads .hoangsa/rules.json plus
.hoangsa/state/enforcement.events — see the hoangsa-cli rule docs.
If the gate blocks, the stderr message tells you which prerequisite
(e.g. memory_recall, memory_impact) is missing — call it, then
retry.
CLI parity
Most MCP tools have a CLI equivalent for headless use:
| CLI | MCP tool |
|---|
hoangsa-memory query <text> | memory_recall |
hoangsa-memory index [path] | memory_index |
hoangsa-memory impact <fqn> | memory_impact |
hoangsa-memory context <fqn> | memory_symbol_context |
hoangsa-memory changes [--from <file|->] | memory_detect_changes |
hoangsa-memory graph query | paths | communities | processes | taint | memory_graph_*, memory_taint_paths |
hoangsa-memory memory show | memory_show |
hoangsa-memory memory fact | lesson | memory_remember_* |
hoangsa-memory archive <ingest|search|status|topics> | memory_archive_* |
CLI-only: init, watch, prefetch-embed, projects, memory edit,
memory lesson-feedback, memory dream. Note the CLI takes the redb
lock exclusively — stop the daemon first, or prefer the MCP tool.
See the memory-cli skill for the full command tree.
