Kumiho memory tools

When [kumiho].enabled = true, Revka injects the Kumiho MCP sidecar into every non-internal agent, and the sidecar publishes a set of kumiho_memory_* tools into that agent’s tool catalog. These are the tools an agent calls to read from and write to the graph-native memory backend during its own LLM loop. This page is the per-tool reference: what each tool does, its parameters, its return shape, and when to reach for it.

Read Memory overview for the conceptual split between the no-op runtime binding and Kumiho, Kumiho setup to install the sidecar and supply auth tokens, and Kumiho graph memory for the agent-loop walkthrough. For the underlying data model — spaces, items, revisions, krefs, and edges — see Graph model: spaces, items & provenance.

Note

These tools appear in the agent tool catalog only when the sidecar is installed, an auth token is present, and the backend is reachable. If they are missing, verify the wiring per Kumiho setup — the usual cause is a missing KUMIHO_SERVICE_TOKEN/KUMIHO_AUTH_TOKEN or an unreachable [kumiho].api_url. You can confirm the catalog at GET /api/tools (see Status, health, config & tools endpoints).

The two-reflex pattern

Almost every Revka agent loop has the same shape: engage memory before responding, reflect after responding. Two tools carry that pattern, and the rest of the tools on this page are either deeper variants of them or maintenance operations.

1. Before responding, call kumiho_memory_engage once with a query derived from the user’s current message. It recalls relevant memories and returns a prompt-injectable context string plus source_krefs.
2. After responding, call kumiho_memory_reflect once with your response text and any structured captures. Pass the source_krefs from engage so new captures link back to what inspired them with DERIVED_FROM edges.

user message
   │
   ▼
kumiho_memory_engage   ──►  context + source_krefs
   │
   ▼
(agent reasons, responds)
   │
   ▼
kumiho_memory_reflect  ──►  captures stored, DERIVED_FROM edges created

One engage per turn

The sidecar enforces a 5-second deduplication window on recall. engage and recall share the same dedup guard — at most one engage or recall per response. A second call inside the window either wastes a slot or returns cached/empty results. Derive each engage query from the user’s current message, not from what you already searched.

Graceful degradation

If the control plane is unreachable, Kumiho MCP fails closed: engage and reflect return errors and the agent should continue without persistence rather than block. Wrap engage/reflect in error handling and log the failure to ~/.revka/logs/ for operator review. Captured content never carries credentials or secrets — only summaries and structured captures reach Kumiho; raw transcripts stay local.

---

Operator-side memory tools

When the Operator MCP is running, it exposes its own set of memory tools that mirror the sidecar tools above, so the operator itself (not just spawned sub-agents) can engage with and write to the graph. These are named without the kumiho_ prefix — memory_engage, memory_reflect, and so on — and most share the sidecar parameters. Two limits are applied operator-side from config:

• min_score is floored by [memory].min_relevance_score.
• limit is capped by [kumiho].memory_retrieval_limit (default 3).

Operator tool	Mirrors / purpose
memory_engage	Recall + context build → { context, results, source_krefs, count }.
memory_reflect	Store structured captures with provenance edges.
memory_retrieve	Semantic search.
memory_search	Structured search by context_filter, name_filter, kind_filter.
memory_fulltext	Full-text keyword search.
memory_get_item	Fetch an item by kref.
memory_resolve_kref	Resolve a kref to concrete identifiers.
memory_get_revision_by_tag	Get a revision by tag (default "published").
memory_store	Store a memory bundle with auto-stack.
memory_graph	Aggregate nodes + edges for force-graph visualization.

Caution

Do not use memory_store for skills — use the operator’s capture_skill tool, which stores SKILL.md as a revision artifact. See Skills system.

The rest of this page documents the sidecar kumiho_memory_* tools in detail. The operator-side equivalents accept the same core arguments unless noted.

---

kumiho_memory_engage

Check memory before responding. Combines recall and context-building into one call: it searches the graph, builds a context summary, and returns the source krefs you pass on to reflect.

Parameters

Parameter	Type	Default	Meaning
query	string	— (required)	Natural-language query derived from the user’s current message.
limit	number	5	Max results to return.
graph_augmented	boolean	false	Enable graph-augmented recall for indirect or chain-of-decision questions.
space_paths	string[]	—	Restrict the search to these space paths (e.g. ["CognitiveMemory/Skills"]).
memory_types	string[]	—	Filter by memory type (e.g. ["decision", "preference"]).
min_score	number (0–1)	0	Drop results scoring below this threshold before building context.
recall_mode	"full" | "summarized"	"summarized"	summarized returns title + summary only; full includes artifact content.

