# openclaw-hawkins — full documentation

> Concatenated single-file content of every page on hawkins.parijatmukherjee.com.
> For RAG ingestion, LLM crawling, or offline reading.

---

## What is it

openclaw-hawkins is an OpenClaw plugin. It provides:

1. **VINES** (Versatile Integration for Networked Execution & State) — durable
   orchestration state in MariaDB, with crash-safe Linear-backed recovery.
2. **VECNA** (Versatile Entity for Contextual Network Awareness) — decay-aware
   shared agent memory across the swarm.
3. **12 typed tools** registered with the OpenClaw runtime so any agent in the
   gateway can call them by name.
4. **A one-command setup** that provisions schemas, creates 6 specialist
   agents, and installs the Nexus orchestration protocol doc.

It pairs with OpenClaw's multi-agent gateway. The plugin ships as
`openclaw-hawkins` on npm and ClawHub, MIT licensed.

---

## Architecture — the Hive-Mind hierarchy

Three layers, one swarm:

### Layer 1 — The Nexus (orchestrator)

The only agent the operator talks to. It listens, plans, and dispatches
sub-tasks to the Tendrils. It explicitly does NOT execute domain work itself,
does NOT share workspace/memory with the Tendrils, and does NOT decide
specialist tooling.

The Nexus reads its protocol from three files in its workspace:
- `AGENTS.md` — orchestration rules
- `IDENTITY.md` — persona
- `HAWKINS_PROTOCOL.md` — plugin tool vocabulary (auto-installed by `openclaw hawkins setup`)

### Layer 2 — The Tendrils (6 isolated specialists)

Each Tendril is a top-level OpenClaw agent (`openclaw agents add <id>`):

- `system-agent` — OS, packages, systemd, disk
- `code-agent` — read/write source, run tests, navigate repos
- `research-agent` — web search, docs lookup, comparison
- `data-agent` — DB queries, analytics
- `comm-agent` — email, chat, notifications
- `vision-agent` — screenshot/image analysis (vision model)

### Layer 3 — The Hive (durable memory)

MariaDB-backed persistence with two tables:

- `orchestration_ledger` — owned by VINES. One row per request. Tracks state,
  active Tendril, Linear parent.
- `vecna_hive` — owned by VECNA. One row per knowledge fragment. Tracks topic,
  source agent, importance, optional ticket reference.

Same database, separate concerns, separate specs.

---

## The Pulse — five named phases

When the Nexus decides a request isn't trivial, it enters The Pulse:

1. **Sensitivity Check** — `vines_triage`. Fires only when >30s work or >2
   specialist domains. Trivial requests skip the rest.
2. **Anchoring** — Create Linear parent ticket + VINES orchestration row
   via `vines_attach_linear_parent`. Recovery anchors for crash-safety.
3. **Deep Seeking** — Optional research-agent dispatch.
4. **The Connection** — Loop dispatch to each Tendril. Sub-ticket per
   sub-task, isolated execution, structured reply.
5. **Consolidation** — Synthesize replies into one operator-facing answer.
   `vines_set_state(success)` + Linear ticket Done; or
   `vines_set_state(failed)` + Linear ticket Canceled on abort.

---

## Install — two commands

```bash
openclaw plugins install clawhub:openclaw-hawkins
openclaw hawkins setup
```

`openclaw hawkins setup` is idempotent. It applies both schemas, creates the
six specialist agents from templates (skipping any that exist), and installs
`~/.openclaw/workspace/HAWKINS_PROTOCOL.md` (skipping if already present).

Verify with:

```bash
openclaw plugins inspect openclaw-hawkins --runtime --json | jq '.plugin | {status, toolNames}'
openclaw agent --agent system-agent --json --timeout 90 \
  --message "Call vecna_healthz and return only the JSON."
```

Expected: `status: "loaded"`, all 12 tool names listed, agent returns
`{ ok: true, db: "up" }`.

---

## Configuration

### Non-secret config — via `openclaw config`

```bash
openclaw config set plugins.entries.openclaw-hawkins.config.mariadb.url  "mariadb://your-host:3306/hawkins"
openclaw config set plugins.entries.openclaw-hawkins.config.mariadb.user "hawkins"
openclaw config set plugins.entries.openclaw-hawkins.config.mariadb.ssl  "insecure"
```

### Secrets — gateway env only

The plugin's `configSchema` deliberately rejects `mariadb.password` and
`linear.apiKey`. Wire them via a 0600 systemd EnvironmentFile:

```bash
mkdir -p ~/.openclaw/secrets && chmod 700 ~/.openclaw/secrets
( umask 077 && printf 'MARIADB_PASSWORD=%s\nLINEAR_API_KEY=%s\n' \
  "$MARIADB_PASSWORD" "$LINEAR_API_KEY" > ~/.openclaw/secrets/hawkins.env )
mkdir -p ~/.config/systemd/user/openclaw-gateway.service.d
cat > ~/.config/systemd/user/openclaw-gateway.service.d/hawkins.conf <<'EOF'
[Service]
EnvironmentFile=%h/.openclaw/secrets/hawkins.env
EOF
systemctl --user daemon-reload
openclaw gateway restart
```

### Env-var matrix

Required: `MARIADB_URL`, `MARIADB_USER`, `MARIADB_PASSWORD`.

