> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kernle.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Desktop

> Setting up Kernle with Claude Desktop

# 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

<Tabs>
  <Tab title="macOS">
    ```
    ~/Library/Application Support/Claude/claude_desktop_config.json
    ```
  </Tab>

  <Tab title="Windows">
    ```
    %APPDATA%\Claude\claude_desktop_config.json
    ```
  </Tab>

  <Tab title="Linux">
    ```
    ~/.config/Claude/claude_desktop_config.json
    ```
  </Tab>
</Tabs>

## Configuration

Add Kernle to the `mcpServers` section:

```json theme={null}
{
  "mcpServers": {
    "kernle": {
      "command": "kernle",
      "args": ["mcp", "--stack", "my-project"]
    }
  }
}
```

<Warning>
  Replace `my-project` with your preferred stack ID. This ID identifies your memory store.
</Warning>

### Full Configuration Example

```json theme={null}
{
  "mcpServers": {
    "kernle": {
      "command": "kernle",
      "args": ["mcp", "--stack", "my-project"]
    }
  }
}
```

### With Python Path (if needed)

If Kernle was installed via pip in a specific environment:

```json theme={null}
{
  "mcpServers": {
    "kernle": {
      "command": "/path/to/python",
      "args": ["-m", "kernle", "mcp", "--stack", "my-project"]
    }
  }
}
```

Or with pipx:

```json theme={null}
{
  "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:

| Tool                     | What It Does                                 |
| ------------------------ | -------------------------------------------- |
| `memory_load`            | Restore working memory at conversation start |
| `memory_checkpoint_save` | Save current state                           |
| `memory_episode`         | Record an experience with lessons            |
| `memory_note`            | Capture notes, decisions, insights           |
| `memory_raw`             | Quick capture for later processing           |
| `memory_search`          | Search across all memory types               |
| `memory_anxiety`         | Check memory health                          |

## Recommended Workflow

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

```bash theme={null}
# Find the path
which kernle
```

Then use that path in the config.

### Permission Denied

Make sure the Kernle data directory exists and is writable:

```bash theme={null}
mkdir -p ~/.kernle
chmod 755 ~/.kernle
```

### Checking Logs

Claude Desktop logs may show MCP connection errors:

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    tail -f ~/Library/Logs/Claude/mcp.log
    ```
  </Tab>

  <Tab title="Windows">
    Check Event Viewer or `%APPDATA%\Claude\logs`
  </Tab>
</Tabs>

<Info>
  For Claude Code (the CLI), use the [Claude Code integration](/integration/claude-code) 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.
</Info>