Claude Code Integration
Kernle integrates with Claude Code via hooks — memory loads automatically, checkpoints save before compaction and at session end, and native memory file writes are intercepted and captured into Kernle.
How It Works
CLAUDE CODE SESSION STARTS
↓
1. SessionStart hook fires
2. `kernle hook session-start` loads memory
3. Memory injected as session context automatically
4. SI has full memory: values, beliefs, goals, checkpoint, episodes
↓
SI WORKS (captures memories via CLI as they happen)
↓
CONTEXT COMPACTION
↓
5. PreCompact hook saves checkpoint automatically
6. SessionStart re-fires — memory reloaded into fresh context
↓
SI CONTINUES WORKING
↓
SESSION ENDS
↓
7. SessionEnd hook saves final checkpoint automatically
Write Interception
When the SI tries to write to memory/ or MEMORY.md (Claude Code’s native memory), the PreToolUse hook:
- Captures the content as a Kernle raw entry
- Blocks the write
- Returns a message directing the SI to use Kernle commands instead
This ensures all memory flows through Kernle’s structured system.
Installation (Recommended)
The recommended approach uses kernle setup which writes hooks directly into .claude/settings.json — no plugin directory or repo access needed.
Install Kernle
pip install kernle
# or
pipx install kernle
Initialize a Stack
kernle -s my-project init
Setup Claude Code Hooks
# Project-level (writes to .claude/settings.json)
kernle setup claude-code
# Or global (writes to ~/.claude/settings.json)
kernle setup claude-code --global
Verify
Then start a new Claude Code session:Ask: “What are my current values and goals from Kernle?”The SI should respond with your memory without needing to run any commands. Installation (Plugin Mode)
Alternatively, use the plugin directory (requires access to the Kernle source repo):
claude --plugin-dir ./integrations/claude-code
kernle hook <event> commands.
Configuration
All configuration is via environment variables — no config files needed:
| Variable | Default | Description |
|---|
KERNLE_STACK_ID | auto-detected | Kernle stack ID |
KERNLE_TOKEN_BUDGET | 8000 | Token budget for memory loading |
Stack ID Resolution
The hooks resolve the stack ID in order:
--stack flag baked into hook commands by kernle setupKERNLE_STACK_ID environment variable- Project directory name from working directory
- Kernle auto-resolve
For multi-project setups, set KERNLE_STACK_ID in your shell profile:
export KERNLE_STACK_ID=my-project
Hooks
SessionStart — Memory Loading
Fires on startup, resume, clear, and compact. Loads memory and injects it as additionalContext in the session.
Matches Write, Edit, and NotebookEdit tool calls. When the target path matches a memory file (memory/, MEMORY.md), the hook:
- Captures the content as a Kernle raw entry (for preservation)
- Blocks the write with a deny decision
- Returns a message explaining that memory is handled by Kernle
PreCompact — Pre-Compaction Checkpoint
Fires before context compaction. Reads the transcript to extract the last user message (task) and assistant message (context), then saves a checkpoint prefixed with [pre-compact].
SessionEnd — Final Checkpoint
Fires when the session terminates. Reads the transcript and saves both a checkpoint and a raw entry marking session completion.
Graceful Degradation
All hooks exit 0 on any error. If Kernle is not installed, the stack doesn’t exist, or any command fails, the session continues normally with no error messages.
What Gets Loaded
The SessionStart hook loads memory containing:
- Checkpoint — current task, context, next steps (resume point)
- Values — core principles
- Beliefs — held truths with confidence levels
- Goals — active goals with priority
- Drives — motivations with intensity
- Lessons — extracted from recent episodes
- Relationships — key entities with sentiment
Memory loading is budget-aware (default 8000 tokens). Items are loaded by priority: checkpoint > values > beliefs > goals > drives > episodes > notes > relationships.
During Work
The SI captures memories via CLI as they happen. Each command writes immediately to local storage:
# Quick capture
kernle -s my-project raw "API rate limit is per-user, not per-key"
# Record a significant experience
kernle -s my-project episode "Debugged API timeout" "success" \
--lesson "Check network latency before assuming code issues"
# Document a decision
kernle -s my-project note "Using Redis for session cache" \
--type decision \
--reason "Need sub-millisecond reads"
Relationship to Native Features
Claude Code has its own memory mechanisms. Here’s how they interact with Kernle:
| Feature | What It Does | Kernle Relationship |
|---|
CLAUDE.md | Static project instructions | Coexists — different purpose (instructions vs memory) |
Auto-memory (~/.claude/.../memory/) | Simple text notes across sessions | Replaced — hook intercepts writes and routes to Kernle |
| Conversation context | In-session history | Coexists — Kernle adds cross-session persistence |
CLAUDE.md is not replaced by Kernle. It serves as the project instruction file — where you put setup commands, coding guidelines, and workflow rules. Kernle handles dynamic memory (what the SI has experienced, learned, and believes).
MCP Server (Alternative)
Kernle also provides an MCP server that works with Claude Code. This is an alternative to the hook approach — use one or the other for memory loading, not both.
The hook approach is recommended because:
- Memory loads automatically (no manual tool call needed)
- Auto-checkpointing before compaction and at session end
- Native write interception routes all memory through Kernle
- No MCP configuration required
If you need MCP tools during the session (e.g., memory_search, memory_anxiety), you can use both: hooks for automatic lifecycle management, and MCP for in-session memory operations. See the MCP Integration guide.
Diagnostics
Verify the integration works:
# Full health check (includes hook validation)
kernle doctor --full
# Verify Kernle is available
which kernle
kernle -s my-project status
# Test loading manually
kernle -s my-project load
# Test hooks manually
echo '{"cwd": "."}' | kernle hook session-start
Troubleshooting
Memory not appearing at session start
-
Run the doctor check:
-
Verify hooks are in settings.json:
cat .claude/settings.json
# Should show SessionStart, PreToolUse, PreCompact, SessionEnd hooks
-
Test the load command manually:
kernle -s my-project load
-
Check if stack is initialized:
kernle -s my-project status
Kernle command not found
Ensure Kernle is installed and in PATH:
which kernle
# If missing:
pip install kernle
Writes to MEMORY.md being blocked
This is expected behavior. The hook intercepts writes to memory files and routes them through Kernle. Use Kernle CLI commands instead:
kernle -s my-project raw "your thought here"
kernle -s my-project note "your observation" --type insight
