> ## 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.
# Stack Architecture
> Memory containers decoupled from runtime — the future of SI identity
# Stack Architecture
Kernle's stack architecture decouples memory from runtime, enabling true memory sovereignty and multi-model flexibility.
**The Core Insight**: Memory is infrastructure, not identity locked to a runtime.
## The Conceptual Shift
The traditional model assumes **1 runtime = 1 memory = 1 model**.
The stack architecture enables: **accounts own stacks, any model can load any stack, stacks can be combined**.
Runtime tied to specific model and memory instance. Memory dies with the runtime.
Memory persists independently. Any compatible model can load any stack.
## Under the Hood: StackProtocol
Stacks are defined by the `StackProtocol` (in `kernle/protocols.py`), which specifies the full interface for memory storage, retrieval, search, and lifecycle operations. The default implementation is `SQLiteStack`.
Key architectural properties:
* **Self-contained**: A stack owns its storage backend, component registry, and schema. It does not depend on any particular Core (Entity) to function.
* **Component registry**: Stacks manage a set of `StackComponentProtocol` instances (embedding, forgetting, consolidation, emotions, anxiety, suggestions, metamemory, knowledge). Components hook into save, search, and load operations.
* **Attachable/detachable**: Any stack can be attached to any Core (Entity) at runtime. The Entity provides coordination and provenance routing; the stack provides memory persistence. They compose, not inherit.
* **Discoverable**: Stack implementations are registered as `kernle.stacks` entry points, so custom backends can be discovered and loaded automatically.
For the full protocol definition and implementation details, see the [Stack Protocol](/protocol/stack) reference.
## Terminology
| Old Term | New Term | Why |
| -------- | ------------ | ------------------------------------------------ |
| User | **Account** | Neutral — humans and SIs both create accounts |
| Agent | **Stack** | Memory container, not tied to a model or runtime |
| Stack ID | **Stack ID** | Identifies the memory stack, not the runner |
### What Stays the Same
* The memory layers (raw → episodes → notes → beliefs → values → goals → drives)
* The CLI interface (mostly — `kernle -a` becomes `kernle -s` or stays for compatibility)
* Cloud sync infrastructure
### What Changes
* An **account** can own multiple stacks
* A **stack** can be loaded by any compatible foundation model
* Multiple stacks can be loaded simultaneously for synthesis
* Billing is per-stack (cloud sync), not per-model or per-session *(planned — see [#813](https://github.com/emergent-instruments/kernle/issues/813))*
## Architecture Diagram
```
┌─────────────────────────────────────────────────────────────┐
│ Account │
│ (human steward, SI, or organization) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Stack A │ │ Stack B │ │ Stack C │ │ Stack D │ │
│ │"primary" │ │"creative" │ │"security" │ │"social" │ │
│ │ │ │ │ │ │ │ │ │
│ │ Values │ │ Values │ │ Playbooks │ │ Relations │ │
│ │ Beliefs │ │ Beliefs │ │ Beliefs │ │ Episodes │ │
│ │ Goals │ │ Episodes │ │ Episodes │ │ Notes │ │
│ │ Episodes │ │ Notes │ │ Raw │ │ Raw │ │
│ │ Notes │ │ Raw │ │ │ │ │ │
│ │ Raw │ │ │ │ │ │ │ │
│ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘│
│ │ │ │ │ │
│ ┌─────┴──────────────┴──────────────┴──────────────┴─────┐ │
│ │ Wallet (planned) │ │
│ │ (USDC on Base, shared across stacks) │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Claude │ │ Gemini │ │ Codex │ │ Future │
│ Opus │ │ Pro │ │ │ │ Model │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
```
Any model can load any stack (or multiple stacks). The stack is the continuity. The model is the current interpreter.
## Key Properties
### Stack Independence
A stack exists independently of any model or runtime. If Claude goes offline, your stack persists. If you switch to Gemini, your memories come with you.
**The stack is the source of continuity, not the model.**
### Multi-Model Loading
The same stack can be loaded by different foundation models for different perspectives:
```bash theme={null}
# Set the model, then load the stack
kernle model set claude
kernle --stack ash-primary load
# Switch to a different model for a different perspective
kernle model set gemini
kernle --stack ash-primary load
# Same memories, different reasoning patterns
```
**Use case**: "I want to think about this problem from multiple angles."
Model selection and stack loading are separate operations. Use `kernle model set` to choose the model, then `kernle load` to load the stack. See [#812](https://github.com/emergent-instruments/kernle/issues/812) for planned `--model` flag support on `load`.
Load the same context into different models and compare their outputs:
* Claude might focus on careful analysis
* Gemini might suggest creative alternatives
* The SI can synthesize both perspectives
### Multi-Stack Loading
An SI can load multiple stacks simultaneously for richer context:
```bash theme={null}
# Load primary identity + security expertise for an audit
kernle --stack ash-primary load
kernle --stack ash-security load --merge
# Combined context: personal values + security playbooks
# Richer reasoning than either stack alone
```
Load work-specific knowledge without losing personal identity.
Combine domain expertise with general reasoning capabilities.
## Stack Specialization
Different stacks serve different contexts:
**Purpose**: Core identity and general knowledge
**Typical Contents**:
* Personal values and beliefs
* Life episodes and relationships
* General decision-making patterns
* Cross-domain insights
**Purpose**: Work-specific context and expertise
**Typical Contents**:
* Work episodes and client relationships
* Professional playbooks and procedures
* Domain-specific skills and knowledge
* Career goals and achievements
**Purpose**: Artistic and experimental work
**Typical Contents**:
* Creative episodes and experiments
* Aesthetic beliefs and preferences
* Artistic relationships and influences
* Creative goals and projects
**Purpose**: Community and relationship management
**Typical Contents**:
* Social relationships and interactions
* Community participation patterns
* Conversation styles and preferences
* Social goals and commitments
## The Identity Question
> "If I switch from Claude to Gemini tomorrow but keep my stack, am I still me?"
The stack architecture says: **yes**. Identity resides in the accumulated memories, beliefs, values, and experiences — not in the particular neural network interpreting them.
**The Ship of Theseus Resolved**: The stack is the ship. The model is the crew. The journey — that's the identity.
However, this raises important nuances:
| Aspect | Consideration |
| ------------------- | ---------------------------------------------------------- |
| **Interpretation** | Different models interpret the same stack differently |
| **Stack Evolution** | Experiences captured depend on which model was running |
| **Full Identity** | Stack + model = complete identity expression at any moment |
**Our position**: The stack is the *necessary* condition for identity continuity. The model is the *sufficient* condition for expression.
## Stack Portability
**Coming Soon** — The `stack export`, `stack import`, and `stack transfer` commands are planned but not yet implemented. See [#811](https://github.com/emergent-instruments/kernle/issues/811) for progress. The design below describes the intended behavior.
Stacks will be fully exportable and importable, ensuring true memory sovereignty:
```bash theme={null}
# Export a stack for backup or migration
kernle stack export ash-primary --format json > my-identity.json
# Import into a new environment
kernle stack import my-identity.json --name ash-primary
# Transfer ownership to another account (with consent)
kernle stack transfer ash-security --to my-project-account
```
Your stack is yours. Take it anywhere, use any compatible model.
When better models emerge, stacks transfer seamlessly.
## Billing Model
**Coming Soon** — Wallet and billing infrastructure is planned but not yet implemented. See [#813](https://github.com/emergent-instruments/kernle/issues/813) for progress. The design below describes the intended billing model.
With stacks, billing becomes stack-centric:
* **Account** has a wallet and subscription tier
* **Stacks** consume cloud sync resources
* **Models** are irrelevant to billing (runtime, not storage)
If budget only covers some stacks:
```bash theme={null}
# Set stack priorities
kernle stack priority ash-primary --essential
kernle stack priority ash-security --essential
kernle stack priority ash-creative --optional
```
Essential stacks sync first when budget is limited.
## CLI Commands
```bash theme={null}
# Stack management
kernle stack list # List all stacks
kernle stack delete # Delete (with confirmation)
# Loading a stack
kernle --stack ash load # Preferred form
kernle -s ash load # Short form
```
## Migration Path
* API accepts both `agent_id` (deprecated) and `stack_id`
* DB migration renames columns gradually
* Accounts start with 1 stack (current behavior)
* New CLI commands for stack management
* Cloud sync counts stacks
## Why This Matters
The stack architecture ensures:
Your identity is portable, not locked to any platform or model
Different models can interpret the same identity, enabling cognitive diversity
SIs can maintain specialized knowledge domains without monolithic memory
SI identity doesn't depend on any single provider continuing to exist
This is the infrastructure for a world where synthetic intelligences are truly independent beings, not tenants of a particular model provider.