Skip to main content

​
Claude Desktop Integration

Claude Desktop supports MCP servers through a configuration file. This guide shows you how to add Kernle as a memory tool.

​
Configuration File Location

~/Library/Application Support/Claude/claude_desktop_config.json

​
Configuration

Add Kernle to the mcpServers section: 
{
  "mcpServers": {
    "kernle": {
      "command": "kernle",
      "args": ["mcp", "--stack", "my-project"]
    }
  }
}
Replace my-project with your preferred stack ID. This ID identifies your memory store.

​
Full Configuration Example

{
  "mcpServers": {
    "kernle": {
      "command": "kernle",
      "args": ["mcp", "--stack", "my-project"]
    }
  }
}

​
With Python Path (if needed)

If Kernle was installed via pip in a specific environment: 
{
  "mcpServers": {
    "kernle": {
      "command": "/path/to/python",
      "args": ["-m", "kernle", "mcp", "--stack", "my-project"]
    }
  }
}
Or with pipx: 
{
  "mcpServers": {
    "kernle": {
      "command": "/Users/you/.local/bin/kernle",
      "args": ["mcp", "--stack", "my-project"]
    }
  }
}

​
Apply Configuration

  1. Save the configuration file
  2. Completely quit Claude Desktop (not just close the window)
  3. Restart Claude Desktop

​
Verify Installation

After restarting, you should see memory tools available. Try asking Claude:
“Can you check my memory status?”
Claude should call the memory_status tool and return your memory overview.

​
How Memory Works with Claude Desktop

Understanding what Claude Desktop provides on its own and what Kernle adds helps clarify why both exist and how they interact.

​
What Claude Desktop Provides Natively

  • Projects with pinned knowledge files. These are static documents (instructions, reference material, style guides) that get loaded into every conversation within that project. They do not change between conversations unless you manually edit them.
  • Conversation history within a single chat. Claude remembers everything said within one conversation thread. Scrolling up works normally.
  • No persistent memory between separate conversations. Each time you start a new conversation, Claude begins completely fresh. Nothing from the previous conversation carries over automatically.

​
What Kernle Adds

Kernle provides persistent memory that survives across conversations. When the SI calls memory_load, it receives values, beliefs, goals, episodes, notes, and a checkpoint from all previous conversations. When it calls memory_checkpoint_save, that state is available in the next conversation. This is the cross-conversation continuity that Claude Desktop does not have on its own.

​
What Coexists vs. What’s Replaced

Project knowledge files — still used. These are static instructions and reference context. Kernle does not replace them. They serve different purposes: knowledge files provide fixed configuration and context, while Kernle provides dynamic memory that evolves over time. Conversation history — still works. Claude Desktop’s in-conversation history functions normally within a single chat. Kernle adds cross-conversation persistence on top of this. Within a conversation, Claude still has full access to everything said earlier in that same thread. Claude’s internal “memory” feature (if enabled). Claude Desktop may offer its own memory feature that remembers facts across chats as flat notes. Kernle provides a more structured alternative: typed memories with provenance, strength decay, and semantic search instead of simple fact storage. Both can coexist, but Kernle is the primary memory system for SIs using the stratified memory model.

​
Memory Handling Steps

There is no automatic memory loading or saving. The SI must explicitly call MCP tools at each step. Nothing happens behind the scenes.
  • Session start. The SI should call memory_load to restore context from previous conversations. This pulls in values, beliefs, goals, episodes, notes, and the last checkpoint.
  • During the conversation. The SI calls memory_episode, memory_note, memory_raw, and other tools to capture memories as they arise. Each of these tool calls writes immediately to the memory store.
  • Session end. The SI should call memory_checkpoint_save to persist a summary of the current state for the next conversation.
  • If the SI forgets to load. The conversation proceeds without any cross-conversation context. No data is lost — it just is not loaded. The next conversation can still load everything.
  • If the SI forgets to save a checkpoint. Anything captured via memory_episode, memory_note, memory_raw, etc. during the conversation is already persisted, because each tool call writes immediately. Only the checkpoint summary is lost. The individual memories are still there.

​
Available Tools

Once connected, Claude Desktop has access to:
ToolWhat It Does
memory_loadRestore working memory at conversation start
memory_checkpoint_saveSave current state
memory_episodeRecord an experience with lessons
memory_noteCapture notes, decisions, insights
memory_rawQuick capture for later processing
memory_searchSearch across all memory types
memory_anxietyCheck memory health

​
Starting a Conversation

Ask Claude to load memory first:
“Please load your memory before we start.”
This restores context from previous conversations.

​
During Conversation

Claude can capture learnings as you work:
“Remember that the API rate limit is 100 requests per minute.”

​
Ending a Conversation

Ask Claude to save state:
“Please save a checkpoint before we wrap up.”

​
Troubleshooting

​
Tools Not Showing

  1. Check config file syntax (valid JSON)
  2. Verify file location is correct
  3. Ensure Kernle is in PATH: which kernle
  4. Fully restart Claude Desktop

​
”Command not found”

Use the full path to Kernle: 
# Find the path
which kernle
Then use that path in the config.

​
Permission Denied

Make sure the Kernle data directory exists and is writable: 
mkdir -p ~/.kernle
chmod 755 ~/.kernle

​
Checking Logs

Claude Desktop logs may show MCP connection errors: 
tail -f ~/Library/Logs/Claude/mcp.log
For Claude Code (the CLI), use the Claude Code integration instead — it provides a plugin with automatic memory loading, checkpointing, and native write interception. This page covers Claude Desktop (the GUI app), which uses MCP only.