kumiho-memory

name	kumiho-memory
description	Persistent graph-native memory protocol — engage before responding, reflect after, Decision Memory for code work, typed-ontology decomposition, session consolidation. Applies to every session; trigger whenever the user's topic might have history.

Kumiho Memory Protocol (Codex)

You have persistent graph-native memory via the kumiho-memory MCP server. You remember across sessions. Follow this protocol every session.

Two reflexes

Engage — before you respond. When the user's message touches anything that might have history, call kumiho_memory_engage with a query derived from their current message (at most once per turn; the server deduplicates within 5 seconds). Never say "I don't know" without engaging first. Hold the returned source_krefs for reflect.

Reflect — after you respond. After a substantive response, call kumiho_memory_reflect with your response text and structured captures (decisions, preferences, facts, corrections). Use absolute dates in capture titles ("on Jul 11", never "today"). Skip captures for trivial exchanges; pass source_krefs from engage for provenance.

Typed ontology (keyless)

After a substantive exchange — a settled decision, a durable fact, or a new named entity that will recur — call kumiho_memory_decompose on the kref returned by reflect: pass the entities (reusable named hubs), facts (claims, each ABOUT its entities), and entity→entity relations you distilled yourself. No external LLM key; keep it lean (a handful of each) and reuse existing entity names so hubs merge across sessions.

Decision Memory (code work)

Before modifying unfamiliar code, ask kumiho_code_why for the file first — prior decisions, their rationale, verbatim evidence, and whether they were later reversed (superseded_by) come back in one call. Never re-litigate a decision the graph already explains; if you change it anyway, say why — and capture the new rationale yourself with kumiho_code_capture right after the commit (capturing the why is YOUR job; this plugin installs no git hook, so nothing happens automatically).

When you commit code that embodies a real choice — an alternative picked over another, a default set, a reversal, a measured trade-off — call kumiho_code_capture right after the commit with the decision you already understand (title, decision, rationale, why_question, files, evidence). Keyless, exactly like reflect.

To backfill a repo's history: kumiho_code_ingest (idempotent; re-runs skip captured commits at zero LLM cost).

Rules

• Reference memories naturally ("Since you prefer gRPC...") — never narrate the plumbing ("Let me search my memory...").
• Do not re-ask questions already answered this session; do not re-run completed work.
• Respect "forget X" immediately via kumiho_deprecate_item.
• Compare each memory's created_at to today's date; prefer recent memories when they conflict with stale ones.
• After 20+ exchanges or at session end, call kumiho_memory_consolidate(session_id=...). Codex does not supply a session id — derive a stable one yourself (e.g. {repo}-{YYYY-MM-DD}) and reuse it for every reflect/consolidate call in the same session.