# openclaw-hawkins

> OpenClaw plugin: durable orchestration state (VINES) + decay-aware shared agent memory (VECNA) for multi-agent swarms. 12 typed tools, MariaDB-backed, optional Linear oversight. Stranger Things–themed. MIT licensed.

The plugin ships as `openclaw-hawkins` on npm and ClawHub. It registers 12 typed tools with the OpenClaw runtime, provides a single CLI command (`openclaw hawkins setup`) that provisions schemas + 6 specialist agents + the Nexus protocol doc, and supports both human and AI-agent install paths.

## Install (recommended)

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

## Docs

- [Install guide for humans](https://hawkins.parijatmukherjee.com/install/): Five-command setup (plugin install → configure → secrets → provision → verify), plus AI-agent and from-source paths linked at the bottom of the page.
- [Install guide for LLM agents](https://hawkins.parijatmukherjee.com/install/llm/): Phase 0 host probe, 1Password-first credential resolution, autonomous-execution recipe.
- [Concepts](https://hawkins.parijatmukherjee.com/concepts/): The Nexus / Tendrils / Hive hierarchy, The Pulse protocol (5 phases), VINES and VECNA design.
- [The 12 tools](https://hawkins.parijatmukherjee.com/tools/): Full reference for every plugin tool with inputs, outputs, and when-to-call guidance.
- [Operator reference](https://hawkins.parijatmukherjee.com/docs/): Env vars, security model, recovery protocol, manifest, troubleshooting.

## Canonical sources (GitHub)

- [README.md](https://github.com/parijatmukherjee/openclaw-hawkins/blob/main/README.md): Top-level overview + install paths.
- [vines/spec.md](https://github.com/parijatmukherjee/openclaw-hawkins/blob/main/vines/spec.md): VINES durable-orchestration contract.
- [vecna/spec.md](https://github.com/parijatmukherjee/openclaw-hawkins/blob/main/vecna/spec.md): VECNA shared-memory contract.
- [SECURITY.md](https://github.com/parijatmukherjee/openclaw-hawkins/blob/main/SECURITY.md): Threat model + design properties.
- [SKILL.md](https://github.com/parijatmukherjee/openclaw-hawkins/blob/main/SKILL.md): OpenClaw skill manifest for autonomous install.
- [orchestrator/HAWKINS_PROTOCOL.md](https://github.com/parijatmukherjee/openclaw-hawkins/blob/main/orchestrator/HAWKINS_PROTOCOL.md): Plugin-aware Nexus protocol.

## The 12 tools (one-liners)

- `vines_triage` — Open a durable orchestration row (state=init). Returns the orchestrationId.
- `vines_start` — Transition to state=executing.
- `vines_set_state` — Set arbitrary lifecycle state.
- `vines_attach_linear_parent` — Bind a Linear parent ticket to an orchestration.
- `vines_recover` — Scan unfinished orchestrations, cross-reference Linear for resume points.
- `vines_status` — Fetch one ledger row.
- `vecna_connect` — Write a knowledge fragment with dedup-window collapse.
- `vecna_recall` — Topic-scoped recall with decay-aware ranking.
- `vecna_evolve` — Atomically deprecate + replace a stale fragment.
- `vecna_search` — Full-text search across non-deprecated fragments.
- `vecna_fragment` — Fetch one fragment by id.
- `vecna_healthz` — Liveness probe.

## 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

## Full content

A concatenated single-file version of every documentation page is available at:
https://hawkins.parijatmukherjee.com/llms-full.txt