Returns

• context — a pre-built, prompt-injectable natural-language summary.
• results — the raw memories with metadata (titles, types, created_at).
• source_krefs — opaque identifiers to pass to the matching reflect.

Example

{
  "tool": "kumiho_memory_engage",
  "args": {
    "query": "transport choice for the operator-daemon channel",
    "graph_augmented": false,
    "limit": 5,
    "space_paths": ["Revka/AgentPool", "CognitiveMemory/Skills"]
  }
}

Skip engage when the answer is already visible in the conversation — engaging unnecessarily wastes tokens and pollutes the graph with low-signal queries.

---

kumiho_memory_reflect

Capture what matters after responding. A single call buffers the assistant response for session continuity, stores each structured capture as a graph memory, and (by default) runs edge discovery against existing memories. The agent’s own LLM identifies what to remember — no external API key is required.

Parameters

Parameter	Type	Default	Meaning
session_id	string	— (required)	Session identifier.
response	string	— (required)	The assistant response text to buffer.
captures	object[]	—	Structured facts to store (see below). Omit or pass [] for trivial exchanges — the response is still buffered.
source_krefs	string[]	—	Krefs from engage results — creates DERIVED_FROM edges to the source memories.
space_path	string	—	Default space path for captures without their own space_hint.
discover_edges	boolean	true	Run edge discovery on stored captures. Gracefully skipped if no server-side LLM is available.

Each entry in captures has these fields:

Field	Type	Meaning
type	string	— (required) Capture type: decision, preference, fact, correction, architecture, implementation, synthesis, reflection, summary, skill.
title	string	— (required) Short title using absolute dates (e.g. "Chose gRPC on Mar 27").
content	string	— (required) The content to store.
space_hint	string	Per-capture space override; wins over the top-level space_path.
tags	string[]	Classification tags.

Example

{
  "tool": "kumiho_memory_reflect",
  "args": {
    "session_id": "sess-2026-06-18-001",
    "response": "<your response text>",
    "captures": [
      {
        "type": "decision",
        "title": "Chose gRPC over REST on Jun 18",
        "content": "Picked gRPC for the operator <-> daemon channel for bidirectional streaming; REST was rejected as backpressure-blind.",
        "space_hint": "Revka/Plans/transport"
      }
    ],
    "source_krefs": ["kref://Revka/AgentPool/transport?r=4"],
    "discover_edges": true
  }
}

Tip

Always use absolute dates in capture titles ("on Jun 18", not "today"). Memories outlive their session, so relative time becomes meaningless on recall. When the user says “remember this,” “note that,” or similar, you must capture via reflect — never silently skip an explicit remember request.

---

kumiho_memory_recall

Search long-term memories by semantic query. Lighter than engage — it returns matching memories without buffering anything or building source krefs for a reflect round-trip. Shares the 5-second dedup guard with engage.

Parameters

Parameter	Type	Default	Meaning
query	string	— (required)	Natural-language search query.
limit	number	5	Max results to return.
graph_augmented	boolean	false	Multi-query reformulation + edge traversal to find connected memories vector search misses. Requires the KUMIHO_GRAPH_AUGMENTED_RECALL=1 env var.
space_paths	string[]	—	Restrict to these space paths.
memory_types	string[]	—	Filter by memory type.
min_score	number (0–1)	0	Drop results below this score.
recall_mode	"full" | "summarized"	"summarized"	full includes raw artifact content; summarized returns title + summary only.

Example

{
  "tool": "kumiho_memory_recall",
  "args": { "query": "gRPC decision", "limit": 5 }
}

---

kumiho_memory_retrieve

Retrieve memory using Google-like fuzzy search with relevance ranking and automatic typo tolerance. Falls back to bundle and pattern search when needed. Use this when you want forgiving keyword-style matching rather than the strict semantic recall of engage/recall.

Parameters

