using-terse

name	using-terse
description	Read, write, and query durable structured state in a TERSE store. Use whenever the user asks about TERSE, or when the session needs shared persistent memory / notes / project state that must survive across turns, sessions, or agents — not a scratchpad and not a general database.
metadata	{"openclaw":{"requires":{"bins":["terse-mcp"]}}}

Using TERSE

This plugin connects Claude to a TERSE state store through the terse-mcp server. TERSE is a hierarchical, human-readable state language designed for AI agents: structured enough to query and mutate by name, sparse enough to keep in-context. See the specification at https://github.com/terse-lang/terse.

When to reach for TERSE

Use it when the session needs durable, structured state that outlives this turn, this session, or this agent:

• persistent notes, decisions, or long-lived context you'll revisit later
• state shared across parallel agents or handed off between sessions
• project trackers, character sheets, world models, worklogs — anywhere hierarchy plus named attributes beats a flat file
• content the model itself will re-read and mutate by path

Do not use it as:

• a scratchpad for the current turn (just think, or use a temp file)
• a general database or blob store (it's a state language, not storage)
• a substitute for source code, config files, or issue trackers

If the user just wants notes on disk, a .md file is fine. TERSE earns its keep when the shape of the state — objects, attributes, references, ordering — is load-bearing.

What this plugin provides

The terse-mcp MCP server exposes two tools:

• terse_command — one call, two channels. declarations carries mutations (create, update, delete, move, rename — the full TERSE command syntax); queries carries one or more ? reads (paths, subtrees, WHERE / WHEN / CONTAINS / DEPTH filters). Both channels are optional multiline strings; at least one must be supplied. When both are present, declarations runs first and queries runs AFTER against the same store — the read observes the just-applied changes. Commands never return results — the queries channel is the only read path in this call. One call does everything — never split a write and its read-back into two calls.
• terse_info — introspection. Returns TERSE text (not JSON): the store's label / description / allow_namespace_create policy and the list of existing namespaces (each with size bytes + modified, or the absent flag if the store hasn't been created yet). Cheap; call when you need context about which store you're talking to.

Multiple stores via namespace

terse_command accepts an optional namespace argument — a lowercase token like proj-1 or agent_2 (regex ^[a-z0-9][a-z0-9_-]{0,63}$). Omitting it targets the default store. Each namespace is an independent store: reach for one when you want to keep per-project notes, per-agent scratch, or per-task worklogs from mixing. No cross-namespace queries — one call, one namespace.

A new namespace may require operator creation. Check terse_info and read allow_namespace_create. When it is false (the default), writing to a namespace that doesn't exist yet returns a hard error directing you to ask the operator to create it (via terse-mcp init --namespace <ns>) or to enable the policy. When it is true, the store is materialized on your first write (via the declarations channel). In either mode, a queries-only call against a namespace that doesn't exist errors — reads never materialize storage. The error text tells you which recovery applies.

When you're unsure of syntax

The server serves the spec as MCP resources — fetch them instead of guessing:

• terse://spec/quickstart — one-page cheat sheet (structure, attrs, references, directive tail, queries).
• terse://spec/full — the complete language guide.

The server also emits a primer through the FastMCP instructions= handshake on connect, so the basics are already in your context. Reach for the resources when a command hits a syntax error or you need a feature the primer didn't cover.

Conventions worth knowing

• Attrs are atomic. Kell(level: 5; class: fighter; wounded) — flags and identifiers, ;-separated (not commas).
• Structure by headings. # Top, ## Sub, ### Deeper — depth equals # count. Path shortcut: # A.B.C.
• References. @Path.Sub.key links between objects. Absent target emits a warning, not an error.
• Ordering is state. TERSE never sorts. Placement is meaningful.

Everything else — text blocks, directive tails, query modifiers, in-place mutations — is documented in the fetchable spec resources.