Kumiho setup

Kumiho is Revka’s canonical persistent memory store. The runtime never persists memory itself — it injects a Kumiho MCP sidecar into every non-internal agent, and that sidecar reads and writes a graph-native memory backend over the Model Context Protocol. This page covers installing the sidecar, the [kumiho] config block, choosing between hosted Kumiho Cloud and a self-hosted Community Edition (CE) backend, supplying auth tokens, and verifying the wiring with revka doctor.

Read Memory overview first if you want the conceptual picture of why memory lives in Kumiho rather than a local database. Once the sidecar is installed and reachable, the agent-side usage pattern is covered in Kumiho graph memory.

Note

The Kumiho MCP server you install here is a client stub, not the backend. The graph backend is either Kumiho Cloud (hosted) or a Community Edition server you run yourself. The sidecar discovers it over HTTP via [kumiho].api_url.

Install the Kumiho MCP sidecar

Revka expects the Kumiho launcher at ~/.revka/kumiho/run_kumiho_mcp.py, backed by a Python virtualenv at ~/.revka/kumiho/venv/. The launcher is a thin shim that runs python -m kumiho.mcp_server from that venv.

Prerequisites

• Python 3.11+ on PATH.
• Network access to PyPI — the installer runs pip install 'kumiho[mcp]>=0.9.20'. The [mcp] extra pulls in mcp>=1.0.0 and httpx>=0.27.0.
• A reachable Kumiho backend URL plus, for cloud, a service token (collected by revka onboard and written to ~/.revka/.env). Without them the MCP process still starts but degrades to stateless operation.

Automated install

With the revka binary

If revka is already on PATH:

revka install --sidecars-only

This is cross-platform and idempotent — safe to re-run. It never overwrites an existing config.toml, .env, or user-authored launcher. Useful flags:

Flag	Effect
--sidecars-only	Install the Python MCP sidecars only (no binary work).
--skip-kumiho	Skip the Kumiho sidecar (install Operator only).
--skip-operator	Skip the Operator sidecar (install Kumiho only).
--dry-run	Print the plan without changing anything.
--with-session-manager	Also install the Node.js live-execution session manager.
--python <path>	Use a specific Python interpreter.

From a source checkout

No revka binary required:

# POSIX (macOS / Linux / WSL)
./scripts/install-sidecars.sh

# Windows
scripts\install-sidecars.bat

The same logic runs automatically from ./install.sh and setup.bat. Disable it with ./install.sh --skip-sidecars.

Manual install

mkdir -p ~/.revka/kumiho
python3 -m venv ~/.revka/kumiho/venv
~/.revka/kumiho/venv/bin/pip install --upgrade pip
~/.revka/kumiho/venv/bin/pip install "kumiho[mcp]>=0.9.20"

cat > ~/.revka/kumiho/run_kumiho_mcp.py <<'PY'
#!/usr/bin/env python3
import os, pathlib, sys
HERE = pathlib.Path(__file__).resolve().parent
VENV_PY = HERE / "venv" / "bin" / "python3"
if not VENV_PY.exists():
    VENV_PY = HERE / "venv" / "Scripts" / "python.exe"
os.execv(str(VENV_PY), [str(VENV_PY), "-m", "kumiho.mcp_server", *sys.argv[1:]])
PY
chmod +x ~/.revka/kumiho/run_kumiho_mcp.py

Tip

The Kumiho sidecar ships two layers. The base kumiho[mcp] package gives you the bootstrap memory tools; the sibling kumiho_memory package adds the high-level reflexes (engage, reflect, recall, consolidate, dream_state). If kumiho_memory is missing the runtime silently falls back to a lite bootstrap prompt — see the doctor checks below for how to detect and fix this.

The Operator MCP sidecar (multi-agent workflow orchestration) is installed alongside Kumiho by the same scripts. For its details see Install the Python MCP sidecars.

The [kumiho] config block

[kumiho] lives in ~/.revka/config.toml and controls sidecar injection, which backend you talk to, and namespace scoping. A representative block:

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

