revka memory & estop

Two unrelated-but-adjacent command groups live on this page. revka memory lets you inspect and prune the entries Revka keeps in Kumiho graph memory — list them, look one up, see backend stats, and clear them. revka estop is the safety brake: it engages an emergency stop that restricts what the agent may do, shows the current stop state, and resumes capabilities once you are ready (optionally behind a one-time password).

Reach for revka memory when you want to audit or tidy what the agent remembers from the terminal. Reach for revka estop when something is going wrong and you need to halt the agent immediately — or when you want a standing, scoped restriction such as blocking outbound network or freezing a single tool.

revka memory

revka memory inspects and manages the memory entries Revka stores in Kumiho graph memory. It talks to the Kumiho REST API directly rather than to a local database, so it needs a Kumiho auth token in the environment (see Authentication below). For the agent-facing memory tools and the graph data model, see Kumiho memory tools and Memory overview.

revka memory stats
revka memory list
revka memory list --category core --limit 10
revka memory list --category conversation --session abc123 --offset 20
revka memory get my-decision-key
revka memory clear --category conversation --yes
revka memory clear --key my-decision --yes
revka memory clear --yes

Subcommand	Purpose
stats	Show the configured Kumiho endpoint, memory project, space list, and per-space item counts.
list	List entries, with optional category/session filters and pagination.
get <key>	Look up a single entry by its exact (slugified) key.
clear	Delete entries by key prefix, by category, or all entries.

Note

