Honcho Plugins for Claude Code

A plugin marketplace for Claude Code, powered by Honcho from Plastic Labs.

Plugins

| Plugin | Description | | ------------------------------------ | ----------------------------------------------- | | honcho | Persistent memory for Claude Code sessions | | honcho-dev | Skills for building AI apps with the Honcho SDK |

Installation

Add the marketplace to Claude Code:

/plugin marketplace add plastic-labs/claude-honcho

Then install the plugin(s) you want:

/plugin install honcho@honcho
/plugin install honcho-dev@honcho

You'll need to restart Claude Code for the plugins to take effect. Follow the instructions below for setting up each plugin.

honcho Plugin

Persistent memory for Claude Code using Honcho.

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

Prerequisites

• A Honcho API key from app.honcho.dev
• Node.js on your PATH

The plugin ships as a self-contained bundle -- no other dependencies needed.

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

macOS / Linux -- 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

Windows (PowerShell) -- set a persistent user environment variable:

# Required
[Environment]::SetEnvironmentVariable("HONCHO_API_KEY", "hch-your-api-key-here", "User")

# Optional
[Environment]::SetEnvironmentVariable("HONCHO_PEER_NAME", $env:USERNAME, "User")
[Environment]::SetEnvironmentVariable("HONCHO_WORKSPACE", "claude_code", "User")

Then restart your terminal so the new variables take effect.

Step 3: Install the Plugin

/plugin marketplace add plastic-labs/claude-honcho
/plugin install honcho@honcho

Step 4: Restart Claude Code

# Exit Claude Code (ctrl+c or /exit)
# Start it again -- you should see the Honcho pixel art and memory loading on startup.
claude

Step 5: (Optional) Kick off your conversation with an interview

/honcho:interview

Claude will interview you about your personal preferences in order 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 in your environment: it will carry 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
• Configurable Memory Injection — Choose exactly what context is injected at session start and per turn
• Team Support — Multiple people can share a workspace and build context together
• MCP Tools — Search memory, query knowledge about you, and save insights

MCP Tools

The honcho 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

| 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 | | /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, skill ideas |

Configuration

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

Config File Reference

{
  // 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
}

Session Strategies

Session strategy controls how Honcho maps your conversations to sessions. Change it with /honcho:config or set_config:

| 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, experimentation, or when you want a clean slate each time |

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 with /honcho:config (memory injection settings), set_config, or by editing ~/.honcho/config.json.

Session-start components (default: ["directives", "summary", "peerCard"]):

| Component | What it injects | | --- | --- | | directives | Static memory-usage guidance — treat injected memory as background, use chat/search for recall, 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. Use it in place of summary/peerCard, not alongside them |

Per-turn components (default: ["userContext"]):

| Component | What it injects | | --- | --- | | userContext | A fresh, prompt-scoped context fetch for you — conclusions selected by semantic search, shaped by the retrieval knobs below | | assistantContext | The same context fetch 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 — much slower than a context fetch |

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 prompt is substituted into %{user_query} | | dialecticReasoning | "medium" | Reasoning tier for the per-turn dialectic call — separate from the top-level reasoningLevel |

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

Visibility: per-turn components report a one-line summary in the terminal by default. To print a component's full injected payload, list it in showContents:

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

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.

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 Claude, Hermes, or any agent without losing memory. | Most users, when you want to build a unified context hub, agent-switching | | directional | Each AI peer keeps its own separate view of you (observer=aiPeer, observed=you). Claude's observations stay with Claude, Hermes' with Hermes. | Multi-peer workspaces where you want isolated per-peer(agent) representations |

Peer defaults: The plugin does not explicitly set observeMe or observeOthers on peers — it uses the server-side defaults. If you want to change how a peer observes (e.g., disable self-observation), update the peer's defaults via API or on app.honcho.dev. The only override the plugin applies is observeOthers: true on the AI peer in directional mode.

To change:

• Ask Claude: "Set my observation mode to directional"
• Or edit ~/.honcho/config.json:

  { "observationMode": "directional" }

• Or per-host:

  {
    "hosts": {
      "claude_code": { "observationMode": "directional" }
    }
  }

Note: Switching modes doesn't automatically migrate existing conclusions. Each mode reads from a different collection. See Migrating Observations below to move conclusions between collections.

Migrating Observations

When switching observation modes, conclusions stored under the old mode's collection won't be visible to the new mode. Use the migration script to copy them over:

# Requires: pip install honcho-ai
# Set your API key: export HONCHO_API_KEY="hch-..."

