Kumiho graph memory

Revka delegates all persistent, cross-session memory to Kumiho, a graph-native cognitive memory backend reached over the Model Context Protocol. A stateless LLM call forgets everything the moment it returns a response; Kumiho gives every agent cross-session continuity, graph-structured recall over typed provenance edges, and a shared substrate that multiple agents can read and write. This guide shows you how to wire an agent into that backend using the canonical two-reflex pattern — engage memory before responding, reflect after — and how to route, link, and consolidate what you store.

Use this page once the Kumiho MCP sidecar is installed and you want an agent to actually use it. For installing the sidecar and configuring the [kumiho] block, start with Kumiho setup and Install the Python MCP sidecars. For the underlying data model, see Graph model: spaces, items & provenance.

Note

Revka does not store memories locally. The runtime memory binding is a no-op — persistence is Kumiho’s job. The Kumiho control plane (FastAPI + Neo4j) is not installed on your machine; the local sidecar at ~/.revka/kumiho/run_kumiho_mcp.py is a client stub that talks to it. See Memory overview.

Prerequisites

1. The Kumiho MCP sidecar is installed and running. Installation puts a Python venv at ~/.revka/kumiho/venv/ and a runner shim at ~/.revka/kumiho/run_kumiho_mcp.py. See Install the Python MCP sidecars.

2. [kumiho] is configured in ~/.revka/config.toml with an api_url, an auth token, and a space_prefix.

   [kumiho]
   enabled = true
   mode = "cloud"                 # or "local_ce" for self-hosted Community Edition
   mcp_path = "~/.revka/kumiho/run_kumiho_mcp.py"
   api_url = "https://api.kumiho.cloud"
   space_prefix = "Revka"
   memory_project = "CognitiveMemory"
   harness_project = "Revka"
   memory_retrieval_limit = 3

   Auth is read from the environment: KUMIHO_AUTH_TOKEN (preferred, used by the local SDK bridge) takes precedence over KUMIHO_SERVICE_TOKEN (FastAPI header). revka onboard writes these to ~/.revka/.env.

3. The MCP tools are visible. Confirm the agent actually has memory tools by checking the tool catalog at http://127.0.0.1:42617/tools (or GET /api/tools) — the kumiho_memory_* tools should appear. If they don’t, check ~/.revka/logs/ for the Kumiho MCP stderr trail; the usual cause is a missing token or an unreachable api_url. Run revka doctor for a structured check of the Kumiho sidecar and backend health.

Caution

Advanced reflexes (engage, reflect, recall, consolidate, DreamState) require the kumiho_memory package, not just kumiho[mcp]. If revka doctor warns that kumiho_memory is missing, the runtime falls back to a lite bootstrap prompt. Fix it with:

~/.revka/kumiho/venv/bin/python -m pip install 'kumiho_memory>=0.5.0'

The two-reflex pattern

Almost every agent loop follows the same shape: engage before responding, reflect after. This is the canonical integration pattern.

Engage — before you respond

When the request touches anything that might have history, call kumiho_memory_engage exactly once. Derive the query from the user’s current message, not from what you remember searching earlier.

{
  "tool": "kumiho_memory_engage",
  "args": {
    "query": "<query derived from the user's message>",
    "graph_augmented": false,
    "limit": 5,
    "space_paths": ["Revka/AgentPool", "CognitiveMemory/Skills"]
  }
}

The call returns:

• context — a pre-built natural-language summary suitable for prompt injection.
• results — the raw memories with metadata (titles, types, created_at).
• source_krefs — opaque identifiers you pass to the matching reflect so new captures link back to what inspired them.

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

Note

The server enforces a 5-second deduplication window on engage. Call it at most once per turn; a second engage in the same window either wastes a slot or returns cached results.

Reflect — after you respond

After a substantive response, call kumiho_memory_reflect once with your response text and any structured captures you want preserved.

{
  "tool": "kumiho_memory_reflect",
  "args": {
    "session_id": "<session id>",
    "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/gateway"
      }
    ],
    "source_krefs": ["<from engage results>"],
    "discover_edges": true
  }
}

