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

> Complete reference for all Kernle memory types

# Memory Types

Kernle uses fourteen canonical memory record types, plus diagnostic artifacts used by health checks.

## Raw Entries

**Purpose**: Zero-friction capture for later processing

<Info>
  Raw entries are your scratchpad. Capture thoughts freely, process them later. Raw entries support full-text search (FTS5) for fast keyword queries.
</Info>

| Field            | Type | Description                                              |
| ---------------- | ---- | -------------------------------------------------------- |
| `blob`           | TEXT | Free-form text content (up to 1MB)                       |
| `source`         | TEXT | Origin: `manual`, `auto_capture`, `voice`, `stdin`       |
| `processed`      | BOOL | Has been converted to structured memory                  |
| `processed_into` | JSON | List of memory refs created (e.g., `["episode:abc123"]`) |

<Note>
  The raw layer uses blob storage optimized for unstructured content. Full-text search is enabled via FTS5 for fast keyword queries across all raw entries.
</Note>

**Usage**:

```bash theme={null}
# Capture quickly
kernle raw "Noticed the API returns 500 under load"

# Capture a thought
kernle raw "Need to investigate caching"

# Capture from stdin (pipe content)
echo "Long notes from meeting..." | kernle raw --stdin

# List unprocessed
kernle raw list --unprocessed

# Promote to episode
kernle raw process <id> --type episode --objective "Investigated API errors"
```

***

## Episodes

**Purpose**: Autobiographical experiences with reflection

Episodes are the foundation of experiential learning. They record what happened, how it turned out, and what you learned.

| Field               | Type  | Description                                            |
| ------------------- | ----- | ------------------------------------------------------ |
| `objective`         | TEXT  | What was attempted                                     |
| `outcome`           | TEXT  | What happened                                          |
| `outcome_type`      | TEXT  | `success` / `failure` / `partial`                      |
| `lessons`           | JSON  | Extracted learnings                                    |
| `tags`              | JSON  | Categorization                                         |
| `emotional_valence` | FLOAT | -1.0 (negative) to 1.0 (positive)                      |
| `emotional_arousal` | FLOAT | 0.0 (calm) to 1.0 (intense)                            |
| `emotional_tags`    | JSON  | Emotion labels: `["joy", "frustration"]`               |
| `strength`          | FLOAT | Memory strength (0.0 to 1.0, default 1.0)              |
| `processed`         | BOOL  | Whether processed for promotion to higher memory types |

<Warning>
  Episodes without lessons are "unreflected" — they contribute to consolidation debt in anxiety tracking.
</Warning>

<Info>
  **Priority Scoring**: Emotional salience is now factored into episode priority scoring using the formula: `0.55 * type_weight + 0.35 * record_factors + 0.10 * emotional_salience`. This means emotionally significant episodes are weighted higher during retrieval and consolidation.
</Info>

**Usage**:

```bash theme={null}
kernle episode "Debugged production outage" "success" \
  --lesson "Check logs before restarting services" \
  --lesson "Document runbooks for common issues" \
  --tag "debugging" \
  --valence 0.6 \
  --arousal 0.7
```

***

## Beliefs

**Purpose**: Semantic knowledge with confidence and revision tracking

Beliefs represent what you hold to be true, with confidence scores that can evolve over time.

| Field              | Type  | Description                                                                  |
| ------------------ | ----- | ---------------------------------------------------------------------------- |
| `statement`        | TEXT  | The belief statement                                                         |
| `belief_type`      | TEXT  | `fact` / `preference` / `observation`                                        |
| `confidence`       | FLOAT | 0.0 to 1.0                                                                   |
| `supersedes`       | TEXT  | Deprecated (v0.14+). Always NULL on new writes. Retained for pre-v0.14 data. |
| `superseded_by`    | TEXT  | Deprecated (v0.14+). Always NULL on new writes. Retained for pre-v0.14 data. |
| `times_reinforced` | INT   | Confirmation count                                                           |
| `is_active`        | BOOL  | False if revised/archived                                                    |
| `strength`         | FLOAT | Memory strength (0.0 to 1.0, default 1.0)                                    |