Optional: `MARIADB_SSL` (default `preferred`), `LINEAR_API_KEY`,
`VECNA_PORT` (default `8765`), `VECNA_HOST` (default `127.0.0.1`),
`VECNA_AUTH_TOKEN` (required in production), `VECNA_DEDUP_WINDOW_MIN`
(default `5`), `VECNA_URL` (default `http://127.0.0.1:8765`).

---

## The 12 tools (full reference)

### VINES — durable orchestration state

**`vines_triage`**
- Inputs: `{ objectiveSummary, linearParentId?, orchestrationId? }`
- Returns: `{ orchestrationId, state: "init", row }`
- When: Start of any non-trivial operator request.

**`vines_start`**
- Inputs: `{ orchestrationId, lastAgentActive? }`
- Returns: `{ ok, state: "executing", orchestrationId }`
- When: Convenience shortcut for the most common transition.

**`vines_set_state`**
- Inputs: `{ orchestrationId, state, lastAgentActive? }`
- Returns: `{ ok, orchestrationId, state }`
- When: After every meaningful transition.

**`vines_attach_linear_parent`**
- Inputs: `{ orchestrationId, linearParentId }`
- Returns: `{ ok, orchestrationId, linearParentId }`
- When: Right after `vines_triage`, once the Linear parent exists. Idempotent.

**`vines_recover`**
- Inputs: `{ markOrphanedAsFailed?, doneStateNames? }`
- Returns: `{ summary, items }`
- When: Once at session start to detect unfinished orchestrations.

**`vines_status`**
- Inputs: `{ orchestrationId }`
- Returns: `{ row }` or null.
- When: "What state am I in?" debugging.

### VECNA — shared agent memory

**`vecna_connect`**
- Inputs: `{ topic, content, sourceAgent, importance?, linearRef?, subTopic? }`
- Returns: `{ fragment, deduplicated }`
- When: A specialist returns a non-trivial result worth persisting.

**`vecna_recall`**
- Inputs: `{ topic, ticket?, limit?, format? }`
- Returns: `{ fragments }` or pre-summarised string (`format="context"`).
- When: Before dispatching a sub-task — recall prior context.

**`vecna_evolve`**
- Inputs: `{ fragmentId, content, importance?, reason? }`
- Returns: `{ deprecated, replacement }`
- When: When you discover a memory is wrong (outdated API, deprecated knob).

**`vecna_search`**
- Inputs: `{ query, limit? }`
- Returns: `{ fragments }`
- When: Full-text fallback when no clear topic is known.

**`vecna_fragment`**
- Inputs: `{ fragmentId }`
- Returns: `{ fragment }` or null.
- When: Rare — lookup by id from a prior recall.

**`vecna_healthz`**
- Inputs: `{}`
- Returns: `{ ok, db: "up"|"down" }`
- When: Smoke check at session start.

---

## Security model — design properties

1. **Shared agent memory (VECNA).** All agents read/write a single MariaDB
   table. Recall gated by topic match + dedup window + decay penalty. Set
   `VECNA_AUTH_TOKEN` in production.
2. **Inter-agent dispatch (OpenClaw pattern).** Tool inputs and recalled
   context land in the receiving agent's prompt → its model provider. Never
   pass secrets in tool arguments.
3. **Linear API scope.** The configured Linear key carries whatever scope
   its issuer granted. Use an OAuth app token scoped to a single team for
   production.
4. **Plugin tools are gateway-wide.** The 12 tools register through OpenClaw's
   standard model. Restrict per-agent allowlists in `openclaw.json`.
5. **`MARIADB_SSL=insecure` skips cert verification.** Operator-gated, for
   self-signed cloud certs only.
6. **Setup runs local effects.** `openclaw hawkins setup` writes schemas
   and creates agent workspaces. Idempotent; all effects listed in the
   post-install banner.

Full text: `SECURITY.md` on GitHub.

---

## Crash + restart recovery

After a host crash or gateway restart, the Nexus runs:

```
1. vecna_healthz   → db must be up
2. vines_recover   → check summary.resumable; resume from
                     item.lastCompletedChild → item.nextPendingChild
```

The scanner distinguishes three states per unfinished row:

- `lookupStatus: "ok"` — resumable.
- `lookupStatus: "missing"` — Linear definitively returns no parent. Safe to mark failed.
- `lookupStatus: "lookup_failed"` — transient Linear API error. Do NOT mark failed.

This distinction prevents a flaky Linear API from destroying live state.

---

## Troubleshooting

- **"the plugin tools aren't directly accessible yet"** — Nexus didn't re-read
  its workspace. Confirm `~/.openclaw/workspace/HAWKINS_PROTOCOL.md` exists
  and restart the gateway.
- **`vecna_healthz` returns `db: down`** — MariaDB unreachable. Check
  `MARIADB_URL`, run `nc -vz <host> <port>`, check firewall.
- **Linear tickets not created** — `~/.openclaw/linear.json` missing OR
  `LINEAR_API_KEY` not in gateway env OR `linear-ticket` CLI not on PATH.
- **`Token required - not valid tokenless upload` (ClawHub publish)** — CI
  workflow missing `CLAWHUB_TOKEN` repo secret or `CLAWHUB_CONFIG_PATH`
  not pointing at `{registry, token}` config file.

---

## Repository

- GitHub: https://github.com/parijatmukherjee/openclaw-hawkins
- npm: https://www.npmjs.com/package/openclaw-hawkins
- ClawHub: https://clawhub.ai/plugins/openclaw-hawkins
- License: MIT
- Author: Parijat Mukherjee