Claude Code

Add AI-native memory to 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

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

Then reload your shell:

source ~/.zshrc  # or ~/.bashrc

Step 3: Install the Plugin

This plugin requires Node.js on your PATH.

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
• Configurable Memory Injection — Choose exactly what context is injected at session start and per turn
• 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
• Secret Redaction — Built-in patterns (plus your own) scrub secrets from tool summaries before upload
• 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
    },
    "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,
  "saveToolUse": false,               // Save [Tool] action summaries (default: false)
  "saveGitEvents": false,             // Save [Git External] state-change events (default: false)
  "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
  },
  "reasoningLevel": "medium",         // Default dialectic reasoning tier: "minimal" | "low" | "medium" | "high" | "max"

  // Memory injection (see "Memory Injection" below)
  "injection": {
    "sessionStart": ["directives", "summary", "peerCard"],
    "perTurn": ["userContext"]
  },

  // On-demand recall tool (see "The honcho_remember Tool" below)
  "rememberTool": false,

  // Observation mode
  "observationMode": "unified",       // "unified" (default) | "directional"

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

  // Miscellaneous
  "redactPatterns": [],               // Extra regexes redacted from tool summaries (additive to built-in secret patterns)
  "statusline": "on",                 // Memory statusline visibility: "on" | "off"
  "enabled": true,
  "logging": true,

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

Memory Injection

The injection config block controls exactly what memory is injected into Claude’s context, on two surfaces: once at session start and per prompt. Each surface selects zero or more components; retrieval knobs shape what those components emit.

Configure it interactively with /honcho:config (under the memory injection settings), by asking Claude to use set_config, or by editing ~/.honcho/config.json directly.

Session-Start Components

Injected once when a session opens. Default: ["directives", "summary", "peerCard"].

Component	What it injects
directives	Static memory-usage guidance — tells Claude to treat injected memory as background, use chat/search for recall, and save insights with create_conclusion
summary	The session’s long summary narrative (skipped on a fresh session)
peerCard	Your peer card — a structured identity/attribute list
peerRepresentation	Your full derived representation, injected at full length
briefing	A nudge for Claude to call the get_briefing MCP tool instead of injecting the summary and peer card inline. The tool call renders as an expandable row in the UI, so you can see exactly what was loaded. Use it in place of summary/peerCard, not alongside them

{ "injection": { "sessionStart": ["directives", "briefing"] } }

Per-Turn Components

Injected with each non-trivial prompt. Default: ["userContext"].

Component	What it injects
userContext	A fresh, prompt-scoped context fetch for you — conclusions selected by semantic search over your representation, shaped by the retrieval knobs below
assistantContext	The same context fetch, but for the AI peer — what Honcho has derived about the assistant itself
sessionContext	Recent raw messages from the currently mapped Honcho session, which can span other Claude instances sharing the session name
dialectic	A reasoned chat() answer over your representation, seeded from dialecticTemplate. Off by default — it is much slower than a context fetch, so it runs on its own time budget

Retrieval Knobs

Field	Default	Description
searchTopK	10	Top-K conclusions pulled by the context fetch’s semantic search
maxConclusions	15	Max conclusions injected per context fetch
searchMaxDistance	0.6	Max cosine distance for the semantic search — lower is stricter
searchQuerySource	"prompt"	What drives the per-turn search: the raw "prompt" or extracted "topics"
sessionContextTokens	1500	Token budget for the sessionContext message fetch
dialecticTemplate	compact factual recall	Query template for the dialectic component; the user’s prompt is substituted into %{user_query}
dialecticReasoning	"medium"	Reasoning tier for the per-turn dialectic call — kept separate from the top-level reasoningLevel so per-turn dialectic can stay cheap

If injected context feels off-topic, lower searchMaxDistance (stricter relevance); if it feels too sparse, raise it or bump searchTopK.

Injection Visibility

By default, per-turn components report a one-line summary in the terminal instead of printing their full contents. To see exactly what a component injects, list it in showContents:

{ "injection": { "showContents": ["userContext", "sessionContext"] } }

Components not listed still inject — they just stay quiet about it.

The honcho_remember Tool

An experimental on-demand recall tool. When enabled, Claude gets a honcho_remember MCP tool that fans out up to 5 parallel dialectic queries about you and returns per-question answers — useful before starting a task, when catching up (“where were we?”), or whenever your history could shape the response.

To enable it, just ask Claude: “Set my Honcho rememberTool config to true” (it uses the set_config tool). Or set it in ~/.honcho/config.json:

{
  "hosts": {
    "claude_code": { "rememberTool": true }
  }
}

Then restart Claude Code — MCP tools register at startup.

When it’s on, the injected session-start directives steer Claude to use it proactively as the primary recall path.

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.

Linked git worktrees resolve to their main repository’s session, so a worktree shares memory with the repo it belongs to.

Observation Mode

Controls how Honcho stores and retrieves conclusions about you. Change it via set_config or edit config.json directly. Requires a Claude Code restart.

Mode	Behavior	Best for
unified (default)	All agents write to your self-observation collection (observer=you, observed=you). Conclusions are portable — switch between agents without losing memory.	Most users — a unified context hub across agents
directional	Each AI peer keeps its own separate view of you (observer=aiPeer, observed=you).	Multi-peer workspaces where you want isolated per-agent representations

Switching modes doesn’t automatically migrate existing conclusions — each mode reads from a different collection. The plugin repository ships a migrate-observations.py script to copy conclusions between collections.

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:

1. HONCHO_HOST env var (explicit override)
2. cursor_version in hook stdin (Cursor detected)
3. CURSOR_PROJECT_DIR env var (Cursor child process)
4. Default: claude_code

Each host block can also carry its own apiKey (useful when different tools authenticate against different Honcho orgs) and override most settings — sessionStrategy, injection, rememberTool, observationMode, and more.

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.

Secret Redaction

Tool-capture summaries are scrubbed against built-in secret patterns (API keys, tokens, credentials) before upload. Add your own patterns with redactPatterns — an array of regexes applied on top of the defaults:

{ "redactPatterns": ["internal-[a-z0-9]+", "ACME_SECRET_\\w+"] }

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 and saved conclusions
chat	Query Honcho’s knowledge about the user (dialectic reasoning)
create_conclusion	Save insights about the user to memory
list_conclusions	List saved conclusions
query_conclusions	Semantic search over saved conclusions
delete_conclusion	Delete a conclusion by ID
get_briefing	Load the session briefing: session summary + peer card
get_context	Retrieve the full context object (representation + peer card)
get_representation	Retrieve the user’s representation string
get_config	View current configuration and status
set_config	Change any configuration field programmatically
honcho_remember	Fan-out dialectic recall (only registered when rememberTool: true)

Skills (Slash Commands)

Command	Description
/honcho:status	Show current memory status and connection info
/honcho:config	Interactive configuration menu (including memory injection settings)
/honcho:setup	First-time setup — validate API key and create config
/honcho:interview	Interview to capture stable, cross-project user preferences
/honcho:briefing	Load the session briefing via a visible tool call
/honcho:import	Backfill past Claude Code sessions into Honcho memory
/honcho:insights	Distill memory into CLAUDE.md edits, style rules, and skill ideas

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_SAVE_TOOL_USE	No	false	Set to true to save tool action summaries
HONCHO_SAVE_GIT_EVENTS	No	false	Set to true to save external git state-change events
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!

---

Next Steps

GitHub Repository

Source code, issues, and README.

Honcho Architecture

Learn about peers, sessions, and dialectic reasoning.