The 12 typed tools
Every operation on VINES and VECNA is a first-class OpenClaw tool. Any agent in your gateway can call them by name. Inputs are validated by TypeBox schemas at the runtime boundary — handlers receive already-checked payloads.
6 VINES tools
VINES owns state — one durable row per operator request, with crash-safe recovery via Linear cross-reference.
vines_triage VINES: triage
Open a new durable orchestration row in state=init. Returns the orchestrationId used by every other VINES tool.
Inputs: { objectiveSummary, linearParentId?, orchestrationId? }
Returns: { orchestrationId, state: 'init', row }
When to call: Start of any non-trivial operator request (>30s of work, or >1 specialist).
vines_start VINES: start executing
Transition a VINES orchestration to state=executing. Records the active Tendril if provided.
Inputs: { orchestrationId, lastAgentActive? }
Returns: { ok, state: 'executing', orchestrationId }
When to call: Convenience shortcut for the most common transition. Equivalent to vines_set_state(executing).
vines_set_state VINES: set state
Set the VINES orchestration to any lifecycle state (init | planning | executing | success | failed).
Inputs: { orchestrationId, state, lastAgentActive? }
Returns: { ok, orchestrationId, state }
When to call: After every meaningful transition: planning → executing → success/failed.
vines_attach_linear_parent VINES: attach Linear parent
Attach (or update) the Linear parent ticket id on an existing orchestration. Enables Linear-anchored recovery.
Inputs: { orchestrationId, linearParentId }
Returns: { ok, orchestrationId, linearParentId }
When to call: Right after vines_triage, once the Linear parent ticket has been created. Idempotent.
vines_recover VINES: recover
Scan unfinished orchestrations and cross-reference Linear to identify resumable vs orphaned vs lookup-failed rows. Optionally marks definitively orphaned rows as failed.
Inputs: { markOrphanedAsFailed?, doneStateNames? }
Returns: { summary, items }
When to call: Run once at session start to detect unfinished orchestrations from a previous crash/restart.
vines_status VINES: status
Fetch the current ledger row for one VINES orchestration. Returns null if not found.
Inputs: { orchestrationId }
Returns: { row }
When to call: Debugging: 'what state am I in?' for a specific orchestration.
6 VECNA tools
VECNA owns memory — cross-orchestration knowledge fragments ranked by ticket-affinity, importance, and recency. Decay-aware.
vecna_connect VECNA: connect
Write a knowledge fragment to the VECNA Hive. Repeated identical high-importance fragments inside the dedup window collapse into the existing row.
Inputs: { topic, content, sourceAgent, importance?, linearRef?, subTopic? }
Returns: { fragment, deduplicated }
When to call: When a specialist returns a non-trivial result, persist the lesson so the next orchestration benefits.
vecna_recall VECNA: recall
Recall non-deprecated fragments for a topic, ranked by ticket-affinity → importance → recency, with a decay penalty for stale entries.
Inputs: { topic, ticket?, limit?, format? }
Returns: { fragments } or pre-summarised string (format='context')
When to call: Before dispatching a sub-task. Use format='context' for direct prompt injection.
vecna_evolve VECNA: evolve
Deprecate an existing fragment and write a corrected replacement on the same topic atomically.
Inputs: { fragmentId, content, importance?, reason? }
Returns: { deprecated, replacement }
When to call: When you discover an existing memory is wrong (outdated API version, deprecated config knob).
vecna_search VECNA: search
Full-text search across non-deprecated fragments via MATCH/AGAINST. Useful when no clear topic is known.
Inputs: { query, limit? }
Returns: { fragments }
When to call: Fallback when a specific topic isn't known but you have a keyword.
vecna_fragment VECNA: get fragment
Fetch one VECNA fragment by id. Returns null if not found.
Inputs: { fragmentId }
Returns: { fragment }
When to call: Rare — only when you have a specific fragment id from a prior recall.
vecna_healthz VECNA: healthz
Liveness probe for the VECNA Hive. Pings MariaDB and returns { ok, db }.
Inputs: {}
Returns: { ok, db: 'up'|'down' }
When to call: Smoke check at session start to confirm the Hive is reachable.
Inspecting the surface from openclaw
Once the plugin is loaded, the runtime exposes the full tool catalog with parameter schemas:
openclaw plugins inspect openclaw-hawkins --runtime --json \
| jq '.plugin.toolNames'openclaw agent --agent system-agent --json --timeout 60 \
--message "Call vecna_healthz and return only the JSON."