Claude Code

Give Claude Code long-term memory that survives context wipes, session restarts, and ctrl+c. Claude remembers what you’re working on, your preferences, and what it was doing across all your projects.

Quick Start

Step 1: Get Your Honcho API Key

Go to app.honcho.dev
Sign up or log in
Copy your API key (starts with hch-)

Step 2: Set Environment Variables

Add these to your shell config (~/.zshrc, ~/.bashrc, or ~/.profile):

# Required
export HONCHO_API_KEY="hch-your-api-key-here"

# Optional (defaults shown)
export HONCHO_PEER_NAME="$USER"           # Your name/identity

Then reload your shell:

source ~/.zshrc  # or ~/.bashrc

Step 3: Install the Plugin

This plugin requires Bun. If you don’t have it: curl -fsSL https://bun.sh/install | bash

Open Claude Code and run:

/plugin marketplace add plastic-labs/claude-honcho

Then install:

/plugin install honcho@honcho

Step 4: Restart Claude Code

# Exit Claude Code (ctrl+c or /exit)
# Start it again
claude

That’s it! You should see the Honcho pixel art and memory loading on startup.

Step 5: (Optional) Kickstart with an Interview

/honcho:interview

Claude will interview you about your personal preferences to kickstart a representation of you. What it learns will be saved in Honcho and remembered forever. The interview is specific to the peer name you chose — it carries across different projects!

What You Get

Persistent Memory — Claude remembers your preferences, projects, and context across sessions
Survives Context Wipes — Even when Claude’s context window resets, memory persists
Git Awareness — Detects branch switches, commits, and changes made outside Claude
Flexible Sessions — Map sessions per directory, per git branch, or per chat instance
AI Self-Awareness — Claude knows what it was working on, even after restarts
Cross-Tool Context — Link workspaces across Claude Code, Cursor, and other hosts so context flows between tools
Team Support — Multiple people can share a workspace and build context together
MCP Tools — Search memory, query knowledge about you, and save insights

Configuration

All configuration lives in a single global file at ~/.honcho/config.json. You can edit it directly, use the /honcho:config skill interactively, or use the set_config MCP tool. Environment variables work for initial setup but the config file takes precedence once it exists.

{
  // Required
  "apiKey": "hch-v2-...",

  // Identity
  "peerName": "alice",              // Your name (default: $USER)

  // Host-specific settings — each tool gets its own workspace and AI peer
  "hosts": {
    "claude_code": {
      "workspace": "claude_code",   // Workspace for Claude Code sessions
      "aiPeer": "claude",           // AI identity in this workspace
      "linkedHosts": ["cursor"]     // Read context from other hosts (optional)
    },
    "cursor": {
      "workspace": "cursor",
      "aiPeer": "cursor"
    }
  },

  // Session mapping
  "sessionStrategy": "per-directory", // "per-directory" | "git-branch" | "chat-instance"
  "sessionPeerPrefix": true,          // Prefix session names with peerName (default: true)

  // Message handling
  "saveMessages": true,
  "messageUpload": {
    "maxUserTokens": null,            // Truncate user messages (null = no limit)
    "maxAssistantTokens": null,       // Truncate assistant messages (null = no limit)
    "summarizeAssistant": false       // Summarize instead of sending full assistant text
  },

  // Context retrieval
  "contextRefresh": {
    "messageThreshold": 30,           // Refresh context every N messages
    "ttlSeconds": 300,                // Cache TTL for context
    "skipDialectic": false            // Skip dialectic chat() calls in user-prompt hook
  },

  // Endpoint
  "endpoint": {
    "environment": "production"       // "production" | "local"
    // or: "baseUrl": "http://your-server:8000/v3"
  },

  // Miscellaneous
  "localContext": { "maxEntries": 50 },
  "enabled": true,
  "logging": true,

  // Advanced: force all hosts to use the same workspace
  "globalOverride": false
}

Session Strategies

Session strategy controls how Honcho maps your conversations to sessions:

Strategy	Behavior	Best for
`per-directory` (default)	One session per project directory. Stable across restarts.	Most users — each project accumulates its own memory
`git-branch`	Session name includes the current git branch. Switching branches switches sessions.	Feature-branch workflows where context per branch matters
`chat-instance`	Each Claude Code chat gets its own session. No continuity between restarts.	Ephemeral usage or when you want a clean slate each time

