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

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

# 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

{
  "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": []
    }
  ]
}

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.