> ## Documentation Index > Fetch the complete documentation index at: https://honcho.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://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`): ```bash theme={null} # 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: ```bash theme={null} source ~/.zshrc # or ~/.bashrc ``` ### Step 3: Install the Plugin This plugin requires [Node.js](https://nodejs.org) 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 ```bash theme={null} # 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. ```jsonc theme={null} { // 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 | ```json theme={null} { "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`: ```json theme={null} { "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`: ```json theme={null} { "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](https://github.com/plastic-labs/claude-honcho) 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: ```jsonc theme={null} { "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`): ```json theme={null} { "apiKey": "hch-v2-team-key...", "peerName": "alice", "hosts": { "claude_code": { "workspace": "team-acme", "aiPeer": "claude" } } } ``` **Person B** (`~/.honcho/config.json`): ```json theme={null} { "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: ```json theme={null} { "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](https://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: ```json theme={null} { "endpoint": { "environment": "local" } } ``` Or via env var: ```bash theme={null} 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](https://app.honcho.dev). ### Step 2: Configure Claude Desktop This requires [Node.js](https://nodejs.org). Claude Desktop or Claude Code can help you install it! Navigate to Claude Desktop's custom MCP servers settings and add Honcho: ```json theme={null} { "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 ", "USER_NAME": "" } } } } ``` **Optional customization** — You can also set a custom assistant name and workspace ID: ```json theme={null} { "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 ", "USER_NAME": "", "ASSISTANT_NAME": "", "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](https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md) into the "Project Instructions" field. Claude will then query for insights before responding and write your messages to storage! *** ## Next Steps Source code, issues, and README. Learn about peers, sessions, and dialectic reasoning.