> ## Documentation Index > Fetch the complete documentation index at: https://docs.kernle.ai/llms.txt > Use this file to discover all available pages before exploring further. # Memory Provenance > How Kernle tracks where memories come from and how they evolve # Memory Provenance Every memory in Kernle carries provenance metadata — a detailed record of its origin, relationships, and confidence evolution over time. This enables self-examination ("why do I believe this?"), belief debugging, and identity archaeology. Provenance answers three fundamental questions about any memory: * **Where did this come from?** — Source type and creation context * **What was it derived from?** — Direct lineage chain * **How has it changed?** — Confidence history and verification record ## Universal Provenance Fields Every memory type (episode, belief, note, value, etc.) carries these provenance fields: | Field | Type | Purpose | Example | | -------------------- | ------ | ------------------------------ | -------------------------------------------- | | `source_type` | string | How this memory was created | `direct_experience`, `inference`, `external` | | `source_entity` | string | Who provided it (optional) | `my-project`, `sean@emergent.ai` | | `source_episodes` | array | Supporting evidence | `["ep:abc123", "ep:def456"]` | | `derived_from` | array | Direct lineage chain | `["raw:f70c", "belief:old1"]` | | `confidence_history` | array | Timestamped confidence changes | See below | | `verification_count` | number | Independent verification count | `3` | ## Source Types Source types are **entity-neutral** — we don't distinguish between human and synthetic sources: Firsthand observation or experience. Default for raw captures and manual entries. Derived through reasoning over other memories. Common for beliefs formed by pattern recognition. Emerged during memory consolidation/reflection. Insights from reviewing experiences. Information received from another being. Includes both human and SI sources. Pre-loaded during initialization. Inherited wisdom from roundtable discussions. External observation from documents, web, etc. Non-conversational sources. ## Lineage vs Evidence Two critical fields serve different purposes: **Direct creation lineage** — "This memory was literally created FROM these." ```json theme={null} { "derived_from": ["raw:abc123", "belief:def456"], "meaning": "This belief was promoted from raw:abc123 and revises belief:def456" } ``` Used when a memory is created, including: * raw-to-episode promotion (`raw:...` → `episode:...`) * episode-to-belief promotion (`episode:...` → `belief:...`) * belief revision (`belief:old_id` → `belief:new_id`) **Supporting evidence** — "These episodes back this up." ```json theme={null} { "source_episodes": ["episode:abc123", "episode:def456"], "meaning": "These specific experiences provide evidence for this belief" } ``` Used when episodes provide evidence for a belief or value. Never conflate `derived_from` and `source_episodes`. Lineage is about creation; evidence is about support. ## The Promotion Chain Raw memories flow upward through promotion, with each step recording lineage: ``` Raw Capture: "First collaboration with Claire on PR #24" ↓ (promote) Episode: "Pair debugging seed beliefs import" ↓ (consolidation) Belief: "Independent convergence validates design decisions" ``` At each step, `derived_from` creates a traceable chain: ```json theme={null} { "raw:f70cefb6": { "content": "First collab with Claire on PR #24", "processed_into": ["episode:abc123"] }, "episode:abc123": { "derived_from": ["raw:f70cefb6"], "processed_into": ["belief:xyz789"] }, "belief:xyz789": { "derived_from": ["episode:abc123"] } } ``` ## Confidence Decay Memories that aren't verified or reinforced gradually lose confidence over time: | Type | Decay Rate | Period | Floor | Rationale | | ------- | ---------- | ------- | ----- | ------------------------------------- | | Episode | 1% | 30 days | 0.5 | Standard — experiences fade | | Belief | 1% | 30 days | 0.5 | Standard — beliefs need reinforcement | | Value | 0.5% | 60 days | 0.7 | Slower — core values are stable | | Note | 1.5% | 30 days | 0.4 | Faster — observations are transient | | Drive | 0.5% | 60 days | 0.6 | Slower — motivations are deep | | Goal | 1% | 30 days | 0.5 | Standard — goals can become stale | ```json theme={null} { "confidence_history": [ { "timestamp": "2026-02-01T10:30:00Z", "old": 0.85, "new": 0.87, "reason": "Reinforced (count: 3)", "evidence_source": "episode:abc123" } ] } ``` ## CLI Commands Provenance is integrated into all memory operations: ```bash theme={null} # Trace a belief's lineage kernle meta trace belief:bd200bfe # Find memories needing attention (low confidence) kernle meta uncertain --threshold 0.6 # Reverse trace: what came from this raw entry? kernle meta reverse raw:f70cefb6 # Find orphaned memories (broken provenance) kernle meta orphans # Verify a memory (increases confidence) kernle meta verify belief:xyz789 --evidence "Confirmed during code review" ``` ## Provenance Enforcement *(v0.10.0)* Provenance is enforced by default. Every memory (except raw entries) must cite its sources via `derived_from`. Creating a belief without citing an episode or note will raise `ProvenanceError`. This is intentional — memories must have traceable origins. ### Hierarchy Rules | Memory Type | Required Sources | Allowed Source Types | | ------------ | ---------------- | -------------------- | | Raw | none | — | | Episode | >= 1 | `raw` | | Note | >= 1 | `raw` | | Belief | >= 1 | `episode`, `note` | | Goal | >= 1 | `episode`, `belief` | | Relationship | >= 1 | `episode` | | Value | >= 1 | `belief` | | Drive | >= 1 | `episode`, `belief` | ### Stack Lifecycle and Enforcement Provenance requirements depend on stack state: * **INITIALIZING**: Seed writes with `source_type="seed"` bypass provenance (for bootstrap) * **ACTIVE**: All writes must have valid provenance (default state) * **MAINTENANCE**: Writes blocked entirely (admin operations only) ### Opting Out For testing or migration, provenance can be disabled: ```python theme={null} from kernle.stack import SQLiteStack stack = SQLiteStack("test-stack", enforce_provenance=False) from kernle import Kernle k = Kernle(stack_id="test", strict=False) # Bypasses stack layer entirely ``` ## Strength Cascade *(v0.10.0)* When a memory's strength changes, effects cascade through the provenance chain: * **Forget/Weaken cascade**: When a source memory is forgotten or weakened below 0.2, derived memories are flagged for review via audit entries * **Verify boost**: When a memory is verified, its source memories get a +0.02 strength boost * **Ungrounded detection**: If ALL source memories of a belief are forgotten/deleted, the belief is flagged as "ungrounded" Cascade depth is 1 (direct children only). All cascades except verify are advisory — they create audit entries but don't auto-modify child strength. ## Belief Revision Beliefs evolve through three mechanisms: When experience confirms a belief, confidence increases with diminishing returns. When a belief evolves, the old one is deactivated and linked to its replacement. Kernle detects conflicts between beliefs. Contradictions are features, not bugs. ### Revision Example ```python theme={null} # Old belief is revised old_belief = { "statement": "Always validate inputs", "is_active": false } # New belief links directly to the previous one new_belief = { "statement": "Validate inputs at trust boundaries, not everywhere", "derived_from": ["belief:old_belief_id"], "source_episodes": [/* inherited from old belief */] } ``` `supersedes`/`superseded_by` are legacy compatibility fields retained for pre-v0.14 stacks. In normal operation, revision is reconstructed from audit entries (`belief.revised`, `belief.deactivated`) rather than from these fields. ## Design Principles Provenance is recorded at creation time without requiring explicit caller intervention. Forward and backward links are birth certificates — recorded once, never updated. Upward tracing is cheap. Downward propagation is an exponential trap. Source types don't distinguish human from SI. A being is a being. ## MCP Integration Provenance is exposed through MCP tools for external clients: | Tool | Purpose | Parameters | | ---------------- | ----------------------------- | -------------------------- | | `meta_lineage` | Get full provenance chain | `memory_type`, `memory_id` | | `meta_verify` | Verify a memory with evidence | `memory_id`, `evidence` | | `meta_uncertain` | Find low-confidence memories | `threshold`, `apply_decay` | | `memory_*` | All creation tools support | `source`, `derived_from` | Provenance transforms memory from a black box into an archaeological dig. Every belief can be traced back to its roots, every decision can be examined for its foundations.