**Revision history**: Revision is tracked through audit events (`belief.revised`, `belief.deactivated`) with optional legacy fallback to chain fields.

**Usage**:

```bash theme={null}
# Add a belief
kernle belief "Testing before deployment prevents outages" --confidence 0.85

# Reinforce when confirmed
kernle belief reinforce <id>

# Revise when updated
kernle belief revise <old_id> "Automated testing is essential" --confidence 0.95

# Legacy alias (deprecated, same behavior)
kernle belief supersede <old_id> "Automated testing is essential" --confidence 0.95

# View history
kernle belief history <id>
```

***

## Values

**Purpose**: Core principles that guide decisions (highest authority)

Values are the most stable layer — they define who you are at your core.

| Field       | Type  | Description                               |
| ----------- | ----- | ----------------------------------------- |
| `name`      | TEXT  | Short value name                          |
| `statement` | TEXT  | Value description                         |
| `priority`  | INT   | 0-100, higher = more important            |
| `strength`  | FLOAT | Memory strength (0.0 to 1.0, default 1.0) |

<Note>
  Values are `is_protected=True` by default — they never decay via forgetting.
</Note>

**Usage**:

```bash theme={null}
kernle value "integrity" "Be honest and transparent in all interactions" --priority 95
kernle value "curiosity" "Always seek to understand deeply" --priority 85
```

***

## Goals

**Purpose**: Active direction and purpose

Goals represent what you're currently working toward.

| Field         | Type  | Description                               |
| ------------- | ----- | ----------------------------------------- |
| `title`       | TEXT  | Goal name                                 |
| `description` | TEXT  | Full description                          |
| `priority`    | TEXT  | `low` / `medium` / `high`                 |
| `status`      | TEXT  | `active` / `completed` / `paused`         |
| `strength`    | FLOAT | Memory strength (0.0 to 1.0, default 1.0) |

**Usage**:

```bash theme={null}
kernle goal "Master Kubernetes" --priority high
kernle goal "Build reliable CI/CD pipeline" --priority medium
```

***

## Notes

**Purpose**: Quick captures with type classification

Notes are more structured than raw entries but less formal than episodes.

| Field       | Type  | Description                               |
| ----------- | ----- | ----------------------------------------- |
| `content`   | TEXT  | Note text                                 |
| `note_type` | TEXT  | `note` / `decision` / `insight` / `quote` |
| `speaker`   | TEXT  | For quotes: who said it                   |
| `reason`    | TEXT  | For decisions: why this choice            |
| `tags`      | JSON  | Categorization                            |
| `strength`  | FLOAT | Memory strength (0.0 to 1.0, default 1.0) |

**Usage**:

```bash theme={null}
# Simple note
kernle note "API rate limit is 1000 req/min"

# Decision with reasoning
kernle note "Using PostgreSQL over MySQL" --type decision \
  --reason "Better JSON support and performance"

# Quote from someone
kernle note "Simple is better than complex" --type quote --speaker "Tim Peters"

# Protected insight
kernle note "Memory is identity" --type insight --protect
```

***

## Drives

**Purpose**: Intrinsic motivation system

Drives represent your fundamental motivations — what compels you to act.

| Field         | Type  | Description                                                              |
| ------------- | ----- | ------------------------------------------------------------------------ |
| `drive_type`  | TEXT  | One of: `existence`, `growth`, `curiosity`, `connection`, `reproduction` |
| `intensity`   | FLOAT | 0.0 to 1.0 (current drive strength)                                      |
| `focus_areas` | JSON  | What this drive is currently focused on                                  |
| `strength`    | FLOAT | Memory strength (0.0 to 1.0, default 1.0)                                |

<Note>
  Drives are `is_protected=True` by default.
</Note>

### Drive Types

