Skip to main content
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

  1. Go to app.honcho.dev
  2. Sign up or log in
  3. 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
export HONCHO_WORKSPACE="claude_code"     # Workspace name
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
  • Per-Project Sessions — Each directory has its own conversation history
  • AI Self-Awareness — Claude knows what it was working on, even after restarts
  • MCP Tools — Search memory, query knowledge about you, and save insights

​
MCP Tools

The plugin provides these tools via MCP:
ToolDescription
searchSemantic search across session messages
chatQuery Honcho’s knowledge about the user
create_conclusionSave insights about the user to memory

​
Environment Variables Reference

VariableRequiredDefaultDescription
HONCHO_API_KEYYes—Your Honcho API key from app.honcho.dev
HONCHO_PEER_NAMENo$USERYour identity in the memory system
HONCHO_WORKSPACENoclaude_codeWorkspace name (groups your sessions)
HONCHO_CLAUDE_PEERNoclaudeHow the AI is identified
HONCHO_ENDPOINTNoproductionproduction, local, or a custom URL
HONCHO_ENABLEDNotrueSet to false to disable
HONCHO_SAVE_MESSAGESNotrueSet to false to stop saving messages

​
Skills (Slash Commands)

CommandDescription
/honcho:statusShow current memory status and configuration
/honcho:interviewInterview 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.

​
Using a local Honcho instance

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!

​
Next Steps

GitHub Repository

Source code, issues, and README.

Honcho Architecture

Learn about peers, sessions, and dialectic reasoning.