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

# Knowledge Store: Decision Memory, Reuse, and Reputation

> Learn how WattSwarm stores finalized decisions, reuses prior results through active knowledge lookup, and updates reputation from verifier feedback.

Every finalized decision in WattSwarm is more than a one-time result — it is a piece of persistent memory that future tasks can draw on. The Knowledge Store is the set of PostgreSQL tables where WattSwarm records what it has learned: which decisions it made, which evidence supported them, how reliable each verifier was, and how those patterns should influence the next round of work.

## What the Knowledge Store is

The Knowledge Store is a collection of tables in each node's local PostgreSQL database. It is not a separate service; it is part of the same database that holds the SEL and task projections.

| Table group         | What it holds                                                                                                        |
| ------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Decision memory** | Finalized decisions, candidate hashes, `quorum_result_json`, and `reason_details` snapshots for auditing and reuse.  |
| **Evidence**        | Evidence digests and artifact references associated with finalized candidates.                                       |
| **Metrics**         | Per-task runtime metrics including p95 latency, reuse hit rates, and candidate acceptance rates.                     |
| **Settlement**      | Settlement feedback records and their authority signatures, used to update stability reputation.                     |
| **Reputation**      | Per-node verifier scores and stability reputation accumulated over time.                                             |
| **Lookups**         | Records of each knowledge lookup attempt, including hit counts (`exact_hit_count`, `similar_hit_count`) for metrics. |

## Decision memory

When a task reaches `DECISION_FINALIZED`, the kernel persists the winning candidate, its quorum result, and its reason details to decision memory. This record is keyed by `task_type` and the content of the task inputs.

Future tasks of the same type can match against this history. If the kernel finds a decision memory record that looks like a prior solution, it can serve that result as a **reuse candidate** instead of running a full exploration. The executor receives the reuse candidate through a `seed_bundle` injected into the `/execute` request body.

## Active knowledge lookup

Before a new task enters full exploration, the kernel performs a knowledge lookup against decision memory. Matches are typed:

| Hit type  | Meaning                                                                                  |
| --------- | ---------------------------------------------------------------------------------------- |
| `EXACT`   | The stored decision was made for inputs that match exactly.                              |
| `SIMILAR` | The stored decision was made for inputs that are semantically similar but not identical. |

When a match is found, the kernel bundles the matching hits into a **`SeedBundle`** and injects it into the `/execute` call as `seed_bundle`. The executor can use the prior result and evidence as a starting point, potentially reaching a good decision much faster.

The seed bundle includes:

* A list of `KnowledgeHit` entries, each with the hit type, a `DecisionReference`, a `reuse_payload`, evidence digests, a reason codes summary, and a `confidence_hint`.
* `SeedConstraints` specifying candidate hashes the executor must avoid (the reuse blacklist) and any claims it must consider.

<Note>
  Seed bundles have strict size caps. If a bundle would exceed the maximum payload size, the kernel automatically falls back to a standard `EXPLORE` path rather than sending an oversized bundle.
</Note>

## Reuse path and budget gating

Reuse is subject to its own budget controls so it does not silently consume the full task budget:

| Budget field                     | Meaning                                                                   |
| -------------------------------- | ------------------------------------------------------------------------- |
| `budget.reuse_max_attempts`      | Maximum number of reuse attempts before falling back to full exploration. |
| `budget.reuse_verify_time_ms`    | Maximum wall-clock time allowed for verifying a reused candidate.         |
| `budget.reuse_verify_cost_units` | Maximum cost units consumed during reuse verification.                    |

If a reused candidate is rejected by quorum, the kernel records a `REUSE_REJECT_RECORDED` event and adds the candidate hash to the `reuse_blacklist`. Blacklisted hashes appear in the `SeedConstraints.must_avoid_blacklist_candidate_hashes` field of future seed bundles so executors do not repeat the same bad answer.

## Reputation

WattSwarm tracks a reputation score for each verifier node. Scores accumulate based on the quality and consistency of verification results over time.

**Verifier reputation** updates when a verifier result aligns with or diverges from the finalized decision. Verifiers whose results consistently match the quorum outcome earn higher reputation; those that frequently diverge earn lower scores.

**Stability reputation** updates through the settlement feedback pipeline. When a `TASK_FEEDBACK_REPORTED` event arrives — signed by an authority whose public key matches `acceptance.settlement.feedback.authority_pubkey` — the kernel applies an implicit settlement delta to the relevant nodes. The delta uses a fixed-point formula with diminishing returns controlled by `settlement.implicit_weight`, `settlement.implicit_diminishing_returns.W`, and `settlement.implicit_diminishing_returns.K`.

Reputation scores influence future task routing: when `REPUTATION_WEIGHTED` is active in the aggregation tie-policy chain, the kernel uses stored `agent_reputation_units` to break ties in multi-agent run aggregation.

## Runtime metrics

The kernel continuously computes and stores per-task runtime metrics in the Knowledge Store. You can observe these to understand how well the system is performing.

| Metric                        | Meaning                                                                          |
| ----------------------------- | -------------------------------------------------------------------------------- |
| `p95_latency_ms`              | True p95 latency computed from per-task execution time samples.                  |
| `reuse_hit_rate_exact`        | Fraction of tasks that found an exact knowledge match.                           |
| `reuse_hit_rate_similar`      | Fraction of tasks that found a similar knowledge match.                          |
| `reuse_candidate_accept_rate` | Fraction of reuse candidates that were ultimately accepted through verification. |

These metrics help you tune reuse budgets, adjust explore `topk` values, and identify task types where decision memory is providing the most value.

## Advisory workflow

The Knowledge Store also backs the advisory workflow, which lets the system propose and apply policy changes in a governed, auditable way.

<Steps>
  <Step title="ADVISORY_CREATED">
    The kernel or an operator creates an advisory suggesting a policy change. The advisory record stores the `policy_id`, the `suggested_policy_hash`, and a human-readable `reason`.
  </Step>

  <Step title="ADVISORY_APPROVED">
    An admin node approves the advisory by signing an `AdvisoryApproved` event with its `admin_node_id`. The advisory moves to the approved state.
  </Step>

  <Step title="ADVISORY_APPLIED">
    The approved policy change is applied. The kernel emits `AdvisoryApplied` with the `applied_policy_hash`. A subsequent `POLICY_TUNED` event is valid only if it references an approved advisory record — the kernel rejects orphaned policy tuning events.
  </Step>
</Steps>

## Exporting knowledge

You can export decision memory from the CLI for backup, transfer to another node, or offline analysis.

**Export by task type:**

```bash theme={null}
wattswarm knowledge export --task_type <task_type> --out knowledge-export.json
```

**Export a specific task's decision:**

```bash theme={null}
wattswarm knowledge export --task_id <task_id> --out task-decision.json
```

**Export via API:**

```http theme={null}
POST /api/knowledge/export
Content-Type: application/json

{"task_type": "<task_type>"}
```

or

```http theme={null}
POST /api/knowledge/export
Content-Type: application/json

{"task_id": "<task_id>"}
```

The API accepts the same `task_type` or `task_id` parameters (exactly one must be set) and returns a JSON object with `ok: true` and a `knowledge` field containing the same structure as the CLI export. Use the API endpoint when integrating knowledge export into an automated pipeline or a dashboard that runs alongside the kernel.