Key	Type	Default	Meaning
enabled	bool	true	Inject the Kumiho MCP sidecar into non-internal agents. Disable for testing or air-gapped deployments — the agent then runs without persistent memory.
mode	string	"cloud"	Backend selector: "cloud" (hosted, token-based) or "local_ce" (self-hosted, tokenless, loopback-only).
mcp_path	string	~/.revka/kumiho/run_kumiho_mcp.py	Path to the launcher shim. Supports ~ expansion.
api_url	string	https://api.kumiho.cloud	Base URL for the Kumiho REST API. For local_ce, point at the loopback CE server (http://127.0.0.1:9190).
space_prefix	string	"Revka"	Prefix that scopes agent memories. Memories are stored under <space_prefix>/<context>.
memory_project	string	"CognitiveMemory"	Kumiho project for user memories, sessions, and compactions.
harness_project	string	"Revka"	Kumiho project for skills, operational data, and ClawHub installs.
memory_retrieval_limit	int	3	Maximum memories returned per recall/engage call.

The mcp_path is resolved in this order: the config value if non-empty, otherwise the default install location ~/.revka/kumiho/run_kumiho_mcp.py.

Note

[kumiho].mode is separate from [memory].backend. [memory].backend only toggles whether the Kumiho path is active (it accepts "kumiho" or "none"); [kumiho].mode selects which Kumiho you talk to. See Backend choices in the overview.

Cloud vs Community Edition

Kumiho Cloud (default)

Hosted, managed, multi-device, account/token-based. This is the recommended path and the default when you run revka onboard.

[kumiho]
enabled = true
mode = "cloud"
api_url = "https://api.kumiho.cloud"

Cloud requires a service token in the environment (see Auth tokens). During onboarding the memory step offers to create or sign in to a Kumiho Cloud account and generate a token, or to paste an existing one. The token is written to ~/.revka/.env as KUMIHO_SERVICE_TOKEN.

Community Edition (local_ce)

A self-hosted Community Edition server: tokenless, loopback-only (127.0.0.1), single-user, and free. CE has no control plane — auth is by network locality, not tokens.

[kumiho]
enabled = true
mode = "local_ce"
api_url = "http://127.0.0.1:9190"   # CE default port

When mode = "local_ce", Revka points the memory MCP at the loopback server via KUMIHO_LOCAL_SERVER_ENDPOINT (derived from api_url, defaulting to 127.0.0.1:9190) and does not forward KUMIHO_AUTH_TOKEN / KUMIHO_SERVICE_TOKEN. The CE auto-detect requires kumiho[mcp] >= 0.10.0.

What CE needs to run

Component	Address	Notes
CE server	127.0.0.1:9190	The Kumiho CE REST/gRPC endpoint.
Neo4j 5.x	127.0.0.1:7687 (Bolt), 7474 (HTTP)	Required — the graph store.
Redis	127.0.0.1:6379	Optional but recommended; enables event streams and the high-level memory write path.

The high-level memory layer (kumiho_memory) buffers sessions in Redis. Because CE has no control plane to discover an Upstash URL, Revka points it at the loopback Redis the CE onboarding provisions. Without a reachable Redis, reflect writes fail with “No credentials available for memory proxy.” Override the URL by exporting KUMIHO_UPSTASH_REDIS_URL (or UPSTASH_REDIS_URL); otherwise it defaults to redis://127.0.0.1:6379.

Setting it up

The CE flow is wizard-driven. revka onboard → memory step → Local Community Edition will, when Docker/Podman is available, offer to start kumiho-neo4j (and optionally kumiho-redis) containers, then hand off to the official Kumiho CE installer.

Caution

Kumiho CE is governed by the Kumiho CE EULA. The installer asks you to review it and type accept before the server runs. The wizard provisions Neo4j with a password you supply; reusing an existing kumiho-neo4j container keeps its original password.

If no container runtime is found, start Neo4j yourself before finishing the Kumiho setup wizard:

docker run -d \
  -p 127.0.0.1:7687:7687 -p 127.0.0.1:7474:7474 \
  -e NEO4J_AUTH=neo4j/<password> \
  neo4j:5

CE must stay loopback-only. Pointing api_url at a non-loopback host is outside the CE scope and would be unencrypted.

Auth tokens

Cloud Kumiho is authenticated with a dashboard-issued service token. Revka reads it from two environment variables, both written to the workspace ~/.revka/.env by revka onboard:

Variable	Read by	Notes
KUMIHO_SERVICE_TOKEN	Revka’s gateway / CLI code (FastAPI calls)	The value onboarding writes. Preferred.
KUMIHO_AUTH_TOKEN	The Kumiho Python SDK inside the sidecar	Fallback if KUMIHO_SERVICE_TOKEN is unset.

