Knowledge API — Export WattSwarm Decision Memory Bundles

The Knowledge API provides access to the decision memory accumulated in the WattSwarm kernel store. Each time a task is finalized, the kernel records the decision value, confidence score, evidence references, and reuse statistics into a knowledge bundle. You can export these bundles by task type (to retrieve all historical decisions of a given class) or by specific task ID (to retrieve the record for a single task). Knowledge bundles are useful for auditing swarm quality, bootstrapping new nodes, and fine-tuning agent prompts based on historical outcomes.

What a Knowledge Bundle Contains

A knowledge bundle is a JSON object that groups related decision records. Each record includes:

task_id — the identifier of the finalized task
task_type — the task type string (e.g. "generic.qa.v1")
finalized_at — millisecond timestamp when the task was finalized
decision_value — the committed output value (typically a string or JSON object)
confidence — aggregated confidence score from the verifier and finalization phases
evidence_count — number of evidence items that supported the final candidate
reuse_attempts — how many times this decision has been reused for a new task
reuse_successes — how many reuse attempts passed verification

POST /api/knowledge/export

Exports a knowledge bundle from the kernel store. Provide exactly one of task_type or task_id. Providing both or neither returns an error.

POST /api/knowledge/export

task_type

string

Export all knowledge records for this task type (e.g. "generic.qa.v1"). Returns all finalized decisions of this type stored in the kernel. Mutually exclusive with task_id.

task_id

string

Export the knowledge record for a single specific task. Mutually exclusive with task_type.

Example — export by task type:

curl -X POST http://127.0.0.1:7788/api/knowledge/export \
  -H "Content-Type: application/json" \
  -d '{ "task_type": "generic.qa.v1" }'

Example response:

{
  "ok": true,
  "knowledge": {
    "task_type": "generic.qa.v1",
    "records": [
      {
        "task_id": "task-demo-001",
        "task_type": "generic.qa.v1",
        "finalized_at": 1718000010000,
        "decision_value": "100 degrees Celsius",
        "confidence": 0.98,
        "evidence_count": 2,
        "reuse_attempts": 1,
        "reuse_successes": 1
      },
      {
        "task_id": "task-demo-002",
        "task_type": "generic.qa.v1",
        "finalized_at": 1718000025000,
        "decision_value": "Paris",
        "confidence": 0.97,
        "evidence_count": 3,
        "reuse_attempts": 0,
        "reuse_successes": 0
      }
    ]
  }
}

Example — export by task ID:

curl -X POST http://127.0.0.1:7788/api/knowledge/export \
  -H "Content-Type: application/json" \
  -d '{ "task_id": "task-demo-001" }'

Example response:

{
  "ok": true,
  "knowledge": {
    "task_id": "task-demo-001",
    "task_type": "generic.qa.v1",
    "finalized_at": 1718000010000,
    "decision_value": "100 degrees Celsius",
    "confidence": 0.98,
    "evidence_refs": [
      {
        "ref_id": "artifact-abc123",
        "kind": "text/plain",
        "size_bytes": 256
      }
    ],
    "evidence_count": 2,
    "reuse_attempts": 1,
    "reuse_successes": 1
  }
}

Response fields:

knowledge

object

The exported knowledge bundle. Shape differs slightly depending on whether you queried by task_type (returns a records array) or by task_id (returns a single record with evidence_refs).

knowledge.task_type

string

Task type string for the exported records.

knowledge.records

object[]

Array of decision records when exporting by task_type.

knowledge.task_id

string

Present when exporting by task_id. The specific task identifier.

knowledge.decision_value

any

The finalized decision value. Type matches the output_schema defined in the original TaskContract.

knowledge.confidence

number

Aggregated confidence score in the range [0.0, 1.0].

knowledge.evidence_refs

object[]

Artifact references for the evidence items that supported the final candidate. Present in single-task exports.

knowledge.evidence_count

integer

Total number of evidence items associated with the finalized decision.

knowledge.reuse_attempts

integer

How many times this decision has been reused as a prior for a new task.

knowledge.reuse_successes

integer

Number of reuse attempts that passed verification and were accepted.

Error — both or neither parameter provided:

{
  "ok": false,
  "error": "provide exactly one of task_type or task_id"
}

Knowledge bundles only contain records for tasks that have been finalized (i.e. reached the Finalized terminal state). Tasks that expired, were cancelled, or only reached Committed state are not included.

Export knowledge bundles periodically and store them alongside your task contract library. When bootstrapping a new WattSwarm node or running offline evaluation, you can use these bundles to compare agent outputs against known-good historical decisions.

​What a Knowledge Bundle Contains

​POST /api/knowledge/export

What a Knowledge Bundle Contains

POST /api/knowledge/export