Core knowledge model

Knowl separates current truth, abandoned choices, temporary status, and supporting evidence into typed atoms while retaining history.

Atom categories

Every atom has exactly one of seven categories:

A skill atom describes a procedure; it is not automatically an executable file-backed package.

Metadata, history, and ownership

The item is the current view; related records retain provenance and history:

• Status: active, deprecated, rejected, archived, or superseded. Retrieval defaults to active; other states remain queryable through explicit history and maintenance paths.
• Freshness: fresh, needs_review, or stale, independently of status.
• Organization: numeric confidence and free-form tags.
• Source: source, sourceCommit, and repository-relative affectedPaths.
• Conflict identity: normalized key, sorted scope, and an optional exclusive flag.
• Ownership: originRepo, visibility, and a repository label on peer results.
• History: immutable assertions, linked evidence, and knowledge commits for governed changes.

Use a timeline when the question is what an item said before it changed:

knowl timeline <item-id>
knowl conflicts
knowl supersede <old-item-id> <replacement-id>

Supersession retires the predecessor with status: superseded; it does not delete the item, its assertions, or its history.

Governed writes and current truth

The deterministic MCP write path accepts structured atoms without an AI provider:

knowl_store({
  "category": "constraint",
  "title": "Authentication tokens stay server-side",
  "content": "Browser code must not persist bearer tokens.",
  "tags": ["auth", "security"]
})

When a verified correction replaces an item already returned by retrieval, make the relationship explicit in the same store call with supersedes, or store the replacement and then point the old item at it:

knowl_update({
  "id": "<new-item-id>",
  "supersedeId": "<old-item-id>"
})

With the default security configuration, every structured write rejects content that exceeds the configured size boundary, contains a detected secret, or references a sensitive path. security.rejectSecrets=false disables both secret detection and the sensitive-path check; field and raw-output size limits still apply. Accepted writes then follow these reconciliation rules:

1. An exact normalized title-and-content match is a no-op.
2. Knowl examines up to the top three active BM25 candidates in the same category. A normalized title subset with at least two significant shared tokens and at least 0.35 significant-token overlap identifies the same subject and retires the predecessor.
3. If no detected candidate qualifies for supersession, an explicitly named active supersedes item is retired. A qualifying detected same-subject candidate currently takes priority when it differs from that explicit ID.
4. Other semantic or lexical overlaps coexist. The result reports the nearby active item so the caller can reconcile it explicitly if necessary.
5. An exclusive write is rejected before insertion when another active exclusive item has the same normalized conflict key and sorted conflict scope.

These rules apply across atom categories rather than assigning special fuzzy behavior to only decisions or state. Batch ingestion and update-plus-supersede sequences should not be treated as an atomic multi-record transaction: current operations may commit individual records separately. Use explicit IDs and inspect the returned result when a correction spans records.