revka memory operates on the Memory space in Kumiho, which is separate from the session and capture spaces that the agent writes through kumiho_memory_reflect. To browse the full memory graph — agent captures, provenance edges, and revisions — use the dashboard’s Assets / Memory views or the read-only /api/kumiho/* proxy. See Memory graph & Asset Browser API.

Authentication and prerequisites

Because the CLI reads and writes Kumiho over REST, it requires a Kumiho service token in the environment:

• KUMIHO_SERVICE_TOKEN — the primary auth token, or
• KUMIHO_AUTH_TOKEN — accepted as a fallback.

revka onboard writes these into ~/.revka/.env, and KUMIHO_SERVICE_TOKEN is auto-injected from ~/.kumiho/kumiho_authentication.json if it is not already set. If no token is present, revka memory cannot reach the backend. For the Kumiho connection settings themselves (api_url, space_prefix, memory_project), see the [kumiho] config block.

List entries

revka memory list prints stored entries, newest-relevant first. Filter by category and session, and page through large result sets with --limit and --offset.

revka memory list                                            # first 50 entries
revka memory list --category core --limit 10                 # 10 core memories
revka memory list --category conversation --session abc123   # one session's chat memories
revka memory list --offset 50 --limit 50                     # second page of 50

Flag	Type	Default	Meaning
--category <NAME>	string	(all)	Filter by category: core, daily, conversation, or any custom label.
--session <ID>	string	(all)	Restrict to entries scoped to a session id.
--limit <N>	integer	50	Maximum number of entries to return.
--offset <N>	integer	0	Number of entries to skip — combine with --limit to paginate.

The category names map to Revka’s memory classification: core holds evergreen long-term facts, daily holds session logs, conversation holds in-context exchanges, and any other string is a custom label. Core memories never decay; daily and conversation memories lose relevance over time. The conceptual model is covered in Memory overview.

Get one entry

revka memory get <key> retrieves a single entry by its key. The lookup requires the full slugified key — it is an exact match, not a prefix match:

revka memory get my-decision-key

The output is the full entry, including its content, category, creation timestamp, session scope, and kref.

Show backend stats

revka memory stats reports the health and shape of the memory backend rather than individual entries:

revka memory stats

It shows the Kumiho endpoint Revka is talking to, the memory project, the list of spaces, and the item count in each space — a quick way to confirm the CLI is authenticated and pointed at the right backend.

Clear entries

revka memory clear deletes entries. Scope the deletion with --key (prefix) or --category; with neither flag it clears everything. Deletion is irreversible, so the command confirms interactively unless you pass --yes.

revka memory clear --key my-decision --yes        # delete by key prefix
revka memory clear --category conversation --yes  # delete all conversation entries
revka memory clear --yes                          # delete ALL entries

Flag	Meaning
--key <PREFIX>	Delete entries whose slugified key starts with this prefix.
--category <NAME>	Delete all entries of the given category.
--yes	Skip the interactive confirmation prompt.

Caution

revka memory clear with no --key and no --category wipes every entry in the Memory space. There is no undo, and --yes removes the only safety prompt — script it carefully.

revka estop

revka estop is Revka’s emergency stop. It writes a persisted restriction that the agent honors immediately and across daemon restarts, so you can halt or constrain agent behavior without stopping the gateway. There are four stop levels that compose additively, a status subcommand to inspect the current state, and a resume subcommand to lift restrictions — optionally gated by a one-time password.

revka estop                                              # engage kill-all (default level)
revka estop --level network-kill                        # block all outbound network
revka estop --level domain-block --domain "*.chase.com" # block specific domains
revka estop --level tool-freeze --tool shell --tool browser
revka estop status                                       # show current estop state
revka estop resume                                       # resume kill-all
revka estop resume --network                             # resume the network kill
revka estop resume --domain "*.chase.com"               # unblock a domain
revka estop resume --tool shell                         # unfreeze a tool
revka estop resume --otp 123456                          # resume with an OTP code

Caution

Emergency stop must be enabled in config. Set enabled = true under [security.estop] in ~/.revka/config.toml (it is false by default). The full security treatment lives in OTP gating & emergency stop.

Stop levels

The --level flag selects which capability to restrict. The default level — used when you run a bare revka estop — is kill-all.

Level	Effect	Extra flag
kill-all	Halts all agent execution. The strongest stop.	—
network-kill	Blocks all outbound network access.	—
domain-block	Blocks specific domains (glob patterns supported).	--domain <PATTERN> (repeatable)
tool-freeze	Freezes specific tools so the agent cannot call them.	--tool <NAME> (repeatable)

revka estop --level kill-all                              # or just: revka estop
revka estop --level network-kill
revka estop --level domain-block --domain "*.chase.com" --domain "*.paypal.com"
revka estop --level tool-freeze --tool shell --tool browser

• --domain <PATTERN> — required for domain-block, repeatable. Patterns support wildcards (e.g. *.bank.com) and are validated when you engage the stop.
• --tool <NAME> — required for tool-freeze, repeatable. Tool names must contain only alphanumeric characters, -, and _.

The levels are additive: blocked domains and frozen tools accumulate, and engaging one level does not clear another. Use resume to remove a specific restriction.

Caution

The estop state is fail-closed. State is persisted to a JSON file (~/.revka/estop-state.json by default), and if that file is unreadable or corrupt, Revka defaults to kill_all = true. A kill-all stop blocks even read operations through the gateway — expect a fully frozen agent until you resume.

Inspect the current state

revka estop status prints whatever is currently engaged — the kill-all and network-kill flags, the list of blocked domains, the list of frozen tools, and when the state was last updated.

revka estop status

This reads the same persisted state file the agent enforces against, so it is the authoritative view of what the agent can and cannot do right now.

Resume capabilities

revka estop resume lifts restrictions. With no selector it resumes the kill-all stop; otherwise it targets exactly one restriction.

revka estop resume                       # clear kill-all
revka estop resume --network             # clear the network kill
revka estop resume --domain "*.chase.com"  # unblock a single domain
revka estop resume --tool shell          # unfreeze a single tool

Selector	Resumes
(none)	The kill-all stop.
--network	The network-kill stop.
--domain <PATTERN>	A blocked domain (repeatable).
--tool <NAME>	A frozen tool (repeatable).
--otp <CODE>	Supplies the TOTP code when resume is OTP-gated (combine with one of the above).

Note

Only one of --network, --domain, or --tool may be passed to a single resume call. Pick the one restriction you want to lift; run resume again for another.

Resuming with an OTP

When require_otp_to_resume = true under [security.estop] (the default when estop is enabled), resume requires a valid TOTP code. Supply it inline with --otp, or omit the flag and Revka prompts for it interactively.

revka estop resume --otp 123456            # resume kill-all with an OTP
revka estop resume --network --otp 123456  # resume network kill with an OTP
revka estop resume                         # omit --otp to be prompted

The TOTP secret is generated on first initialization and the otpauth:// enrollment URI is printed once at that time — scan it into any authenticator app. Validation tolerates ±1 time step for clock drift. OTP gating is shared with the wider OTP subsystem; see OTP gating & emergency stop for enrollment, regeneration, and gated-action configuration.

Engage-then-resume in practice

1. Enable estop in config (once). Edit ~/.revka/config.toml:

   [security.estop]
   enabled = true
   state_file = "~/.revka/estop-state.json"
   require_otp_to_resume = true

2. Engage a stop when you need it. For a hard halt:

   revka estop

   Or a scoped restriction, e.g. freeze the shell tool:

   revka estop --level tool-freeze --tool shell

3. Confirm what is engaged.

   revka estop status

4. Resume when it is safe, supplying an OTP if required:

   revka estop resume --otp 123456

Related pages

OTP gating & emergency stop The security model behind estop levels, fail-closed state, and TOTP-gated resume.

Memory overview How Revka uses Kumiho graph memory, categories, and time decay.

Kumiho memory tools The agent-facing kumiho_memory_* tools that read and write the graph.

Memory graph & Asset Browser API Browse the full memory graph over HTTP from the gateway.