ClawQL plugin model — horizontal packages and MCP tools

Status: Phase 2 shipped (July 2026) — horizontal plugins register via onRegister; HITL and third-party API remain roadmap
Audience: Contributors, integrators, and third-party plugin authors
Related: Modularization implementation status · Effect + plugin plan · Plugin registry · Contributor Technical Specification §1.1

This document explains what it means for clawql-memory, clawql-documents, and clawql-automation to become plugins, how that differs from today’s layout, and how third-party plugins will work.

1. One-sentence summary

A plugin is how a package tells clawql-api: “When I’m enabled, register my MCP tools, wire my background workers, declare my provider dependencies, and participate in gateway hooks — and when I’m disabled, leave zero footprint.”

For memory, documents, and automation, yes — the plugin’s main visible job is registering the respective MCP tools (memory_ingest, memory_recall, ingest_external_knowledge, schedule, notify). Plugins also own lifecycle and optional pipeline hooks, not just tool names.

2. Today: plugins register via onRegister (Phase 2 shipped)

Extraction phases 1–9 moved business logic into workspace packages. Phase 2 (7.0.0+) moved MCP registration into Plugin.onRegister for Memory, Documents, Automation, Sandbox, and Ouroboros.

Transport-only concerns stay in src/ today:

• Zod schemas at server.tool(...) registration time
• wrapMcpToolHandler (OpenTelemetry)
• logMcpToolShape (payload shape logging, no secrets)
• CLAWQL_ENABLE_* gates in registerTools()

Remaining in tools.ts: HITL and any tools not yet moved to a plugin package.

3. Horizontal plugins (shipped)

At gateway startup, composition looks like:

createClawQLApi({
  plugins: [
    PanguardProxyPlugin, // kind: mcp-proxy — policy chokepoint, no new tools
    MemoryPlugin, // memory_* + pageindex_* when enabled
    DocumentsPlugin, // ingest_external_knowledge when enabled
    AutomationPlugin, // schedule + notify; starts schedule worker
    // future: LendingPlugin, YourCompanyPlugin, …
  ],
})

When CLAWQL_ENABLE_MEMORY=0 (or the Operator CRD omits the memory Layer), MemoryPlugin is not composed → listTools has no memory_ingest / memory_recall, and heavy vault/sql.js paths are not loaded for that process tier.

3.1 MCP tools each horizontal plugin registers

Core tools search, execute, cache, and audit stay in the gateway / core tier — not owned by these horizontal plugins.

3.2 onRegister contract (shipped)

Horizontal plugins implement Plugin.onRegister and register tools via ClawQLPluginRegistrationApi.registerMcpTool. Illustration:

const MemoryPlugin: Plugin = {
  id: 'clawql-memory',
  version: '1.0.0',
  onRegister: (api) =>
    Effect.gen(function* () {
      yield* api.registerMcpTool(
        'memory_ingest',
        memoryIngestSchema,
        handleMemoryIngest,
      )
      yield* api.registerMcpTool(
        'memory_recall',
        memoryRecallSchema,
        handleMemoryRecall,
      )
    }),
  onTeardown: (api) =>
    Effect.gen(function* () {
      // Close pools, flush workers if any
    }),
}

Handlers call into clawql-memory (runMemoryIngest, etc.). Transport wrappers (logMcpToolShape) may remain in a thin MCP adapter or move behind a small registration helper on ClawQLApi — that detail is implementation, not the model.

4. Plugins are more than tool registration

Tool registration is what most integrators see. The full plugin contract (see Contributor Technical Specification §1.1) also includes:

4.1 Panguard: plugin without tools

PanguardProxyPlugin is already shipped. It does not register MCP tools. It implements beforeCallTool so policy/ATR runs on every tool invocation. Same Plugin interface, different role — shows that “plugin” ≠ “adds tools” only.

5. Shipped vs target (honest matrix)

6. What extraction already did vs what “becoming plugins” finishes

Becoming plugins does not mean moving more files — it means owning MCP surface area and lifecycle when enabled, instead of centralizing registration in tools.ts.

7. Third-party and vertical plugins

The same model extends to verticals (clawql-lending, clawql-legal, …) and community extensions:

1. Publish an npm package (e.g. clawql-acme-widgets) depending on clawql-core + clawql-api — not on clawql-mcp transport internals.
2. Export a Plugin (and eventually an Effect Layer).
3. Implement onRegister to register your MCP tools and declare requiredSpecs if you need Postgres, Onyx, etc.
4. Document the Operator toggle or CLAWQL_ENABLE_* flag that includes or omits your Layer.

Until Layer composition is stable, in-repo extensions should continue via bundled providers (providers/) and MCP tools in the monorepo. Third-party registration without forking tools.ts is explicitly roadmap, not current API.

8. Request flow (target)

Agent (stdio / HTTP / gRPC)
        │
        ▼
  MCP transport (src/server*.ts, thin tools adapter)
        │
        ▼
  createClawQLApi({ plugins: [...] })
        │
        ├── Core: search / execute / cache / audit (always on)
        │
        ├── PanguardProxyPlugin.beforeCallTool (every tool)
        │
        └── If MemoryPlugin composed:
              memory_ingest / memory_recall → clawql-memory
            If DocumentsPlugin composed:
              ingest_external_knowledge → clawql-documents
            If AutomationPlugin composed:
              schedule / notify → clawql-automation

9. References