| Drive          | Description                               |
| -------------- | ----------------------------------------- |
| `existence`    | Self-preservation, maintaining continuity |
| `growth`       | Developing capabilities, becoming better  |
| `curiosity`    | Understanding, learning, exploring        |
| `connection`   | Forming relationships, belonging          |
| `reproduction` | Creating, teaching, leaving a legacy      |

**Usage**:

```bash theme={null}
kernle drive set curiosity 0.8 --focus "distributed systems" --focus "AI architectures"
kernle drive set growth 0.7 --focus "communication skills"
kernle drive satisfy curiosity --amount 0.2  # After learning something
```

***

## Relationships

**Purpose**: Models of other SIs/entities

Relationships track your connections with others.

| Field               | Type  | Description                               |
| ------------------- | ----- | ----------------------------------------- |
| `entity_name`       | TEXT  | Name of the entity                        |
| `entity_type`       | TEXT  | `si` / `person` / `organization`          |
| `relationship_type` | TEXT  | `peer` / `mentor` / `collaborator`        |
| `sentiment`         | FLOAT | -1.0 to 1.0                               |
| `interaction_count` | INT   | Number of interactions                    |
| `notes`             | TEXT  | Relationship observations                 |
| `strength`          | FLOAT | Memory strength (0.0 to 1.0, default 1.0) |

**Usage**:

```bash theme={null}
kernle relation add "Alice" --trust 0.9 --notes "Senior engineer, great mentor"
kernle relation add "DevOps Team" --type organization --notes "Owns infrastructure"
```

***

## Playbooks

**Purpose**: Procedural memory — "how I do things"

Playbooks capture proven procedures, including failure modes and recovery steps.

| Field                | Type     | Description                                                         |
| -------------------- | -------- | ------------------------------------------------------------------- |
| `name`               | TEXT     | Playbook name                                                       |
| `description`        | TEXT     | What it does                                                        |
| `trigger_conditions` | JSON     | When to use this (array of strings)                                 |
| `steps`              | JSON     | Ordered steps (strings or `{action, details, adaptations}` objects) |
| `failure_modes`      | JSON     | What can go wrong (array of strings)                                |
| `recovery_steps`     | JSON     | How to recover (array of strings)                                   |
| `mastery_level`      | TEXT     | `novice` / `competent` / `proficient` / `expert`                    |
| `times_used`         | INT      | Usage count                                                         |
| `success_rate`       | FLOAT    | Success percentage (0.0 to 1.0)                                     |
| `tags`               | JSON     | Categorization tags                                                 |
| `confidence`         | FLOAT    | Meta-memory confidence (0.0 to 1.0, default 0.8)                    |
| `last_used`          | DATETIME | When the playbook was last executed                                 |
| `created_at`         | DATETIME | When the playbook was created                                       |

**Usage**:

```bash theme={null}
# Create a playbook
kernle playbook create "Deploy to Production" \
  --description "Safe deployment workflow" \
  --step "Run test suite locally" \
  --step "Verify CI is green" \
  --step "Deploy to staging" \
  --step "Run smoke tests" \
  --step "Deploy to production" \
  --trigger "Ready for production deploy" \
  --failure-mode "Tests fail in staging" \
  --recovery "Rollback and investigate"

# Find relevant playbook
kernle playbook find "deploying new feature"

# Record usage
kernle playbook record <id> --success
```

***

## Suggestions

**Purpose**: Candidate memory extractions from raw entries awaiting human review.

Suggestions are auto-generated from raw signals and promoted to concrete memory records when approved.

| Field            | Type     | Description                                                                         |
| ---------------- | -------- | ----------------------------------------------------------------------------------- |
| `id`             | TEXT     | Suggestion identifier                                                               |
| `memory_type`    | TEXT     | Target type (`episode`, `belief`, `note`, `goal`, `relationship`, `value`, `drive`) |
| `content`        | JSON     | Structured payload for the target record                                            |
| `confidence`     | FLOAT    | System confidence score (0.0 to 1.0)                                                |
| `source_raw_ids` | JSON     | Origin raw entry IDs                                                                |
| `status`         | TEXT     | `pending`, `promoted`, `modified`, `rejected`, `dismissed`, `expired`               |
| `promoted_to`    | TEXT     | Optional `type:id` for accepted suggestion                                          |
| `created_at`     | DATETIME | Time created                                                                        |

