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
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.
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.
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 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 |
- 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 |
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
General MCP Configuration
For clients that use a JSON configuration file:
{
"mcpServers": {
"kernle": {
"command": "kernle",
"args": ["-s", "<stack_id>", "mcp"]
}
}
}
<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
- 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.