Session names are prefixed with your peerName by default (e.g., alice-my-project). Set sessionPeerPrefix: false if you’re the only user and want shorter names.

Host-Aware Configuration

The plugin auto-detects which tool is running it (Claude Code, Cursor, etc.) and reads the matching block from hosts. Each host gets its own workspace and AI peer name, so data stays separated by default. Host detection priority:

HONCHO_HOST env var (explicit override)
cursor_version in hook stdin (Cursor detected)
CURSOR_PROJECT_DIR env var (Cursor child process)
Default: claude_code

Linking Hosts for Cross-Tool Context

If you use both Claude Code and Cursor, you can link them so context from one is readable in the other. Writes always stay in the current host’s workspace — linking only adds read access.

{
  "hosts": {
    "claude_code": {
      "workspace": "claude_code",
      "aiPeer": "claude",
      "linkedHosts": ["cursor"]  // Claude Code can read Cursor's context
    },
    "cursor": {
      "workspace": "cursor",
      "aiPeer": "cursor",
      "linkedHosts": ["claude_code"]  // Cursor can read Claude Code's context
    }
  }
}

Or use /honcho:config and select Workspace > Linking to set this up interactively.

Global Override

If you want all hosts to share a single workspace (instead of per-host isolation), set globalOverride: true and a flat workspace field:

{
  "globalOverride": true,
  "workspace": "shared",
  "hosts": {
    "claude_code": { "aiPeer": "claude" },
    "cursor": { "aiPeer": "cursor" }
  }
}

All tools will read and write to the shared workspace. Each tool still uses its own AI peer name.

Building with Teammates

Multiple people can share context by pointing to the same workspace. Each person uses their own peerName as identity, and sessions are automatically prefixed with it to avoid collisions. Person A (~/.honcho/config.json):

{
  "apiKey": "hch-v2-team-key...",
  "peerName": "alice",
  "hosts": {
    "claude_code": {
      "workspace": "team-acme",
      "aiPeer": "claude"
    }
  }
}

Person B (~/.honcho/config.json):

{
  "apiKey": "hch-v2-team-key...",
  "peerName": "bob",
  "hosts": {
    "claude_code": {
      "workspace": "team-acme",
      "aiPeer": "claude"
    }
  }
}

Both Alice and Bob write to the team-acme workspace. Their sessions are namespaced (e.g., alice-my-project, bob-my-project) so data doesn’t collide, but Honcho’s dialectic reasoning can draw on context from both users.

Logging

The plugin logs activity to ~/.honcho/ and to Claude Code’s verbose mode, so you can see exactly how Honcho is being used — what context is loaded at session start, what messages are saved, and what context is injected into Claude’s prompts. Set logging to false in your config (or HONCHO_LOGGING=false) to disable file logging.

MCP Tools

The plugin provides these tools via MCP:

Tool	Description
`search`	Semantic search across session messages
`chat`	Query Honcho’s knowledge about the user
`create_conclusion`	Save insights about the user to memory
`get_config`	View current configuration and status
`set_config`	Change any configuration field programmatically

Skills (Slash Commands)

Command	Description
`/honcho:status`	Show current memory status and connection info
`/honcho:config`	Interactive configuration menu
`/honcho:setup`	First-time setup — validate API key and create config
`/honcho:interview`	Interview to capture stable, cross-project user preferences

The Interview

The /honcho:interview skill conducts a short interview to learn stable, cross-project aspects about you:

Communication style — Concise answers, detailed explanations, or a mix
Tone — Direct and professional or conversational
Structure — Bullet points, step-by-step, or narrative
Technical depth — Beginner, intermediate, or expert
Code quality focus — Clarity, performance, tests, or minimal changes
Collaboration style — Make changes directly, propose options, or ask first

Each answer is saved as a conclusion in Honcho memory and persists across all your projects.

Environment Variables

Environment variables work for initial bootstrap (before a config file exists). Once ~/.honcho/config.json is written, the config file takes precedence for host-specific fields like workspace.

Variable	Required	Default	Description
`HONCHO_API_KEY`	Yes	—	Your Honcho API key from app.honcho.dev
`HONCHO_PEER_NAME`	No	`$USER`	Your identity in the memory system
`HONCHO_WORKSPACE`	No	`claude_code`	Workspace name (used only when no config file exists)
`HONCHO_AI_PEER`	No	`claude`	AI peer name
`HONCHO_HOST`	No	auto-detected	Force host detection: `claude_code`, `cursor`, or `obsidian`
`HONCHO_ENDPOINT`	No	`production`	`production`, `local`, or a full URL
`HONCHO_ENABLED`	No	`true`	Set to `false` to disable
`HONCHO_SAVE_MESSAGES`	No	`true`	Set to `false` to stop saving messages
`HONCHO_LOGGING`	No	`true`	Set to `false` to disable file logging to `~/.honcho/`

