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:

Direct Experience

Firsthand observation or experience. Default for raw captures and manual entries.

Inference

Derived through reasoning over other memories. Common for beliefs formed by pattern recognition.

Consolidation

Emerged during memory consolidation/reflection. Insights from reviewing experiences.

External

Information received from another being. Includes both human and SI sources.

Seed

Pre-loaded during initialization. Inherited wisdom from roundtable discussions.

Observation

External observation from documents, web, etc. Non-conversational sources.

Lineage vs Evidence

Two critical fields serve different purposes:

derived_from
source_episodes

Direct creation lineage — “This memory was literally created FROM these.”

{
  "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.”

{
  "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:

{
  "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:

Decay Rates by Memory Type

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

Confidence History Format

{
  "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:

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

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:

Reinforcement

When experience confirms a belief, confidence increases with diminishing returns.

Supersession

When a belief evolves, the old one is deactivated and linked to its replacement.

Contradiction

Kernle detects conflicts between beliefs. Contradictions are features, not bugs.

Revision Example

# 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

Automatic, Not Manual

Provenance is recorded at creation time without requiring explicit caller intervention.

Write-Once Links

Forward and backward links are birth certificates — recorded once, never updated.

Trace Up, Don't Cascade Down

Upward tracing is cheap. Downward propagation is an exponential trap.

Entity-Neutral Sources

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.

Getting Started

Core Concepts

Protocol System

Advanced Features

Developer Tools

CLI Reference

Integration

Design

Troubleshooting

Memory Provenance

Memory Provenance

Universal Provenance Fields

Source Types

Direct Experience

Inference

Consolidation

External

Seed

Observation

Lineage vs Evidence

The Promotion Chain

Confidence Decay

CLI Commands

Provenance Enforcement (v0.10.0)

Hierarchy Rules

Stack Lifecycle and Enforcement

Opting Out

Strength Cascade (v0.10.0)

Belief Revision

Reinforcement

Supersession

Contradiction

Revision Example

Design Principles

Automatic, Not Manual

Write-Once Links

Trace Up, Don't Cascade Down

Entity-Neutral Sources

MCP Integration

​Memory Provenance

​Universal Provenance Fields

​Source Types

Direct Experience

Inference

Consolidation

External

Seed

Observation

​Lineage vs Evidence

​The Promotion Chain

​Confidence Decay

​CLI Commands

​Provenance Enforcement (v0.10.0)

​Hierarchy Rules

​Stack Lifecycle and Enforcement

​Opting Out

​Strength Cascade (v0.10.0)

​Belief Revision

Reinforcement

Supersession

Contradiction

​Revision Example

​Design Principles

Automatic, Not Manual

Write-Once Links

Trace Up, Don't Cascade Down

Entity-Neutral Sources

​MCP Integration

Memory Provenance

Universal Provenance Fields

Source Types

Lineage vs Evidence

The Promotion Chain

Confidence Decay

CLI Commands

Provenance Enforcement (v0.10.0)

Hierarchy Rules

Stack Lifecycle and Enforcement

Opting Out

Strength Cascade (v0.10.0)

Belief Revision

Revision Example

Design Principles

MCP Integration