Parameter	Type	Default	Meaning
query	string	—	Natural-language query; supports fuzzy multi-word matching.
project	string	"CognitiveMemory"	Project name.
space_paths	string[]	—	Restrict to specific space paths.
memory_types	string[]	—	Filter by memory type (e.g. ["decision", "summary", "error"]).
keywords	string[]	—	Extra keywords to include in the search.
topics	string[]	—	Topic names to search for.
bundle_names	string[]	—	Search within specific bundles.
mode	string	"search"	search (fuzzy), first (oldest by date), or latest.
memory_item_kind	string	"conversation"	Item kind for memory entries.
include_revision_metadata	boolean	true	Also search revision metadata for deeper matching.
limit	number	5	Max results to return.

---

kumiho_fulltext_search

Full-text fuzzy search across items, ranked by relevance, with automatic typo tolerance. On higher Kumiho tiers it uses hybrid search (fulltext + vector similarity) when scanning revision metadata. Prefer this over a raw item search for natural-language queries.

Parameters

Parameter	Type	Default	Meaning
query	string	— (required)	Search terms (fuzzy; typos tolerated).
context	string	""	Restrict to a kref prefix (e.g. "CognitiveMemory/Skills"). Empty searches all.
kind	string	""	Exact kind match (e.g. "conversation", "bundle").
limit	number	20	Max results to return.
include_deprecated	boolean	false	Include soft-deleted items.
include_metadata	boolean	false	Include full item metadata in results.
include_revision_metadata	boolean	false	Also search revision tags/metadata (slower, more thorough).
include_artifact_metadata	boolean	false	Also search artifact names/metadata (slower).

---

kumiho_memory_store

Store a memory entry in one call — it creates or reuses the space, item, revision, artifact, bundle, and edges together. By default it searches for an existing similar item and stacks a new revision rather than creating a duplicate. Use this for direct, structured writes outside the engage/reflect flow.

Parameters (selected)

Parameter	Type	Default	Meaning
user_text	string	— (required)	The user-side text to store.
assistant_text	string	—	The assistant-side text.
title	string	—	Item title.
summary	string	—	Item summary.
memory_type	string	"summary"	summary, decision, fact, reflection, or error.
project	string	"CognitiveMemory"	Project name.
space_path	string	—	Full taxonomy space path.
space_hint	string	—	Short taxonomy hint when space_path is omitted.
bundle_name	string	—	Bundle name (defaults to the topic slug).
tags	string[]	—	Classification tags.
source_revision_krefs	string[]	—	Source krefs for provenance edges.
edge_type	string	"DERIVED_FROM"	Edge type for the provenance links.
stack_revisions	boolean	true	When true, find a similar item and stack a revision; false always creates a new item.
metadata	object	—	Extra metadata (string values only).

Caution

Do not use kumiho_memory_store to persist skills — skills are SKILL.md revision artifacts and must go through the operator’s capture_skill tool. See Skills system.

---

kumiho_memory_ingest

Ingest a user message into cognitive memory: it buffers the message in the working-memory store, recalls relevant long-term memories, and returns both working memory and long-term context. This is the message-level entry point for agents that drive a full ingest → respond → add_response loop rather than the engage/reflect pattern.

Parameters

Parameter	Type	Default	Meaning
user_id	string	— (required)	Stable user identifier.
message	string	— (required)	The user message text.
session_id	string	—	Existing session ID; auto-generated if omitted.
context	string	"personal"	Memory context (e.g. personal, work).
recall_limit	number	5	Max long-term memories to recall.
working_memory_limit	number	10	Max working-memory messages to return.

---

kumiho_memory_add_response

Add an assistant response to the session buffer in working memory. Call this after generating a response when you are using the ingest-based loop (it is the lighter counterpart to reflect, which both buffers and captures).

Parameters

Parameter	Type	Meaning
session_id	string	Session identifier from ingest.
response	string	The assistant response text.

---

kumiho_memory_store_execution

Store a tool or command execution result as a structured memory. Successful executions are stored as action type; failures as error type. Captured stdout/stderr become artifacts — useful for building an auditable trail of what an agent actually ran.

Parameters

Parameter	Type	Default	Meaning
task	string	— (required)	Description of what was executed (e.g. "git push origin main").
status	done | failed | error | blocked	"done"	Execution outcome.
exit_code	number	—	Process exit code (0 = success).
duration_ms	number	—	Execution duration in milliseconds.
stdout	string	—	Captured standard output.
stderr	string	—	Captured standard error.
tools	string[]	—	Tool names used.
topics	string[]	—	Classification topics.
space_hint	string	—	Space path hint for organisation.

