> ## 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.
# Temporal Epochs
> Named eras that mark significant transitions in an SI's timeline
Epochs are temporal markers that divide an SI's life into meaningful phases. They enable epoch-scoped memory loading, time-aware consolidation, and narrative coherence across long-lived SIs.
## Overview
Load memories from specific eras in the SI's history
Mark significant changes with explicit epoch boundaries
Connect epochs to beliefs, goals, relationships, and drives
## Why Epochs Matter
Long-lived SIs accumulate vast amounts of experience. Without temporal structure, all memories blend together into an undifferentiated mass. Epochs solve this by providing named eras that give shape to an SI's history:
* **Context switching**: Load only memories relevant to the current phase of work
* **Growth tracking**: See how beliefs and values evolved across epochs
* **Consolidation triggers**: Epoch closing triggers automatic consolidation of that era's learnings
* **Anxiety integration**: Epoch staleness contributes to the anxiety score when no active epoch exists
***
## Epoch Dataclass
| Field | Type | Description |
| ---------------------- | ----------- | ---------------------------------------------------------------- |
| `id` | `str` | Unique identifier |
| `stack_id` | `str` | Owning stack |
| `epoch_number` | `int` | Sequential epoch number |
| `name` | `str` | Human-readable epoch name |
| `started_at` | `datetime` | When the epoch began |
| `ended_at` | `datetime` | When the epoch ended (`None` if still active) |
| `trigger_type` | `str` | How the epoch was initiated: `declared`, `detected`, or `system` |
| `trigger_description` | `str` | Optional description of what triggered the epoch |
| `summary` | `str` | Optional summary of the epoch (typically set on close) |
| `key_belief_ids` | `List[str]` | Beliefs that defined this epoch |
| `key_relationship_ids` | `List[str]` | Important relationships during this epoch |
| `key_goal_ids` | `List[str]` | Goals pursued during this epoch |
| `dominant_drive_ids` | `List[str]` | Drives that were strongest during this epoch |
### Trigger Types
| Trigger | Description |
| ---------- | ------------------------------------------------------ |
| `declared` | Manually declared by the SI or operator |
| `detected` | Automatically detected from patterns in memory |
| `system` | System-generated (e.g., first epoch on initialization) |
***
## CLI Commands
### Create an Epoch
```bash theme={null}
kernle -s my-project epoch create "Learning Phase" \
--trigger declared \
--trigger-description "Starting a focused learning period"
```
```
Epoch created: Learning Phase
ID: a3f8c1d2...
Trigger: declared
```
### View the Current Epoch
```bash theme={null}
kernle -s my-project epoch current
```
```
Current epoch: #3 - Learning Phase
Started: 2026-01-15 09:30
ID: a3f8c1d2...
```
### List All Epochs
```bash theme={null}
kernle -s my-project epoch list
```
```
Epochs
============================================================
[3] Learning Phase (ACTIVE)
ID: a3f8c1d2...
Period: 2026-01-15 - now
Trigger: declared
[2] Production Deployment (closed)
ID: 7b2e9f41...
Period: 2025-12-01 - 2026-01-14
Trigger: declared
Summary: Shipped v2, learned to handle pressure...
```
### Show Epoch Details
```bash theme={null}
kernle -s my-project epoch show a3f8c1d2
```
```
Epoch #3: Learning Phase (ACTIVE)
============================================================
ID: a3f8c1d2-...
Period: 2026-01-15 09:30 - now
Trigger: declared
Trigger description: Starting a focused learning period
Key beliefs: 5
Key relationships: 3
Key goals: 2
Dominant drives: 2
```
### Close an Epoch
```bash theme={null}
# Close the current epoch with a summary
kernle -s my-project epoch close --summary "Completed the learning phase. Key insight: depth over breadth."
# Close a specific epoch by ID
kernle -s my-project epoch close --id a3f8c1d2 --summary "Phase complete."
```
Closing an epoch automatically triggers epoch-closing consolidation, which generates a reflection scaffold summarizing the epoch's key learnings, belief changes, and relationship evolution.
***
## Epoch-Filtered Loading
When loading working memory, you can scope it to a specific epoch. This is useful for focusing on memories from a particular phase:
```bash theme={null}
# Load only memories from the current epoch
kernle -s my-project load --epoch current
# Load memories from a specific epoch
kernle -s my-project load --epoch a3f8c1d2
```
The `load_all` method on the storage backend accepts an `epoch_id` parameter that filters all memory types (episodes, beliefs, notes, goals, etc.) to only those tagged with the given epoch.
***
## Epochs and Anxiety
The anxiety system accounts for epoch state. When no active epoch exists for an extended period, it contributes to the overall anxiety score as an "epoch staleness" factor. This encourages SIs to maintain temporal structure in their experience.
***
## Python API
```python theme={null}
from kernle import Kernle
k = Kernle(stack_id="my-stack")
# Create a new epoch
epoch_id = k.epoch_create(
name="Research Phase",
trigger_type="declared",
trigger_description="Beginning deep research into memory architectures"
)
# Get the current active epoch
current = k.get_current_epoch()
if current:
print(f"Active: {current.name} (#{current.epoch_number})")
# List all epochs
epochs = k.get_epochs(limit=10)
for e in epochs:
status = "ACTIVE" if e.ended_at is None else "closed"
print(f" [{e.epoch_number}] {e.name} ({status})")
# Get a specific epoch
epoch = k.get_epoch(epoch_id)
# Close the current epoch
k.epoch_close(summary="Completed research. Key findings documented as beliefs.")
# Close a specific epoch
k.epoch_close(epoch_id=epoch_id, summary="Phase complete.")
# Trigger epoch-closing consolidation
consolidation = k.consolidate_epoch_closing(epoch_id)
print(consolidation["scaffold"])
```