MCP Integration

Kernle provides an MCP (Model Context Protocol) server that exposes memory operations as tools for AI assistants.

What is MCP?

MCP is a protocol that allows AI assistants to use external tools. When you add Kernle as an MCP server, your AI assistant gains access to memory operations like:

Loading working memory
Saving checkpoints
Recording episodes and notes
Searching memory
Managing beliefs and values

Starting the MCP Server

kernle -s <stack_id> mcp

This starts an MCP server using stdio transport. The server stays running and responds to tool calls from the connected client.

How Memory Works via MCP

MCP provides a protocol for AI assistants to call external tools. Kernle exposes its full memory API as MCP tools. Any MCP-compatible client — Claude Code, Claude Desktop, Cursor, custom agents — can use Kernle memory through standard tool calls.

All Memory Handling is Manual

There is no automatic memory loading or saving. The client SI must call tools explicitly at each stage: Session start — Call memory_load to restore context. This returns values, beliefs, goals, episodes, notes, checkpoint, and relationships, priority-ordered within the token budget. Without this call, the SI starts with no memory context. During the session — Call capture tools (memory_episode, memory_note, memory_raw, etc.) as the SI works. Each call immediately persists to the local SQLite database. Nothing is buffered or batched. Session end — Call memory_checkpoint_save to record what the SI was working on, pending items, and context for next time. This checkpoint is loaded first on the next memory_load. Search — memory_search runs semantic search across all memory types. memory_raw_search uses FTS5 for keyword search on raw entries. Processing — memory_process runs automated memory processing (raw entries to episodes to beliefs to values) using the bound inference model. memory_process_status shows what is pending.

What the MCP Server Does NOT Do

Does not auto-load memory at connection time
Does not auto-save when the client disconnects
Does not run background maintenance or processing
Does not push notifications about memory state

The server is purely reactive — it waits for tool calls and executes them.

Immediate Persistence Model

Every memory_* capture tool writes directly to the SQLite database on call. If the client crashes after calling memory_episode but before memory_checkpoint_save, the episode is still saved — only the checkpoint summary is lost. This means partial sessions are never completely lost; whatever was captured before the interruption remains in the database.

Relationship to Native Memory Systems

Kernle works alongside whatever native memory your MCP client already provides. It does not require exclusive access.

Claude Code

Claude Code has two native memory mechanisms: CLAUDE.md files (static project instructions loaded at session start) and auto-memory (~/.claude/projects/.../memory/MEMORY.md, simple text notes the agent writes during sessions). Kernle provides structured, typed memory with provenance, strength decay, hierarchy, and search — capabilities that flat text files cannot offer. CLAUDE.md is still the right place for static project instructions. Auto-memory can coexist with Kernle — some users keep auto-memory for quick project notes and use Kernle for the full stratified memory system.

Claude Desktop

Claude Desktop has Projects with pinned knowledge files (static documents). It has no persistent dynamic memory between conversations. Kernle fills the gap entirely, giving the assistant memory that survives across conversations. See the Claude Desktop guide for setup.

Other MCP Clients (Cursor, Custom Agents)

Kernle provides the complete memory layer. Whatever native memory the client has can coexist — Kernle does not require exclusive access and does not interfere with other memory systems.

Available Tools

When connected, the MCP server exposes these tools:

Core Memory Operations

Tool	Description
`memory_load`	Load working memory with priority-based budget allocation
`memory_checkpoint_save`	Save checkpoint with task description
`memory_checkpoint_load`	Load previous checkpoint
`memory_status`	Get memory statistics
`memory_sync`	Trigger synchronization with cloud storage

memory_load Tool Details

The memory_load tool uses priority-based budget allocation to load the most important memories within token limits. Parameters:

Parameter	Type	Default	Description
`format`	string	`"text"`	Output format: `"text"` or `"json"`
`budget`	integer	`8000`	Token budget (100-50000)
`truncate`	boolean	`true`	Truncate long content to fit more items

Priority Ordering: Memories are loaded by priority until the budget is exhausted:

Checkpoint (1.00) - Always loaded first for task continuity
Values (0.90) - Sorted by priority descending
Beliefs (0.70) - Sorted by confidence descending
Goals (0.65) - Sorted by recency
Drives (0.60) - Sorted by intensity descending
Episodes (0.40) - Sorted by recency
Notes (0.35) - Sorted by recency
Relationships (0.30) - Sorted by last interaction

Response Metadata (_meta): When using JSON format, the response includes budget metrics:

{
  "_meta": {
    "budget_used": 5200,
    "budget_total": 8000,
    "excluded_count": 12
  }
}

Field	Description
`budget_used`	Tokens consumed by loaded memories
`budget_total`	Original budget requested
`excluded_count`	Number of memories that could not fit

Token Estimation: Tokens are estimated at approximately 4 characters per token, with a 1.3x safety margin for JSON serialization overhead. Access Tracking: Loading memories automatically records access for salience-based forgetting. This helps Kernle identify frequently-used memories that should be preserved.

Memory Capture

