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