​

CoreProtocol — The Coordinator

​

CoreProtocol Interface

​

Properties

​

Model Management

​

Stack Management

​

Plugin Management

​

Routed Memory Operations

​

Upsert Semantics (v0.13.12)

• drive() — Looks up an existing drive by drive_type. If found, updates intensity, focus_areas, and other fields in place. The original id, created_at, and version chain are preserved. Only explicitly provided optional fields are overwritten.
• relationship() — Looks up an existing relationship by entity_name (other_stack_id). If found, updates fields in place and increments interaction_count. If not found, creates a new relationship.

​

Routed Search, Load, and Status

​

Trust Operations

​

Checkpoint & Binding

​

Stack Management

from kernle.entity import Entity
from kernle.stack import SQLiteStack

# Create the core
entity = Entity(core_id="my-entity")

# Attach stacks (returns stack_id, alias is cosmetic)
entity.attach_stack(SQLiteStack("primary"), alias="primary")
entity.attach_stack(SQLiteStack("work"), alias="work", set_active=False)

# Switch context (by stack_id)
entity.set_active_stack("work")

# Detach when done (by stack_id)
entity.detach_stack("work")

​

Plugin Lifecycle

​

Protocol Version Enforcement

# From Entity.load_plugin()
plugin_pv = getattr(plugin, "protocol_version", None)
if plugin_pv is not None and plugin_pv > PROTOCOL_VERSION:
    raise ValueError(
        f"Plugin '{plugin.name}' requires protocol version {plugin_pv}, "
        f"but this core supports version {PROTOCOL_VERSION}."
    )
elif plugin_pv is not None and plugin_pv < PROTOCOL_VERSION:
    logger.warning(
        "Plugin '%s' uses protocol version %d (current: %d).",
        plugin.name, plugin_pv, PROTOCOL_VERSION,
    )

​

Operation Routing

• id: New UUID
• stack_id: From the active stack
• source_entity: "core:{core_id}" or a custom source (plugins use "plugin:{name}")
• source_type: Explicit on all write paths. Accepts a string or SourceType enum value. Defaults to "direct_experience" when not specified. Invalid strings raise ValueError. Internal subsystems pass explicit values: checkpoint uses "observation", sync uses "external" with source_entity="kernle:sync", doctor uses "observation" with source_entity="kernle:doctor".
• created_at: Current UTC timestamp
• derived_from: Optional lineage chain
• context / context_tags: Optional grouping

# The proper way -- full provenance
entity.episode(
    "Deploy to production",
    "Successful with zero downtime",
    lessons=["Blue-green deploys work well"],
    tags=["deployment"],
    context="work",
)

# Bypass -- incomplete provenance (for migration/repair only)
stack.save_episode(Episode(
    id="...",
    stack_id=stack.stack_id,
    objective="Deploy to production",
    outcome="Successful",
    # No source_entity, no context, no source_type
))

​

Checkpoint Save and Restore

# Save current composition
cp_id = entity.checkpoint("before refactor")
# Saves to ~/.kernle/checkpoints/{core_id}_{timestamp}_{uuid}.json

# Restore later
from pathlib import Path
restored = Entity.from_checkpoint(Path.home() / ".kernle/checkpoints/my-entity_20260216_...json")

• schema_version — format version (currently 1) for forward compatibility
• checkpoint_id — unique identifier for this checkpoint
• message — human-readable description
• binding — the composition snapshot (core_id, model_config, stacks, plugins)
• created_at — UTC timestamp

• Missing schema_version is treated as version 1 with a warning (backward compat for checkpoints created before this change)
• schema_version > 1 raises ValueError (forward compat — prevents loading newer formats with older code)