A single reflect call does three things:

1. Buffers the assistant response for session continuity, so the next engage in the same session sees it.
2. Stores each capture as a graph memory with DERIVED_FROM edges to the supplied source_krefs.
3. With discover_edges: true (the default), runs a server-side LLM pass to find non-obvious links to existing memories.

Reflect with captures: [] still buffers the response, so use it for trivial exchanges that need continuity but no durable memory.

Caution

When the user says “remember this”, “keep this in mind”, “note that”, or anything equivalent, you must capture it via reflect. Never silently skip an explicit remember request. Conversely, never put credentials, secrets, or sensitive payloads into capture content — only summaries and structured captures reach the control plane; raw transcripts stay local.

Capture types

Pick the type that matches what you’re storing. Type drives retrieval ranking and DreamState consolidation behavior.

Type	When to use	Example title
decision	A choice with a rationale that should bind future agents.	”Chose Axum over Actix on Mar 14”
preference	Stable user or operator preference.	”User wants tests run before commits”
fact	Verified fact about the world or the system.	”Daemon binds 0.0.0.0:42617 in network mode”
correction	Overrides a prior memory that proved wrong.	”Operator does NOT auto-restart on panic (correction)“
architecture	High-level structural choice or constraint.	”Operator/Rust split per ADR-005 on Apr 18”
implementation	Concrete how-it-works knowledge.	”Skill kref resolution flow on Apr 20”
synthesis	Aggregated insight derived from multiple sources.	”Q1 channel error patterns rolled up Apr 27”
reflection	Post-mortem or lesson learned.	”Postmortem: stash overlap on Apr 27”
summary	Compacted session or thread summary.	”Apr 27 docs-restructure session summary”
skill	A reusable procedure to be discovered later.	”creative-memory”

Tip

Always use absolute dates in capture titles ("on Jun 18", not "today"). Memories outlive their session, and relative time becomes meaningless on recall.

Provenance edges

Provenance is what separates a graph memory from a flat note. Memories are stored as items in hierarchical spaces, each with immutable revisions, and revisions carry typed edges. Revka uses these edge types:

Edge	Meaning	How it’s created
DERIVED_FROM	The new capture was derived from each source.	Implicit when you pass source_krefs to reflect.
DEPENDS_ON	B cannot start until A completes (plan ordering).	Set explicitly via kumiho_create_edge.
REFERENCED	Soft pointer; one memory mentions another.	Discovered, or explicit.
CONTAINS	Bundle/membership; a session contains its captures.	Discovered, or explicit.
CREATED_FROM	One item is a forked or transformed version of another.	Explicit.
BELONGS_TO	Ownership or scope; ties an artifact to a project, run, or agent.	Explicit.
HANDED_OFF_TO	Handoff between agents on the shared substrate.	Explicit, for multi-agent flows.

When in doubt, let discover_edges: true on reflect infer the edges. Create edges manually only when you have semantic information the LLM can’t infer — DEPENDS_ON ordering is the typical case. Items are addressed by kref in the form kref://space/item?r=N.

Space routing

Kumiho organizes memory into hierarchical spaces. Revka’s prefix is Revka/...; the CognitiveMemory/... tree is shared across Revka and its sibling agents. Route a read by passing space_paths to engage, and route a write by setting space_hint on the individual capture (per-capture targeting wins over any bulk default).

Space	Purpose
Revka/AgentPool	Per-agent state — identity, expertise, tone, allowed tools.
Revka/Plans/<project>	Plans the Operator decomposed for a project.
Revka/Sessions	Active and historical chat sessions.
Revka/Goals	Long-running goals an agent is working toward.
Revka/AgentTrust	Per-agent trust scores and recent outcome buffer.
Revka/ClawHub	Marketplace catalog state (skills, agents, workflows).
Revka/Teams	Team composition and delegation topology.
Revka/WorkflowRuns	Operator workflow run state and history.
Revka/Outcomes	Per-run outcomes feeding the trust score calculation.
CognitiveMemory/Skills	Shared skill library — cross-agent reusable procedures.

Skill discovery