Tool	Description
`memory_episode`	Record an experience with lessons
`memory_note`	Capture a note (decision/insight/quote)
`memory_raw`	Quick capture to raw layer
`memory_value`	Define core values
`memory_goal`	Set and manage goals
`memory_drive`	Set or update drives (motivations)

Playbooks are currently available via CLI only. MCP tools for playbook operations are planned for a future release.

Search & Query

Tool	Description
`memory_search`	Semantic search across all memory
`memory_raw_search`	FTS5 keyword search on raw entries
`memory_note_search`	Search notes by content and type
`memory_when`	Query memories by time period (today, yesterday, this week)
`memory_promote`	Get reflection scaffold with recent episodes and beliefs

Processing

Tool	Description
`memory_process`	Run automated memory processing through hierarchy layers
`memory_process_status`	Check status of memory processing

List Operations

Tool	Description
`memory_belief_list`	List all active beliefs with confidence levels
`memory_value_list`	List all core values ordered by priority
`memory_goal_list`	List goals filtered by status
`memory_drive_list`	List all drives with current intensities

Update Operations

Tool	Description
`memory_episode_update`	Update an episode (add lessons, change outcome, add tags)
`memory_goal_update`	Update a goal’s status, priority, or description
`memory_belief_update`	Update a belief’s confidence or deactivate it

Suggestions

Tool	Description
`suggestion_list`	List and filter memory suggestions by status, type, confidence, age
`suggestion_accept`	Accept a suggestion and create structured memory (with optional modifications)
`suggestion_dismiss`	Dismiss a suggestion with an optional reason
`suggestion_extract`	Extract suggestions from unprocessed raw entries

Client Configuration

Claude Code

Add Kernle as an MCP server using the Claude CLI:

claude mcp add kernle -- kernle -s <stack_id> mcp

This registers Kernle with Claude Code. You can verify with:

claude mcp list

General MCP Configuration

For clients that use a JSON configuration file:

{
  "mcpServers": {
    "kernle": {
      "command": "kernle",
      "args": ["-s", "<stack_id>", "mcp"]
    }
  }
}

Replace <stack_id> with your actual stack identifier.

Usage Example

Once configured, your AI assistant can use memory tools naturally:

"Let me save my current progress..."
→ Tool call: memory_checkpoint_save(task="Working on user auth")

"What have I learned about caching?"
→ Tool call: memory_search(query="caching")

"I should remember this insight about rate limiting."
→ Tool call: memory_note(content="Rate limits are per-user, not per-key", type="insight")

Best Practices

Session Start: Always call memory_load at the beginning of a session to restore context.

Save Often: Use memory_checkpoint_save before context gets full, not just at session end.

Record Lessons: Use memory_episode with lessons when you learn something significant.

Troubleshooting

Server Not Starting

Verify Kernle is installed and accessible:

which kernle
kernle --version

Tools Not Appearing

Restart your MCP client
Check the MCP configuration path
Verify the stack ID exists: kernle -s <stack_id> status

Permission Issues

The MCP server runs with the same permissions as your user. Ensure ~/.kernle/ is accessible.

Getting Started

Core Concepts

Protocol System

Advanced Features

Developer Tools

CLI Reference

Integration

Design

Troubleshooting

MCP Integration

MCP Integration

What is MCP?

Starting the MCP Server

How Memory Works via MCP

All Memory Handling is Manual

What the MCP Server Does NOT Do

Immediate Persistence Model

Relationship to Native Memory Systems

Claude Code

Claude Desktop

Other MCP Clients (Cursor, Custom Agents)

Available Tools

Core Memory Operations

memory_load Tool Details

Memory Capture

Search & Query

Processing

List Operations

Update Operations

Suggestions

Client Configuration

Claude Code

General MCP Configuration

Usage Example

Best Practices

Troubleshooting

Server Not Starting

Tools Not Appearing

Permission Issues

​MCP Integration

​What is MCP?

​Starting the MCP Server

​How Memory Works via MCP

​All Memory Handling is Manual

​What the MCP Server Does NOT Do

​Immediate Persistence Model

​Relationship to Native Memory Systems

​Claude Code

​Claude Desktop

​Other MCP Clients (Cursor, Custom Agents)

​Available Tools

​Core Memory Operations

​memory_load Tool Details

​Memory Capture

​Search & Query

​Processing

​List Operations

​Update Operations

​Suggestions

​Client Configuration

​Claude Code

​General MCP Configuration

​Usage Example

​Best Practices

​Troubleshooting

​Server Not Starting

​Tools Not Appearing

​Permission Issues

MCP Integration

What is MCP?

Starting the MCP Server

How Memory Works via MCP

All Memory Handling is Manual

What the MCP Server Does NOT Do

Immediate Persistence Model

Relationship to Native Memory Systems

Claude Code

Claude Desktop

Other MCP Clients (Cursor, Custom Agents)

Available Tools

Core Memory Operations

memory_load Tool Details

Memory Capture

Search & Query

Processing

List Operations

Update Operations

Suggestions

Client Configuration

Claude Code

General MCP Configuration

Usage Example

Best Practices

Troubleshooting

Server Not Starting

Tools Not Appearing

Permission Issues