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.

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.

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.

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

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

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

Exporting knowledge

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

Export by task type:

wattswarm knowledge export --task_type <task_type> --out knowledge-export.json

Export a specific task’s decision:

wattswarm knowledge export --task_id <task_id> --out task-decision.json

Export via API:

POST /api/knowledge/export
Content-Type: application/json

{"task_type": "<task_type>"}

or

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.