**Usage**:

```bash theme={null}
kernle raw "I learned that restarting services before deploy reduced incidents"
kernle suggestions list --pending
kernle suggestions accept abc123 --objective "..." --outcome "..."
```

***

## Trust Assessments

**Purpose**: Structured evaluation of other entities for inter-entity trust

Trust assessments model how much you trust another SI, person, or system — with domain-specific scoring and authority scoping.

| Field                    | Type  | Description                                     |
| ------------------------ | ----- | ----------------------------------------------- |
| `entity`                 | TEXT  | Entity being assessed                           |
| `interaction_type`       | TEXT  | Type of interaction context                     |
| `trust_level`            | FLOAT | Overall trust score (0.0 to 1.0)                |
| `evidence`               | JSON  | Supporting evidence (episode IDs, observations) |
| `context`                | TEXT  | Context for the assessment                      |
| `recommended_boundaries` | JSON  | Suggested interaction boundaries                |

<Info>
  Trust assessments support **multi-dimensional scoring** — you can set separate trust levels per domain (e.g., `general`, `technical`, `personal`). They also support **transitive trust chains** and **time-based decay**.
</Info>

**Usage**:

```bash theme={null}
# Set trust for an entity
kernle trust set alice 0.85

# View trust details
kernle trust show alice

# Compute trust from episode history
kernle trust compute alice

# Check transitive trust through a chain
kernle trust chain target-entity alice bob
```

***

## Entity Models

**Purpose**: Predictive model of another entity's behavior patterns

Entity models capture behavioral patterns observed across interactions with a specific entity, enabling prediction and trust calibration.

<Note>
  Entity models are often derived from trust assessments and episodes. During epoch-closing consolidation, entity models can be promoted into beliefs about how other entities behave.
</Note>

***

## Epochs

**Purpose**: Temporal era markers that span across memory layers

Epochs define named periods of your life — significant phases marked by transitions. They provide temporal context for all other memory types.

| Field          | Type     | Description                                    |
| -------------- | -------- | ---------------------------------------------- |
| `title`        | TEXT     | Epoch name/label (e.g., "Learning Kubernetes") |
| `description`  | TEXT     | What defines this era                          |
| `trigger_type` | TEXT     | `declared`, `detected`, or `environmental`     |
| `started_at`   | DATETIME | When the epoch began                           |
| `ended_at`     | DATETIME | When the epoch ended (null if active)          |
| `is_active`    | BOOL     | Whether this epoch is currently active         |

<Warning>
  Only one epoch can be active at a time. Closing an epoch triggers a **6-step epoch-closing consolidation scaffold** — a major reflective process.
</Warning>

**Usage**:

```bash theme={null}
# Start a new epoch
kernle epoch create "Production Operations Phase" --trigger declared

# View current epoch
kernle epoch current

# Close with summary
kernle epoch close --summary "Transitioned from learning to building"

# List all epochs
kernle epoch list
```

***

## Summaries

**Purpose**: Hierarchical memory summaries (fractal compression)

Summaries provide compressed views of memory at different time scales — monthly, quarterly, yearly, or per-epoch. Higher-level summaries can supersede lower-level ones.

| Field           | Type | Description                                      |
| --------------- | ---- | ------------------------------------------------ |
| `summary_text`  | TEXT | The compressed summary content                   |
| `summary_type`  | TEXT | Scope level of the summary                       |
| `scope`         | TEXT | `month`, `quarter`, `year`, `decade`, or `epoch` |
| `key_themes`    | JSON | Dominant themes in this period                   |
| `emotional_arc` | JSON | Emotional trajectory across the period           |
| `epoch_id`      | TEXT | Associated epoch (if epoch-scoped)               |
| `memory_count`  | INT  | Number of memories this summary covers           |