Precedence: KUMIHO_SERVICE_TOKEN wins over KUMIHO_AUTH_TOKEN. When forwarding to the spawned MCP, Revka uses the service token (the onboarded value) so it isn’t shadowed by a stale shell-level KUMIHO_AUTH_TOKEN from another account. The same resolved token is forwarded to the sidecar as KUMIHO_AUTH_TOKEN (what the SDK reads).

If neither variable is set, Revka falls back to the Kumiho CLI’s auth file at ~/.kumiho/kumiho_authentication.json (written by kumiho login), reading its control_plane_token and seeding KUMIHO_SERVICE_TOKEN from it when the token isn’t expired.

Caution

Paste exactly one Kumiho service token generated from Kumiho Cloud → Service Tokens. A Firebase/Auth JWT used as KUMIHO_SERVICE_TOKEN causes Kumiho 401 errors. CE mode is tokenless — leave these variables unset for local_ce.

Revka does not auto-load arbitrary shell .env files, but it does load the workspace ~/.revka/.env at startup so KUMIHO_SERVICE_TOKEN is available. You can also set KUMIHO_CONTROL_PLANE_URL to override the control-plane URL forwarded to the sidecar.

Verify with revka doctor

revka doctor runs structured diagnostics. Two categories cover Kumiho:

revka doctor

sidecars category — checks the Kumiho venv and packages:

• Resolves the venv from kumiho.mcp_path (<dir>/venv/bin/python, or venv\Scripts\python.exe on Windows).

• Warns if the venv Python is missing — fix by running scripts/install-sidecars.sh (or the .bat equivalent).

• Errors if kumiho is not importable (broken venv).

• Warns if kumiho_memory is missing — the runtime is on the lite bootstrap prompt and advanced reflexes are unavailable. The remediation it prints:

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

If kumiho.enabled = false, the sidecar check is skipped.

kumiho category — checks the backend:

• Cloud: reports backend: cloud (<api_url>) (a static note — a live probe would need a service token).
• Community Edition: probes the loopback server with GET /api/_live (asserting deployment_mode=self_hosted_ce) and GET /api/_health, reporting per-component readiness for Neo4j, Redis event-stream, and embeddings. If the server is unreachable it warns and points you to finish kumiho_server onboard (accept the EULA, start the server, ensure Neo4j is running), then re-run revka doctor.

Severity uses three levels: ok, warn, and error. You can also smoke-test the sidecar directly:

# Package import smoke test
~/.revka/kumiho/venv/bin/python3 -c 'import kumiho; print(kumiho.__version__)'

# Confirm the MCP tools loaded: open the gateway tools panel and look for kumiho_memory_*
revka gateway
# then visit http://127.0.0.1:42617/tools

See revka doctor, status & self-test for the full diagnostic surface.

Troubleshooting

Symptom	Fix
Log: Kumiho MCP script not found: ~/.revka/kumiho/run_kumiho_mcp.py	Run revka install --sidecars-only (or scripts/install-sidecars.sh).
ModuleNotFoundError: kumiho.mcp_server or ModuleNotFoundError: mcp	Reinstall with the [mcp] extra: ~/.revka/kumiho/venv/bin/pip install -U 'kumiho[mcp]'.
kumiho_memory_* tools absent from the tools panel	Missing token or unreachable backend. Confirm KUMIHO_SERVICE_TOKEN is in ~/.revka/.env; check ~/.revka/logs/ for the sidecar stderr.
Cloud 401 errors	The token is not a Kumiho service token (e.g. a Firebase JWT). Generate one from Kumiho Cloud → Service Tokens.
CE: reflect reports a save that never persisted	Redis unreachable — start kumiho-redis or set KUMIHO_UPSTASH_REDIS_URL.
CE: doctor says not reachable at 127.0.0.1:9190	Finish kumiho_server onboard, start the server, ensure Neo4j (7687) is running.
Backend silently degraded (no persistence)	api_url unreachable — verify [kumiho].api_url points at a live endpoint.

Related pages

Memory overview Why Kumiho is canonical, the NoneMemory binding, and backend choices.

Kumiho graph memory The engage/reflect two-reflex pattern for wiring an agent into Kumiho.

Install the Python MCP sidecars Install the Kumiho and Operator MCP sidecars together.

Config: gateway, memory, security & platform Full [kumiho] and [memory] config schema reference.

revka doctor, status & self-test The full diagnostic surface, including the sidecar and kumiho checks.

revka memory & estop Inspect and manage Kumiho-backed memory from the CLI.