# Dry run — see what would be migrated (directional → unified)
python scripts/migrate-observations.py \
  --workspace agents \
  --from-observer claude \
  --user ajspig \
  --dry-run

# Execute the migration
python scripts/migrate-observations.py \
  --workspace agents \
  --from-observer claude \
  --user ajspig

# Execute and delete the source conclusions after migration
python scripts/migrate-observations.py \
  --workspace agents \
  --from-observer claude \
  --user ajspig \
  --delete-source

The script:

• Reads all conclusions from the source collection (e.g., observer=claude, observed=ajspig)
• Deduplicates by content against the destination (e.g., observer=ajspig, observed=ajspig)
• Creates only the conclusions that don't already exist in the destination
• Handles rate limiting with automatic retries

To migrate in the other direction (unified → directional):

python scripts/migrate-observations.py \
  --workspace agents \
  --from-observer ajspig \
  --to-observer claude \
  --user ajspig

If you use multiple AI agents, run the script once per agent:

# Migrate Claude's observations to unified
python scripts/migrate-observations.py -w agents --from-observer claude --user ajspig

# Migrate Hermes' observations to unified
python scripts/migrate-observations.py -w agents --from-observer hermes --user ajspig

Run with --help for all options.

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:

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

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.

Team Setup with Shared Context

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. If you want fully independent sessions, set sessionPeerPrefix: false — but this is not recommended in shared workspaces.

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/ |

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                        Claude Code                              │
├─────────────────────────────────────────────────────────────────┤
│  SessionStart   │  UserPrompt     │  PostToolUse   │ SessionEnd │
│  ───────────    │  ───────────    │  ────────────  │ ────────── │
│  Load context   │  Save message   │  Log activity  │ Upload all │
│  from Honcho    │  to Honcho      │  to Honcho     │ + summary  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Honcho API                              │
│                                                                 │
│   Your messages and Claude's work → Persistent Memory →         │
│   Retrieved as context at session start                         │
└─────────────────────────────────────────────────────────────────┘

The plugin hooks into Claude Code's lifecycle events:

• SessionStart: Loads your context and history from Honcho
• UserPrompt: Saves your messages and retrieves relevant context
• PostToolUse: Logs Claude's actions (file edits, commands, etc.)
• PreCompact: Anchors a memory snapshot before context compaction so knowledge survives summarization
• Stop: Flushes any pending messages
• SessionEnd: Uploads remaining messages and generates a summary

Troubleshooting

"Not configured" or no memory loading

1. Check your API key is set:

   echo $HONCHO_API_KEY          # macOS / Linux
   echo $env:HONCHO_API_KEY      # Windows PowerShell

   If empty, set it (see Step 2 in Quick Start) and restart your terminal.

2. Check the plugin is installed:

   /plugin

   You should see honcho@honcho in the list.

3. Restart Claude Code after making changes.

4. Run /honcho:status to see connection state, workspace, and session info.

Memory not persisting between sessions

Make sure saveMessages is not set to false in your config (or HONCHO_SAVE_MESSAGES in env).

Using a local Honcho instance

Via config file:

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

Or via env var:

export HONCHO_ENDPOINT="local"  # Uses localhost:8000
# or
export HONCHO_ENDPOINT="http://your-server:8000/v3"

Temporarily disabling memory

export HONCHO_ENABLED="false"

Or set "enabled": false in your config file. Restart Claude Code to take effect.

honcho-dev Plugin

Skills for building AI applications with the Honcho SDK.

This plugin provides skills to help you integrate Honcho into your projects and migrate between SDK versions.

Skills

| Command | Description | | ------------------------ | -------------------------------------------------- | | /honcho-dev:integrate | Add Honcho memory to your project or bot framework | | /honcho-dev:migrate-py | Migrate Python code to the latest Honcho SDK | | /honcho-dev:migrate-ts | Migrate TypeScript code to the latest Honcho SDK |

Installation

/plugin install honcho-dev@honcho

Uninstalling

/plugin uninstall honcho@honcho
/plugin uninstall honcho-dev@honcho
/plugin marketplace remove honcho

Then remove the environment variables from your shell config if desired.

License

MIT — see LICENSE

Links

• Issues: GitHub Issues
• Discord: Join the Community
• X (Twitter): @honchodotdev
• Plastic Labs: plasticlabs.ai
• Honcho: honcho.dev — The memory API
• Documentation: docs.honcho.dev
• Blog: Read about Honcho, Agents, and Memory