400 lines
13 KiB
Plaintext
400 lines
13 KiB
Plaintext
---
|
|
title: "Claude Code"
|
|
icon: 'terminal'
|
|
description: "Add AI-native memory to Claude Code"
|
|
sidebarTitle: '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
|
|
# 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
|
|
source ~/.zshrc # or ~/.bashrc
|
|
```
|
|
|
|
### Step 3: Install the Plugin
|
|
|
|
<Note>
|
|
This plugin requires [Bun](https://bun.sh). If you don't have it: `curl -fsSL https://bun.sh/install | bash`
|
|
</Note>
|
|
|
|
Open Claude Code and run:
|
|
|
|
```
|
|
/plugin marketplace add plastic-labs/claude-honcho
|
|
```
|
|
|
|
Then install:
|
|
|
|
```
|
|
/plugin install honcho@honcho
|
|
```
|
|
|
|
### Step 4: Restart Claude Code
|
|
|
|
```bash
|
|
# 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
|
|
- **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
|
|
- **Cross-Tool Context** — Link workspaces across Claude Code, Cursor, and other hosts so context flows between tools
|
|
- **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
|
|
{
|
|
// 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
|
|
"linkedHosts": ["cursor"] // Read context from other hosts (optional)
|
|
},
|
|
"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,
|
|
"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
|
|
},
|
|
|
|
// Endpoint
|
|
"endpoint": {
|
|
"environment": "production" // "production" | "local"
|
|
// or: "baseUrl": "http://your-server:8000/v3"
|
|
},
|
|
|
|
// Miscellaneous
|
|
"localContext": { "maxEntries": 50 },
|
|
"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:
|
|
|
|
| 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.
|
|
|
|
### 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`
|
|
|
|
### Linking Hosts for Cross-Tool Context
|
|
|
|
If you use both Claude Code and Cursor, you can link them so context from one is readable in the other. Writes always stay in the current host's workspace — linking only adds read access.
|
|
|
|
```jsonc
|
|
{
|
|
"hosts": {
|
|
"claude_code": {
|
|
"workspace": "claude_code",
|
|
"aiPeer": "claude",
|
|
"linkedHosts": ["cursor"] // Claude Code can read Cursor's context
|
|
},
|
|
"cursor": {
|
|
"workspace": "cursor",
|
|
"aiPeer": "cursor",
|
|
"linkedHosts": ["claude_code"] // Cursor can read Claude Code's context
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Or use `/honcho:config` and select **Workspace > Linking** to set this up interactively.
|
|
|
|
### 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
|
|
{
|
|
"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
|
|
{
|
|
"apiKey": "hch-v2-team-key...",
|
|
"peerName": "alice",
|
|
"hosts": {
|
|
"claude_code": {
|
|
"workspace": "team-acme",
|
|
"aiPeer": "claude"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Person B** (`~/.honcho/config.json`):
|
|
```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.
|
|
|
|
## 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 |
|
|
| `chat` | Query Honcho's knowledge about the user |
|
|
| `create_conclusion` | Save insights about the user to memory |
|
|
| `get_config` | View current configuration and status |
|
|
| `set_config` | Change any configuration field programmatically |
|
|
|
|
## Skills (Slash Commands)
|
|
|
|
| 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 |
|
|
|
|
### 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_LOGGING` | No | `true` | Set to `false` to disable file logging to `~/.honcho/` |
|
|
|
|
### Using a local Honcho instance
|
|
|
|
Via config file:
|
|
```json
|
|
{ "endpoint": { "environment": "local" } }
|
|
```
|
|
|
|
Or via env var:
|
|
```bash
|
|
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
|
|
|
|
<Note>
|
|
This requires [Node.js](https://nodejs.org). Claude Desktop or Claude Code can help you install it!
|
|
</Note>
|
|
|
|
Navigate to Claude Desktop's custom MCP servers settings and add Honcho:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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](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
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="GitHub Repository" icon="github" href="https://github.com/plastic-labs/claude-honcho">
|
|
Source code, issues, and README.
|
|
</Card>
|
|
|
|
<Card title="Honcho Architecture" icon="sitemap" href="../../documentation/core-concepts/architecture">
|
|
Learn about peers, sessions, and dialectic reasoning.
|
|
</Card>
|
|
</CardGroup>
|