> ## Documentation Index
> Fetch the complete documentation index at: https://mx-6c34bcc6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# wattswarm knowledge — Export Decision Memory Bundles

> Reference for wattswarm knowledge export: export decision bundles by task type or task ID for inspection, reuse analysis, and offline review.

The `knowledge` command group lets you export the decision memory that WattSwarm accumulates in the local Knowledge Store as tasks are executed and finalized. Decision memory drives the kernel's reuse and seed bundle features — previous outputs, evidence, and reputation scores are injected into new task executions to reduce redundant exploration. Exporting a bundle lets you inspect, audit, and archive that memory outside the kernel.

***

## `knowledge export`

Export a decision knowledge bundle to a JSON file.

**Synopsis**

```bash theme={null}
wattswarm [--state-dir <path>] [--store <name>] knowledge export \
  { --task_type <type> | --task_id <id> } \
  --out <file>
```

**Flags**

| Flag                 | Description                                                                                       |
| -------------------- | ------------------------------------------------------------------------------------------------- |
| `--task_type <type>` | Export all knowledge records for this task type (for example, `swarm` or `topic_interpretation`). |
| `--task_id <id>`     | Export knowledge records for a single specific task ID.                                           |
| `--out <file>`       | Output path for the exported JSON bundle file (required).                                         |

You must pass exactly one of `--task_type` or `--task_id`. Passing both or neither returns an error.

**Description**

Reads the Knowledge Store tables from the local PostgreSQL database and writes a structured JSON bundle to the output file. The export includes all knowledge rows that match the filter, serialised as a single JSON object that you can inspect directly or archive.

**Examples**

```bash theme={null}
# Export all knowledge for the "swarm" task type
wattswarm --state-dir ./.ws-dev knowledge export \
  --task_type swarm \
  --out ./knowledge-swarm.json

# Export knowledge for a specific task
wattswarm --state-dir ./.ws-dev knowledge export \
  --task_id task-abc-001 \
  --out ./knowledge-task-abc-001.json
```

## What the exported bundle contains

The exported bundle is a JSON object with the following top-level sections:

**Decision records** — one record per finalized task. Each record captures:

* `task_id` and `task_type`
* `finalized_candidate_id` and the candidate output value
* `quorum_result_json` — the full quorum outcome snapshot at finalization
* `reason_details` — structured details for `FINALIZED`, `ERROR`, or `EXPIRY` terminal states
* Timestamps for creation, finalization, and expiry

**Evidence references** — `ArtifactRef` entries from proposers and verifiers attached to the winning candidate. Each ref includes `uri`, `digest`, `size_bytes`, `mime`, `created_at`, and `producer`.

**Reuse metrics** — per-task-type and per-task reuse statistics:

* `reuse_hit_rate_exact` — fraction of tasks where an exact knowledge match was found and reused
* `reuse_hit_rate_similar` — fraction of tasks where a similar (fuzzy) match was found and reused
* `reuse_candidate_accept_rate` — fraction of reused candidates that were ultimately accepted by quorum
* `exact_hit_count` and `similar_hit_count` per lookup row

**Reputation scores** — per-verifier reputation entries used for `REPUTATION_WEIGHTED` aggregation. Each entry includes the verifier's `node_id`, accumulated reputation units, and any downgrade events recorded against them.

## Example output structure

```json theme={null}
{
  "exported_at": 1718000000000,
  "filter": { "task_type": "swarm" },
  "decision_records": [
    {
      "task_id": "task-abc-001",
      "task_type": "swarm",
      "finalized_candidate_id": "cand-7a3f",
      "candidate_output": {
        "answer": "The proposal carries three material risks.",
        "confidence": 0.91
      },
      "quorum_result_json": {
        "votes": 3,
        "threshold": 2,
        "outcome": "COMMIT"
      },
      "reason_details": null,
      "created_at": 1717999900000,
      "finalized_at": 1718000000000
    }
  ],
  "evidence_refs": [
    {
      "task_id": "task-abc-001",
      "candidate_id": "cand-7a3f",
      "uri": "https://runtime.local/task-abc-001/exec-4f2a9c",
      "digest": "sha256:a3f1d8c2...",
      "size_bytes": 512,
      "mime": "application/json",
      "created_at": 1718000000000,
      "producer": "my-agent/gpt-4o"
    }
  ],
  "reuse_metrics": {
    "task_type": "swarm",
    "reuse_hit_rate_exact": 0.42,
    "reuse_hit_rate_similar": 0.17,
    "reuse_candidate_accept_rate": 0.88,
    "lookup_rows": [
      {
        "lookup_id": "lkp-001",
        "task_id": "task-abc-001",
        "exact_hit_count": 2,
        "similar_hit_count": 1
      }
    ]
  },
  "reputation_scores": [
    {
      "node_id": "node-verifier-a",
      "reputation_units": 1450,
      "downgrade_events": []
    }
  ]
}
```

<Tip>
  Export knowledge bundles before you rotate or reset a node to preserve the accumulated decision memory. You can later re-import bundles via the knowledge summary propagation path so other nodes in the swarm benefit from the history.
</Tip>