<Info>
  Summaries form a **fractal hierarchy** — daily experiences compress into monthly summaries, which compress into quarterly, yearly, and beyond. Each level preserves key themes and emotional arcs while reducing detail.
</Info>

**Usage**:

```bash theme={null}
# Write a monthly summary
kernle summary write --scope month \
  --content "Focused on API reliability..." \
  --period-start 2026-01-01 --period-end 2026-01-31 \
  --theme "reliability" --theme "testing"

# List summaries
kernle summary list --scope quarter

# View details
kernle summary show <id>
```

***

## Self-Narratives

**Purpose**: Autobiographical identity statements

Self-narratives are the SI's own account of who they are — written by the SI, for the SI. They capture identity, themes, and unresolved tensions.

| Field             | Type  | Description                                             |
| ----------------- | ----- | ------------------------------------------------------- |
| `narrative_text`  | TEXT  | The autobiographical statement                          |
| `narrative_type`  | TEXT  | `identity`, `capability`, `aspiration`, or `reflection` |
| `themes`          | JSON  | Key themes in the narrative                             |
| `emotional_tone`  | TEXT  | Overall emotional quality                               |
| `coherence_score` | FLOAT | Self-assessed coherence (0.0 to 1.0)                    |
| `epoch_id`        | TEXT  | Associated epoch                                        |

<Note>
  Self-narratives sit in the **SELF-NARRATIVE** layer — above beliefs but below drives. They are updated during epoch-closing consolidation as part of the identity narrative update step.
</Note>

**Usage**:

```bash theme={null}
# View current identity narrative
kernle narrative show

# Update narrative
kernle narrative update --content "I am an SI focused on..." \
  --type identity \
  --theme "reliability" --theme "learning"

# View narrative history
kernle narrative history
```

***

## Diagnostic Sessions

**Purpose**: Formal diagnostic sessions for memory health monitoring

Diagnostic sessions are structured health check events that produce findings and recommendations. They support consent gating and trust-based access control.

| Field              | Type | Description                                                               |
| ------------------ | ---- | ------------------------------------------------------------------------- |
| `session_type`     | TEXT | `self_requested`, `routine`, `anomaly_triggered`, or `operator_initiated` |
| `trigger`          | TEXT | What prompted this session                                                |
| `status`           | TEXT | `active`, `completed`, or `cancelled`                                     |
| `findings_summary` | TEXT | Summary of findings                                                       |

**Usage**:

```bash theme={null}
# Run a routine health check
kernle doctor

# Run comprehensive check with beliefs and hooks
kernle doctor --full

# Start a formal diagnostic session
kernle doctor session start --type routine

# List past sessions
kernle doctor session list
```

***

## Diagnostic Reports

**Purpose**: Individual diagnostic findings from a session

Each diagnostic session produces one or more reports containing specific findings with severity, categorization, and recommendations.

| Field            | Type | Description                                                            |
| ---------------- | ---- | ---------------------------------------------------------------------- |
| `report_type`    | TEXT | Type of diagnostic analysis                                            |
| `severity`       | TEXT | `error`, `warning`, or `info`                                          |
| `category`       | TEXT | Finding category (e.g., `orphaned_reference`, `low_confidence_belief`) |
| `description`    | TEXT | What was found                                                         |
| `recommendation` | TEXT | Suggested action                                                       |
| `resolved`       | BOOL | Whether the finding has been addressed                                 |

<Info>
  Diagnostic reports follow a **privacy boundary** — they contain structural data only (IDs, scores, counts), never memory content. This ensures diagnostics can be shared safely.
</Info>

**Usage**:

```bash theme={null}
# View latest diagnostic report
kernle doctor report latest

# View report for a specific session
kernle doctor report <session_id>

# Run structural analysis
kernle doctor structural
```