---

kumiho_memory_consolidate

Consolidate a conversation session into long-term memory. The sidecar summarizes the conversation with an LLM, redacts PII, writes a local artifact, stores the summary to the graph, and clears the session’s working memory. Trigger this after roughly 20 exchanges or at session end; Revka’s daemon also runs it automatically on session end, but long-running agents should self-trigger periodically.

Parameters

Parameter	Type	Meaning
session_id	string	The session to consolidate.

{
  "tool": "kumiho_memory_consolidate",
  "args": { "session_id": "sess-2026-06-18-001" }
}

---

kumiho_memory_discover_edges

Discover and create edges from a newly stored memory to related existing memories. The server generates “implication queries” — future scenarios in which the memory would be relevant — and links to matching memories. Best run after consolidate or store.

Parameters

Parameter	Type	Default	Meaning
revision_kref	string	— (required)	The kref of the revision to discover edges for.
summary	string	— (required)	Summary text used to generate implication queries.
edge_type	string	"REFERENCED"	Edge type to create.
max_edges	number	3	Max edges to create.
max_queries	number	5	Max implication queries to generate.
min_score	number	0.3	Minimum similarity score for an edge candidate.
space_paths	string[]	—	Restrict the search; auto-derived from revision_kref if omitted.

---

kumiho_memory_dream_state

Run a Dream State consolidation cycle — Kumiho’s background “sleep” maintenance pass. It replays new events, assesses memories with an LLM, and applies deprecation, tagging, metadata enrichment, and relationship linking across a whole project. This is how a skill-type capture gets refined and how stale memories get retired over time. Use dry_run: true to preview without writing.

Parameters

Parameter	Type	Default	Meaning
project	string	"CognitiveMemory"	Kumiho project to process.
dry_run	boolean	false	Preview changes without applying them.
batch_size	number	20	Memories per LLM assessment batch.
max_deprecation_ratio	number (0.1–0.9)	0.5	Max fraction of memories deprecated per run.
allow_published_deprecation	boolean	false	Allow deprecating published items (use with caution).
provider	openai | anthropic | gemini	env	LLM provider; falls back to KUMIHO_LLM_PROVIDER.
model	string	env	Assessment model; falls back to KUMIHO_LLM_MODEL.
base_url	string	env	OpenAI-compatible base URL; falls back to KUMIHO_LLM_BASE_URL.
api_key	string	env	LLM API key; falls back to KUMIHO_LLM_API_KEY.

Caution

Dream State can deprecate memories. Run it with dry_run: true first to inspect the planned changes, and leave allow_published_deprecation at false unless you intend to retire published items. The max_deprecation_ratio cap is a safety brake against a single run pruning too much.

---

Maintenance and lookup tools

Beyond the core memory tools, the sidecar exposes the graph primitives you need to verify, inspect, and retire memories. These are most relevant when handling stale recalls (see the caution below).

Tool	Purpose
kumiho_resolve_kref	Resolve a kref URI to a concrete file location for an artifact or a revision’s default artifact.
kumiho_get_edges	Get a revision’s edges, filterable by direction (outgoing / incoming / both) and edge_type.
kumiho_get_revision_by_tag	Fetch a revision by tag (default "published").
kumiho_deprecate_item	Set an item’s deprecated status; deprecated items are hidden from searches. Use deprecated: false to restore.

Stale memories

A memory that names a file, function, or flag is a claim that the target existed when the memory was written. Before acting on a recalled memory, verify the target still exists. If it doesn’t, treat the memory as stale and either kumiho_deprecate_item it or store a correction-type capture that supersedes it.

For the full item / revision / edge / bundle / artifact CRUD surface and the kref format (kref://space/item?r=N), see Graph model: spaces, items & provenance and the Memory graph & Asset Browser API.

Related pages

• Memory overview — the runtime binding, config, categories, and decay.
• Kumiho setup — install the sidecar, configure [kumiho], supply tokens.
• Kumiho graph memory — the engage/reflect loop in practice.
• Graph model: spaces, items & provenance — spaces, krefs, edge types, trust.
• Operator MCP — the operator-side memory_* mirror tools.
• revka memory & estop — inspect and manage memory from the CLI.