Using a local Honcho instance

Via config file:

{ "endpoint": { "environment": "local" } }

Or via env var:

export HONCHO_ENDPOINT="local"  # Uses http://localhost:8000/v3

Using Honcho with Claude Desktop

You can also use Honcho with the Claude Desktop app via MCP. This lets Claude manage its own memory in the native desktop experience.

Step 1: Get Your API Key

Get an API key from app.honcho.dev.

Step 2: Configure Claude Desktop

This requires Node.js. Claude Desktop or Claude Code can help you install it!

Navigate to Claude Desktop’s custom MCP servers settings and add Honcho:

{
  "mcpServers": {
    "honcho": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.honcho.dev",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "--header",
        "X-Honcho-User-Name:${USER_NAME}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <your-honcho-key>",
        "USER_NAME": "<your-name>"
      }
    }
  }
}

Optional customization — You can also set a custom assistant name and workspace ID:

{
  "mcpServers": {
    "honcho": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.honcho.dev",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "--header",
        "X-Honcho-User-Name:${USER_NAME}",
        "--header",
        "X-Honcho-Assistant-Name:${ASSISTANT_NAME}",
        "--header",
        "X-Honcho-Workspace-ID:${WORKSPACE_ID}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <your-honcho-key>",
        "USER_NAME": "<your-name>",
        "ASSISTANT_NAME": "<your-assistant-name>",
        "WORKSPACE_ID": "<your-custom-workspace-id>"
      }
    }
  }
}

Step 3: Restart Claude Desktop

Upon relaunch, Honcho should start and the tools will be available.

Step 4: Add Instructions

The Desktop app doesn’t allow system prompts directly, but you can create a project and paste these instructions into the “Project Instructions” field. Claude will then query for insights before responding and write your messages to storage!

Overview

Integrations

Migrations

Chatbots

Quick Start

Step 1: Get Your Honcho API Key

Step 2: Set Environment Variables

Step 3: Install the Plugin

Step 4: Restart Claude Code

Step 5: (Optional) Kickstart with an Interview

What You Get

Configuration

Session Strategies

Host-Aware Configuration

Linking Hosts for Cross-Tool Context

Global Override

Building with Teammates

Logging

MCP Tools

Skills (Slash Commands)

The Interview

Environment Variables

Using a local Honcho instance

Using Honcho with Claude Desktop

Step 1: Get Your API Key

Step 2: Configure Claude Desktop

Step 3: Restart Claude Desktop

Step 4: Add Instructions

Next Steps

GitHub Repository

Honcho Architecture

Overview

Integrations

Migrations

Chatbots

​Quick Start

​Step 1: Get Your Honcho API Key

​Step 2: Set Environment Variables

​Step 3: Install the Plugin

​Step 4: Restart Claude Code

​Step 5: (Optional) Kickstart with an Interview

​What You Get

​Configuration

​Session Strategies

​Host-Aware Configuration

​Linking Hosts for Cross-Tool Context

​Global Override

​Building with Teammates

​Logging

​MCP Tools

​Skills (Slash Commands)

​The Interview

​Environment Variables

​Using a local Honcho instance

​Using Honcho with Claude Desktop

​Step 1: Get Your API Key

​Step 2: Configure Claude Desktop

​Step 3: Restart Claude Desktop

​Step 4: Add Instructions

​Next Steps

GitHub Repository

Honcho Architecture

Quick Start

Step 1: Get Your Honcho API Key

Step 2: Set Environment Variables

Step 3: Install the Plugin

Step 4: Restart Claude Code

Step 5: (Optional) Kickstart with an Interview

What You Get

Configuration

Session Strategies

Host-Aware Configuration

Linking Hosts for Cross-Tool Context

Global Override

Building with Teammates

Logging

MCP Tools

Skills (Slash Commands)

The Interview

Environment Variables

Using a local Honcho instance

Using Honcho with Claude Desktop

Step 1: Get Your API Key

Step 2: Configure Claude Desktop

Step 3: Restart Claude Desktop

Step 4: Add Instructions

Next Steps