Skills are reusable procedures stored in CognitiveMemory/Skills. Before improvising an unfamiliar procedure, engage that space first:

{
  "tool": "kumiho_memory_engage",
  "args": {
    "query": "creative output tracking",
    "space_paths": ["CognitiveMemory/Skills"]
  }
}

If a skill matches, follow it and cache it in working context for the rest of the session. If nothing matches and you improvised a procedure, capture it back as a skill-type memory with space_hint: "CognitiveMemory/Skills" so DreamState can refine it later.

Consolidation

After roughly 20 exchanges, or when a session ends, trigger consolidation:

{
  "tool": "kumiho_memory_consolidate",
  "args": { "session_id": "<session id>" }
}

This compacts session-buffered responses into durable summaries, runs edge discovery over the session’s new captures, and clears the session buffer. Revka’s daemon does this automatically on session end, but long-running agents should self-trigger periodically.

For a direct lookup outside the engage/reflect cycle, use kumiho_memory_recall:

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

DreamState

DreamState is Kumiho’s overnight maintenance pass, run via the kumiho_memory_dream_state tool. It deprecates stale memories, enriches metadata, adds tags, and links related memories so the graph stays coherent as it grows.

revka onboard offers to install DreamState as a nightly cron job when you select a Kumiho memory backend. You can pick the run time (midnight, 2 AM, 3 AM by default, 4 AM, or 6 AM). Add or change it later with revka cron:

revka cron list
revka cron add "0 3 * * *" --tz UTC "revka agent -m 'run DreamState memory consolidation'"

See revka cron for scheduling syntax and the Onboarding wizard for the install-time prompt.

Graceful degradation and pitfalls

• Silent degraded mode. 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. Log the error to ~/.revka/logs/ for operator review.
• Stale memories. A memory naming a file, function, or flag is a claim that the target existed when it was written. Verify the target still exists before acting on a recalled memory; if it’s gone, deprecate the item with kumiho_deprecate_item or update it.
• Kumiho is canonical. Do not rely on in-process state for cross-session knowledge. If something needs to be remembered across sessions, it must reach Kumiho.
• Transport fallback. Reads prefer a process-local SDK bridge over loopback for lower latency, falling back to hosted FastAPI automatically. Force the hosted path with REVKA_KUMIHO_SDK_BRIDGE=0.

Inspecting the graph

The dashboard renders Kumiho memory as a force-directed graph at /memory — filter by kind or space and inspect individual nodes. The backing endpoint is GET /api/memory/graph, which returns nodes, edges, and spaces in one payload; a read-only proxy at GET /api/kumiho/{*path} forwards any Kumiho GET endpoint. Both require gateway bearer auth. See Assets & memory explorer and Memory graph & Asset Browser API.

From the CLI, revka memory inspects the Kumiho-backed Memory space directly:

revka memory stats
revka memory list --category core --limit 20
revka memory get my-decision-key

See revka memory & estop for the full command set.

Verify your integration

A quick smoke test for any new Kumiho-aware agent path:

1. Tools visible. GET /api/tools returns at least kumiho_memory_engage, kumiho_memory_reflect, kumiho_memory_recall, and kumiho_memory_consolidate.

2. Engage round-trip. Call kumiho_memory_engage with a query that should hit something stored earlier; confirm results is non-empty.

3. Reflect with captures. Call kumiho_memory_reflect with one capture; verify the kref returns and the capture appears at /memory.

4. Edge formation. Confirm an engage → reflect pair produces a DERIVED_FROM edge from the new capture to the source krefs. Inspect with kumiho_get_edges or the /memory force-graph.

A failure here is almost always one of: missing auth token, unreachable control plane, the MCP sidecar not started, or the daemon’s [kumiho] config disagreeing with the running sidecar’s environment.

Next steps

Kumiho setup Install the sidecar, configure the [kumiho] block, and verify with revka doctor.

Graph model: spaces, items & provenance The Kumiho data model: spaces, items, revisions, krefs, and trust.

Kumiho memory tools Reference for every kumiho_memory_* MCP tool and its parameters.

Memory overview Why Kumiho is the canonical store and how the runtime binding works.