Skip to main content

​
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

​
Write Interception

When the SI tries to write to memory/ or MEMORY.md (Claude Code’s native memory), the PreToolUse hook:
  1. Captures the content as a Kernle raw entry
  2. Blocks the write
  3. Returns a message directing the SI to use Kernle commands instead
This ensures all memory flows through Kernle’s structured system. The recommended approach uses kernle setup which writes hooks directly into .claude/settings.json — no plugin directory or repo access needed.
1

Install Kernle

2

Initialize a Stack

3

Setup Claude Code Hooks

4

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):
Both approaches call the same kernle hook <event> commands.

​
Configuration

All configuration is via environment variables — no config files needed:

​
Stack ID Resolution

The hooks resolve the stack ID in order:
  1. --stack flag baked into hook commands by kernle setup
  2. KERNLE_STACK_ID environment variable
  3. Project directory name from working directory
  4. Kernle auto-resolve
For multi-project setups, set KERNLE_STACK_ID in your shell profile:

​
Hooks

​
SessionStart — Memory Loading

Fires on startup, resume, clear, and compact. Loads memory and injects it as additionalContext in the session.

​
PreToolUse — Write Interception

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:

​
Relationship to Native Features

Claude Code has its own memory mechanisms. Here’s how they interact with Kernle:
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:

​
Troubleshooting

​
Memory not appearing at session start

  1. Run the doctor check:
  2. Verify hooks are in settings.json:
  3. Test the load command manually:
  4. Check if stack is initialized:

​
Kernle command not found

Ensure Kernle is installed and in PATH:

​
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: