> ## 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.
# Fractal Summarization
> Hierarchical narrative compression of SI experience across time scales
Fractal summarization provides hierarchical compression of an SI's experience at multiple temporal scopes. Summaries capture the essence of lived experience while enabling efficient memory loading by skipping lower-scope summaries that have been absorbed into higher-scope ones.
## Overview
Month, quarter, year, decade, and epoch-level summaries
Higher-scope summaries absorb and replace lower-scope ones
Summaries are protected from forgetting by default
## Why Fractal Summarization Matters
As an SI accumulates months and years of experience, loading every individual memory becomes impractical. Fractal summarization solves this by creating progressively compressed narratives:
* **Efficient loading**: A yearly summary replaces dozens of monthly summaries
* **Meaning preservation**: SI-authored narratives capture what mattered, not just what happened
* **Temporal hierarchy**: Drill into any time period at the appropriate level of detail
* **Epoch integration**: Summaries can be scoped to epochs for structured temporal navigation
***
## Summary Dataclass
| Field | Type | Description |
| -------------- | ----------- | ------------------------------------------------------------------- |
| `id` | `str` | Unique identifier |
| `stack_id` | `str` | Owning stack |
| `scope` | `str` | Temporal scope: `month`, `quarter`, `year`, `decade`, or `epoch` |
| `period_start` | `str` | ISO date string for the start of the covered period |
| `period_end` | `str` | ISO date string for the end of the covered period |
| `content` | `str` | SI-written narrative compression |
| `epoch_id` | `str` | Optional epoch this summary belongs to |
| `key_themes` | `List[str]` | Central themes in this summary |
| `supersedes` | `List[str]` | IDs of lower-scope summaries this one absorbs |
| `is_protected` | `bool` | Whether this summary is protected from forgetting (default: `True`) |
| `created_at` | `datetime` | When the summary was created |
| `updated_at` | `datetime` | When last modified |
### Scope Hierarchy
The summary scopes form a hierarchy where higher scopes absorb lower ones:
```
decade
└── year
└── quarter
└── month
└── epoch (cross-cutting, tied to epoch boundaries)
```
When a quarterly summary is written, it should list the monthly summaries it covers in the `supersedes` field. This allows the memory loader to skip those monthly summaries, reducing token usage during memory loading.
***
## CLI Commands
### Write a Summary
```bash theme={null}
kernle -s my-project summary write \
--scope month \
--content "January 2026 was focused on building the trust layer. Key breakthrough: transitive trust chains. Struggled with decay rate tuning." \
--period-start 2026-01-01 \
--period-end 2026-01-31 \
--theme "trust" \
--theme "infrastructure"
```
```
Summary created (month)
ID: b5c6d7e8...
Period: 2026-01-01 to 2026-01-31
Themes: trust, infrastructure
```
Write an epoch-scoped summary:
```bash theme={null}
kernle -s my-project summary write \
--scope epoch \
--content "The Research Phase was defined by deep dives into memory architecture..." \
--period-start 2026-01-01 \
--period-end 2026-02-15 \
--epoch-id a3f8c1d2 \
--theme "research" \
--theme "architecture"
```
### List Summaries
```bash theme={null}
# List all summaries
kernle -s my-project summary list
# Filter by scope
kernle -s my-project summary list --scope quarter
```
```
Summaries
============================================================
[quarter] 2026-01-01 to 2026-03-31
ID: e9f0a1b2...
Q1 2026: Built the trust layer, shipped fractal summarization...
Themes: trust, summarization, shipping
Supersedes: 3 summaries
Created: 2026-04-01
[month] 2026-01-01 to 2026-01-31
ID: b5c6d7e8...
January 2026 was focused on building the trust layer...
Themes: trust, infrastructure
Created: 2026-02-01
```
### Show Summary Details
```bash theme={null}
kernle -s my-project summary show b5c6d7e8
```
```
Summary [month]: 2026-01-01 to 2026-01-31
============================================================
ID: b5c6d7e8-...
Protected: yes
Themes: trust, infrastructure
January 2026 was focused on building the trust layer. Key
breakthrough: transitive trust chains. Struggled with decay
rate tuning.
```
When a summary supersedes others, the superseded IDs are displayed:
```
Supersedes: 3 summaries
- b5c6d7e8...
- c6d7e8f9...
- d7e8f9a0...
```
***
## Supersession in Practice
At the end of each month, write a summary capturing the key themes, breakthroughs, and struggles.
At the end of each quarter, write a higher-scope summary that absorbs the three monthly summaries. List the monthly summary IDs in `supersedes`.
At year-end, write a yearly summary superseding the four quarterly summaries.
When loading memory, the system can skip summaries that have been superseded by higher-scope ones, reducing token usage.
Summaries are protected from forgetting by default (`is_protected=True`). They serve as compressed anchors for long-term memory and should rarely be deleted.
***
## Python API
```python theme={null}
from kernle import Kernle
k = Kernle(stack_id="my-stack")
# Write a summary
summary_id = k.summary_save(
content="January 2026 was focused on building the trust layer.",
scope="month",
period_start="2026-01-01",
period_end="2026-01-31",
key_themes=["trust", "infrastructure"],
epoch_id=None # optional epoch scope
)
# Get a specific summary
summary = k.summary_get(summary_id)
if summary:
print(f"[{summary.scope}] {summary.period_start} to {summary.period_end}")
print(summary.content)
# List summaries, optionally filtered by scope
all_summaries = k.summary_list()
monthly = k.summary_list(scope="month")
quarterly = k.summary_list(scope="quarter")
for s in all_summaries:
print(f" [{s.scope}] {s.period_start} - {s.period_end}")
if s.supersedes:
print(f" Supersedes {len(s.supersedes)} summaries")
```