@honcho-ai/claude-honcho 0.3.4 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +113 -333
- package/dist/hooks/save-user-message.js +1721 -1066
- package/dist/hooks/save-user-message.js.map +24 -19
- package/dist/hooks/session-end.js +556 -633
- package/dist/hooks/session-end.js.map +11 -9
- package/dist/hooks/session-start.js +1922 -1319
- package/dist/hooks/session-start.js.map +31 -22
- package/dist/hooks/stop.js +1742 -1160
- package/dist/hooks/stop.js.map +25 -20
- package/dist/hooks/user-prompt.js +689 -16616
- package/dist/hooks/user-prompt.js.map +13 -90
- package/dist/mcp-server.js +1595 -1612
- package/dist/mcp-server.js.map +23 -20
- package/dist/skills/backfill-runner.js +1816 -919
- package/dist/skills/backfill-runner.js.map +27 -21
- package/dist/skills/{setup-runner.js → pane-runner.js} +1902 -1030
- package/dist/{hooks/pre-compact.js.map → skills/pane-runner.js.map} +28 -24
- package/dist/skills/status-runner.js +1567 -761
- package/dist/skills/status-runner.js.map +23 -19
- package/hooks/hooks.json +4 -48
- package/hooks/register.tsx +576 -0
- package/package.json +1 -1
- package/skills/insights/SKILL.md +3 -7
- package/dist/hooks/post-tool-use.js +0 -16924
- package/dist/hooks/post-tool-use.js.map +0 -97
- package/dist/hooks/pre-compact.js +0 -17111
- package/dist/hooks/pre-tool-honcho.js +0 -869
- package/dist/hooks/pre-tool-honcho.js.map +0 -16
- package/dist/skills/setup-runner.js.map +0 -96
- package/scripts/honcho-statusline.sh +0 -101
- package/skills/briefing/SKILL.md +0 -20
- package/skills/config/SKILL.md +0 -288
- package/skills/import/SKILL.md +0 -73
- package/skills/setup/SKILL.md +0 -60
- package/skills/status/SKILL.md +0 -30
package/README.md
CHANGED
|
@@ -44,86 +44,44 @@ Give Claude Code long-term memory that survives context wipes, session restarts,
|
|
|
44
44
|
|
|
45
45
|
## Prerequisites
|
|
46
46
|
|
|
47
|
-
-
|
|
47
|
+
- Claude Code v2.1.287 or later
|
|
48
48
|
- [Node.js](https://nodejs.org) on your PATH
|
|
49
|
+
- A Honcho account at [app.honcho.dev](https://app.honcho.dev)
|
|
49
50
|
|
|
50
51
|
The plugin ships as a self-contained bundle -- no other dependencies needed.
|
|
51
52
|
|
|
52
53
|
## Quick Start
|
|
53
54
|
|
|
54
|
-
### Step 1:
|
|
55
|
-
|
|
56
|
-
1. Go to **[app.honcho.dev](https://app.honcho.dev)**
|
|
57
|
-
2. Sign up or log in
|
|
58
|
-
3. Copy your API key (starts with `hch-`)
|
|
59
|
-
|
|
60
|
-
### Step 2: Set Environment Variables
|
|
61
|
-
|
|
62
|
-
**macOS / Linux** -- add these to your shell config (`~/.zshrc`, `~/.bashrc`, or `~/.profile`):
|
|
63
|
-
|
|
64
|
-
```bash
|
|
65
|
-
# Required
|
|
66
|
-
export HONCHO_API_KEY="hch-your-api-key-here"
|
|
67
|
-
|
|
68
|
-
# Optional (defaults shown)
|
|
69
|
-
export HONCHO_PEER_NAME="$USER" # Your name/identity
|
|
70
|
-
export HONCHO_WORKSPACE="claude_code" # Workspace name
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
Then reload your shell:
|
|
74
|
-
|
|
75
|
-
```bash
|
|
76
|
-
source ~/.zshrc # or ~/.bashrc
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
**Windows (PowerShell)** -- set a persistent user environment variable:
|
|
80
|
-
|
|
81
|
-
```powershell
|
|
82
|
-
# Required
|
|
83
|
-
[Environment]::SetEnvironmentVariable("HONCHO_API_KEY", "hch-your-api-key-here", "User")
|
|
84
|
-
|
|
85
|
-
# Optional
|
|
86
|
-
[Environment]::SetEnvironmentVariable("HONCHO_PEER_NAME", $env:USERNAME, "User")
|
|
87
|
-
[Environment]::SetEnvironmentVariable("HONCHO_WORKSPACE", "claude_code", "User")
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
Then restart your terminal so the new variables take effect.
|
|
91
|
-
|
|
92
|
-
### Step 3: Install the Plugin
|
|
55
|
+
### Step 1: Install the plugin
|
|
93
56
|
|
|
94
57
|
```
|
|
95
58
|
/plugin marketplace add plastic-labs/claude-honcho
|
|
96
59
|
/plugin install honcho@honcho
|
|
97
60
|
```
|
|
98
61
|
|
|
99
|
-
|
|
62
|
+
Then run `/reload-plugins`, or restart Claude Code.
|
|
100
63
|
|
|
101
|
-
|
|
102
|
-
# Exit Claude Code (ctrl+c or /exit)
|
|
103
|
-
# Start it again -- you should see the Honcho pixel art and memory loading on startup.
|
|
104
|
-
claude
|
|
105
|
-
```
|
|
64
|
+
### Step 2: Connect Honcho
|
|
106
65
|
|
|
107
|
-
|
|
66
|
+
Click `○ honcho · set up` in the prompt footer, or run `/honcho setup`. Sign in with your browser, or paste an API key from [app.honcho.dev](https://app.honcho.dev). Your sign-in and key stay in the pane; they never go to Claude.
|
|
108
67
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
68
|
+
### Step 3: Start a new session
|
|
69
|
+
|
|
70
|
+
Run `/clear` or restart Claude Code. Memory loads at the start of each session, and `● honcho` in the footer opens the Honcho pane.
|
|
71
|
+
|
|
72
|
+
### Step 4 (optional): Teach Honcho about you
|
|
112
73
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
to the peer name you chose in your environment: it will carry across different projects!
|
|
74
|
+
- `/honcho:interview` -- Claude asks about your preferences and saves what it learns. It carries across projects.
|
|
75
|
+
- `/honcho import` -- add your past Claude Code sessions to Honcho. Chats the plugin already saved are skipped.
|
|
116
76
|
|
|
117
77
|
## What You Get
|
|
118
78
|
|
|
119
79
|
- **Persistent Memory** — Claude remembers your preferences, projects, and context across sessions
|
|
120
80
|
- **Survives Context Wipes** — Even when Claude's context window resets, memory persists
|
|
121
|
-
- **
|
|
122
|
-
- **Flexible Sessions** — Map sessions per directory, per git branch, or per chat instance
|
|
81
|
+
- **One session per chat** — Each Claude Code chat maps to its own Honcho session
|
|
123
82
|
- **AI Self-Awareness** — Claude knows what it was working on, even after restarts
|
|
124
|
-
- **Configurable Memory Injection** — Choose exactly what context is injected at session start and per turn
|
|
125
83
|
- **Team Support** — Multiple people can share a workspace and build context together
|
|
126
|
-
- **MCP Tools** — Search memory
|
|
84
|
+
- **MCP Tools** — Search memory and ask Honcho about you, a project scope, or the whole workspace
|
|
127
85
|
|
|
128
86
|
## MCP Tools
|
|
129
87
|
|
|
@@ -131,268 +89,76 @@ The honcho plugin provides these tools via MCP:
|
|
|
131
89
|
|
|
132
90
|
| Tool | Description |
|
|
133
91
|
| -------------------- | -------------------------------------------------------------- |
|
|
134
|
-
| `search` | Semantic search across session
|
|
135
|
-
| `chat` |
|
|
92
|
+
| `search` | Semantic search across messages (all sessions, or `scope: "session"` for this chat) and derived conclusions |
|
|
93
|
+
| `chat` | Ask Honcho about the user, optionally limited to a `scope`, or about the whole workspace (`workspace: true`) |
|
|
136
94
|
| `create_conclusion` | Save insights about the user to memory |
|
|
137
|
-
| `list_conclusions` | List
|
|
138
|
-
| `query_conclusions` | Semantic search over
|
|
95
|
+
| `list_conclusions` | List derived conclusions (explicit ones are excluded) |
|
|
96
|
+
| `query_conclusions` | Semantic search over derived conclusions |
|
|
139
97
|
| `delete_conclusion` | Delete a conclusion by ID |
|
|
140
|
-
| `get_briefing` | Load the session briefing: session summary + peer card |
|
|
141
|
-
| `get_context` | Retrieve the full context object (representation + peer card) |
|
|
142
|
-
| `get_representation` | Retrieve the user's representation string |
|
|
143
98
|
| `get_config` | View current configuration and status |
|
|
144
99
|
| `set_config` | Change any configuration field programmatically |
|
|
145
|
-
| `honcho_remember` | Fan-out dialectic recall (only registered when `rememberTool: true`) |
|
|
146
100
|
|
|
147
101
|
## Skills
|
|
148
102
|
|
|
149
103
|
| Command | Description |
|
|
150
104
|
| ------------------- | ----------------------------------------------------------- |
|
|
151
|
-
| `/honcho:status` | Show current memory status and connection info |
|
|
152
|
-
| `/honcho:config` | Interactive configuration menu |
|
|
153
|
-
| `/honcho:setup` | First-time setup — validate API key and create config |
|
|
154
105
|
| `/honcho:interview` | Interview to capture stable, cross-project user preferences |
|
|
155
|
-
| `/honcho:briefing` | Load the session briefing via a visible tool call |
|
|
156
|
-
| `/honcho:import` | Backfill past Claude Code sessions into Honcho memory |
|
|
157
106
|
| `/honcho:insights` | Distill memory into CLAUDE.md edits, style rules, skill ideas |
|
|
107
|
+
| `/honcho` | Opens the Honcho pane. `/honcho setup` (sign in or enter an API key), `/honcho status`, `/honcho config`, `/honcho set <field> <value>` and `/honcho import` (backfill past sessions; `--yes` to upload) answer at once, without a Claude turn |
|
|
108
|
+
|
|
109
|
+
**Honcho pane.** Click `● honcho` in the prompt footer, or run `/honcho`, to open a pane beside the chat with a link to this chat's session in Honcho, your dream history and your peer card. Select a dream or the peer card to see it in full.
|
|
158
110
|
|
|
159
111
|
---
|
|
160
112
|
|
|
161
113
|
## Configuration
|
|
162
114
|
|
|
163
|
-
All configuration lives in a single global file at `~/.honcho/config.json`. You can edit it directly, use
|
|
115
|
+
All configuration lives in a single global file at `~/.honcho/config.json`. You can edit it directly, use `/honcho set <field> <value>`, or use the `set_config` MCP tool. Environment variables override the file.
|
|
164
116
|
|
|
165
117
|
### Config File Reference
|
|
166
118
|
|
|
167
119
|
```jsonc
|
|
168
120
|
{
|
|
169
|
-
|
|
170
|
-
"apiKey": "hch-v2-...",
|
|
171
|
-
|
|
172
|
-
// Identity
|
|
173
|
-
"peerName": "alice", // Your name (default: $USER)
|
|
174
|
-
|
|
175
|
-
// Host-specific settings — each tool gets its own workspace and AI peer
|
|
121
|
+
"schemaVersion": 2,
|
|
176
122
|
"hosts": {
|
|
177
123
|
"claude_code": {
|
|
178
|
-
"
|
|
179
|
-
"
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
"workspace": "cursor",
|
|
183
|
-
"aiPeer": "cursor"
|
|
124
|
+
"oauth": { "accessToken": "…", "refreshToken": "…", "accessExpiresAt": 1794263473, "clientId": "claude-honcho", "scope": "write" },
|
|
125
|
+
"peerName": "alice", // asked during /honcho setup
|
|
126
|
+
"workspace": "claude_code",
|
|
127
|
+
"aiPeer": "claude"
|
|
184
128
|
}
|
|
185
|
-
},
|
|
186
|
-
|
|
187
|
-
// Session mapping
|
|
188
|
-
"sessionStrategy": "per-directory", // "per-directory" | "git-branch" | "chat-instance"
|
|
189
|
-
"sessionPeerPrefix": true, // Prefix session names with peerName (default: true)
|
|
190
|
-
|
|
191
|
-
// Message handling
|
|
192
|
-
"saveMessages": true,
|
|
193
|
-
"saveToolUse": false, // Save [Tool] action summaries (default: false)
|
|
194
|
-
"saveGitEvents": false, // Save [Git External] state-change events (default: false)
|
|
195
|
-
"messageUpload": {
|
|
196
|
-
"maxUserTokens": null, // Truncate user messages (null = no limit)
|
|
197
|
-
"maxAssistantTokens": null, // Truncate assistant messages (null = no limit)
|
|
198
|
-
"summarizeAssistant": false // Summarize instead of sending full assistant text
|
|
199
|
-
},
|
|
200
|
-
|
|
201
|
-
// Context retrieval
|
|
202
|
-
"contextRefresh": {
|
|
203
|
-
"messageThreshold": 30, // Refresh context every N messages
|
|
204
|
-
"ttlSeconds": 300, // Cache TTL for context
|
|
205
|
-
"skipDialectic": false // Skip dialectic chat() calls in user-prompt hook
|
|
206
|
-
},
|
|
207
|
-
"reasoningLevel": "medium", // Default dialectic reasoning tier: "minimal" | "low" | "medium" | "high" | "max"
|
|
208
|
-
|
|
209
|
-
// Memory injection (see "Memory Injection" below)
|
|
210
|
-
"injection": {
|
|
211
|
-
"sessionStart": ["directives", "summary", "peerCard"],
|
|
212
|
-
"perTurn": ["userContext"]
|
|
213
|
-
},
|
|
214
|
-
|
|
215
|
-
// On-demand recall tool (see "The honcho_remember Tool" below)
|
|
216
|
-
"rememberTool": false,
|
|
217
|
-
|
|
218
|
-
// Observation mode
|
|
219
|
-
"observationMode": "unified", // "unified" (default) | "directional"
|
|
220
|
-
|
|
221
|
-
// Endpoint
|
|
222
|
-
"endpoint": {
|
|
223
|
-
"environment": "production" // "production" | "local"
|
|
224
|
-
// or: "baseUrl": "http://your-server:8000/v3"
|
|
225
|
-
},
|
|
226
|
-
|
|
227
|
-
// Miscellaneous
|
|
228
|
-
"redactPatterns": [], // Extra regexes redacted from tool summaries (additive to built-in secret patterns)
|
|
229
|
-
"statusline": "on", // Memory statusline visibility: "on" | "off"
|
|
230
|
-
"enabled": true,
|
|
231
|
-
"logging": true,
|
|
232
|
-
|
|
233
|
-
// Advanced: force all hosts to use the same workspace
|
|
234
|
-
"globalOverride": false
|
|
235
|
-
}
|
|
236
|
-
```
|
|
237
|
-
|
|
238
|
-
### Session Strategies
|
|
239
|
-
|
|
240
|
-
Session strategy controls how Honcho maps your conversations to sessions. Change it with `/honcho:config` or `set_config`:
|
|
241
|
-
|
|
242
|
-
| Strategy | Behavior | Best for |
|
|
243
|
-
| --- | --- | --- |
|
|
244
|
-
| `per-directory` (default) | One session per project directory. Stable across restarts. | Most users — each project accumulates its own memory |
|
|
245
|
-
| `git-branch` | Session name includes the current git branch. Switching branches switches sessions. | Feature-branch workflows where context per branch matters |
|
|
246
|
-
| `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 |
|
|
247
|
-
|
|
248
|
-
### Memory Injection
|
|
249
|
-
|
|
250
|
-
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`.
|
|
251
|
-
|
|
252
|
-
**Session-start components** (default: `["directives", "summary", "peerCard"]`):
|
|
253
|
-
|
|
254
|
-
| Component | What it injects |
|
|
255
|
-
| --- | --- |
|
|
256
|
-
| `directives` | Static memory-usage guidance — treat injected memory as background, use `chat`/`search` for recall, save insights with `create_conclusion` |
|
|
257
|
-
| `summary` | The session's long summary narrative (skipped on a fresh session) |
|
|
258
|
-
| `peerCard` | Your peer card — a structured identity/attribute list |
|
|
259
|
-
| `peerRepresentation` | Your full derived representation, injected at full length |
|
|
260
|
-
| `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 |
|
|
261
|
-
|
|
262
|
-
**Per-turn components** (default: `["userContext"]`):
|
|
263
|
-
|
|
264
|
-
| Component | What it injects |
|
|
265
|
-
| --- | --- |
|
|
266
|
-
| `userContext` | A fresh, prompt-scoped context fetch for *you* — conclusions selected by semantic search, shaped by the retrieval knobs below |
|
|
267
|
-
| `assistantContext` | The same context fetch for the AI peer — what Honcho has derived about the assistant itself |
|
|
268
|
-
| `sessionContext` | Recent raw messages from the currently mapped Honcho session, which can span other Claude instances sharing the session name |
|
|
269
|
-
| `dialectic` | A reasoned `chat()` answer over your representation, seeded from `dialecticTemplate`. Off by default — much slower than a context fetch |
|
|
270
|
-
|
|
271
|
-
**Retrieval knobs:**
|
|
272
|
-
|
|
273
|
-
| Field | Default | Description |
|
|
274
|
-
| --- | --- | --- |
|
|
275
|
-
| `searchTopK` | `10` | Top-K conclusions pulled by the context fetch's semantic search |
|
|
276
|
-
| `maxConclusions` | `15` | Max conclusions injected per context fetch |
|
|
277
|
-
| `searchMaxDistance` | `0.6` | Max cosine distance for the semantic search — lower is stricter |
|
|
278
|
-
| `searchQuerySource` | `"prompt"` | What drives the per-turn search: the raw `"prompt"` or extracted `"topics"` |
|
|
279
|
-
| `sessionContextTokens` | `1500` | Token budget for the `sessionContext` message fetch |
|
|
280
|
-
| `dialecticTemplate` | compact factual recall | Query template for the `dialectic` component; the prompt is substituted into `%{user_query}` |
|
|
281
|
-
| `dialecticReasoning` | `"medium"` | Reasoning tier for the per-turn `dialectic` call — separate from the top-level `reasoningLevel` |
|
|
282
|
-
|
|
283
|
-
If injected context feels off-topic, lower `searchMaxDistance`; if too sparse, raise it or bump `searchTopK`.
|
|
284
|
-
|
|
285
|
-
**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`:
|
|
286
|
-
|
|
287
|
-
```json
|
|
288
|
-
{ "injection": { "showContents": ["userContext", "sessionContext"] } }
|
|
289
|
-
```
|
|
290
|
-
|
|
291
|
-
### The `honcho_remember` Tool
|
|
292
|
-
|
|
293
|
-
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.
|
|
294
|
-
|
|
295
|
-
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`:
|
|
296
|
-
|
|
297
|
-
```json
|
|
298
|
-
{
|
|
299
|
-
"hosts": {
|
|
300
|
-
"claude_code": { "rememberTool": true }
|
|
301
129
|
}
|
|
302
130
|
}
|
|
303
131
|
```
|
|
304
132
|
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
When it's on, the injected session-start directives steer Claude to use it proactively as the primary recall path.
|
|
133
|
+
`/honcho setup` writes one of two credentials:
|
|
308
134
|
|
|
309
|
-
|
|
135
|
+
- `oauth`: "Sign in with your browser". Your Claude Code sign-in to Honcho cloud, refreshed automatically. Other Honcho plugins keep their own.
|
|
136
|
+
- `apiKey`: "Use an API key", for a key from app.honcho.dev or a self-hosted Honcho (`"baseUrl": "http://localhost:8000"`; browser sign-in is cloud-only).
|
|
310
137
|
|
|
311
|
-
|
|
138
|
+
`HONCHO_API_KEY` overrides both.
|
|
312
139
|
|
|
313
|
-
|
|
314
|
-
| --- | --- | --- |
|
|
315
|
-
| `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 |
|
|
316
|
-
| `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 |
|
|
140
|
+
Each plugin keeps its settings in its own block under `hosts`; nothing at the top level is read. If your file still has top-level settings or old key names, the plugin copies them into `hosts.claude_code` at session start and says so once, and leaves the top level and other plugins' blocks as they are. Logs go to `~/.honcho/activity.log`. To turn the plugin off, disable it in Claude Code's `/plugin` menu.
|
|
317
141
|
|
|
318
|
-
|
|
142
|
+
### Sessions
|
|
319
143
|
|
|
320
|
-
|
|
144
|
+
Each Claude Code chat maps to one Honcho session whose id is the Claude Code session id. Resuming a chat continues its session; `/clear` and new chats start a new one. Memory about you still carries across every chat in the workspace.
|
|
321
145
|
|
|
322
|
-
|
|
323
|
-
- Or edit `~/.honcho/config.json`:
|
|
324
|
-
```json
|
|
325
|
-
{ "observationMode": "directional" }
|
|
326
|
-
```
|
|
327
|
-
- Or per-host:
|
|
328
|
-
```json
|
|
329
|
-
{
|
|
330
|
-
"hosts": {
|
|
331
|
-
"claude_code": { "observationMode": "directional" }
|
|
332
|
-
}
|
|
333
|
-
}
|
|
334
|
-
```
|
|
146
|
+
New sessions also join two Honcho scopes: one named after the git repository (worktrees share the main repo's name; outside git, the directory name) and one named after the machine's hostname. Use them to query memory from just one project or one machine.
|
|
335
147
|
|
|
336
|
-
|
|
148
|
+
This mapping isn't configurable. If you want a different session layout, connect to Honcho through the [Honcho MCP server](https://mcp.honcho.dev) and manage sessions yourself.
|
|
337
149
|
|
|
338
|
-
###
|
|
339
|
-
|
|
340
|
-
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:
|
|
341
|
-
|
|
342
|
-
```bash
|
|
343
|
-
# Requires: pip install honcho-ai
|
|
344
|
-
# Set your API key: export HONCHO_API_KEY="hch-..."
|
|
345
|
-
|
|
346
|
-
# Dry run — see what would be migrated (directional → unified)
|
|
347
|
-
python scripts/migrate-observations.py \
|
|
348
|
-
--workspace agents \
|
|
349
|
-
--from-observer claude \
|
|
350
|
-
--user ajspig \
|
|
351
|
-
--dry-run
|
|
352
|
-
|
|
353
|
-
# Execute the migration
|
|
354
|
-
python scripts/migrate-observations.py \
|
|
355
|
-
--workspace agents \
|
|
356
|
-
--from-observer claude \
|
|
357
|
-
--user ajspig
|
|
358
|
-
|
|
359
|
-
# Execute and delete the source conclusions after migration
|
|
360
|
-
python scripts/migrate-observations.py \
|
|
361
|
-
--workspace agents \
|
|
362
|
-
--from-observer claude \
|
|
363
|
-
--user ajspig \
|
|
364
|
-
--delete-source
|
|
365
|
-
```
|
|
366
|
-
|
|
367
|
-
The script:
|
|
368
|
-
- Reads all conclusions from the source collection (e.g., `observer=claude, observed=ajspig`)
|
|
369
|
-
- Deduplicates by content against the destination (e.g., `observer=ajspig, observed=ajspig`)
|
|
370
|
-
- Creates only the conclusions that don't already exist in the destination
|
|
371
|
-
- Handles rate limiting with automatic retries
|
|
372
|
-
|
|
373
|
-
To migrate in the other direction (unified → directional):
|
|
374
|
-
|
|
375
|
-
```bash
|
|
376
|
-
python scripts/migrate-observations.py \
|
|
377
|
-
--workspace agents \
|
|
378
|
-
--from-observer ajspig \
|
|
379
|
-
--to-observer claude \
|
|
380
|
-
--user ajspig
|
|
381
|
-
```
|
|
150
|
+
### Memory Injection
|
|
382
151
|
|
|
383
|
-
|
|
152
|
+
At session start the plugin injects two things:
|
|
384
153
|
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
python scripts/migrate-observations.py -w agents --from-observer claude --user ajspig
|
|
154
|
+
- **Directives**: how to use Honcho memory. Treat it as background, recall with the `chat` tool (naming this chat's repo and machine scopes), and save insights with `create_conclusion`.
|
|
155
|
+
- **Your peer card**: a structured identity/attribute list.
|
|
388
156
|
|
|
389
|
-
|
|
390
|
-
python scripts/migrate-observations.py -w agents --from-observer hermes --user ajspig
|
|
391
|
-
```
|
|
157
|
+
Nothing is injected per prompt, and nothing is fetched with `context()`. Tools that read conclusions (`search`, `list_conclusions`, `query_conclusions`) return only derived conclusions; explicit ones are filtered out. Claude recalls memory when it needs it by calling `chat`:
|
|
392
158
|
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
159
|
+
- **About you** (default): an answer from everything Honcho knows about you.
|
|
160
|
+
- **Within a scope**: pass `scope` (e.g. the repo name) to answer only from that scope's sessions.
|
|
161
|
+
- **Across the workspace**: pass `workspace: true` to ask about every peer in the workspace.
|
|
396
162
|
|
|
397
163
|
### Host-Aware Configuration
|
|
398
164
|
|
|
@@ -404,34 +170,17 @@ The plugin auto-detects which tool is running it (Claude Code, Cursor, etc.) and
|
|
|
404
170
|
3. `CURSOR_PROJECT_DIR` env var (Cursor child process)
|
|
405
171
|
4. Default: `claude_code`
|
|
406
172
|
|
|
407
|
-
### Global Override
|
|
408
|
-
|
|
409
|
-
If you want all hosts to share a single workspace (instead of per-host isolation), set `globalOverride: true` and a flat `workspace` field:
|
|
410
|
-
|
|
411
|
-
```jsonc
|
|
412
|
-
{
|
|
413
|
-
"globalOverride": true,
|
|
414
|
-
"workspace": "shared",
|
|
415
|
-
"hosts": {
|
|
416
|
-
"claude_code": { "aiPeer": "claude" },
|
|
417
|
-
"cursor": { "aiPeer": "cursor" }
|
|
418
|
-
}
|
|
419
|
-
}
|
|
420
|
-
```
|
|
421
|
-
|
|
422
|
-
All tools will read and write to the `shared` workspace. Each tool still uses its own AI peer name.
|
|
423
|
-
|
|
424
173
|
### Team Setup with Shared Context
|
|
425
174
|
|
|
426
|
-
Multiple people can share context by pointing to the same workspace. Each person uses their own `peerName` as identity
|
|
175
|
+
Multiple people can share context by pointing to the same workspace. Each person uses their own `peerName` as identity.
|
|
427
176
|
|
|
428
177
|
**Person A** (`~/.honcho/config.json`):
|
|
429
178
|
```json
|
|
430
179
|
{
|
|
431
|
-
"apiKey": "hch-v2-team-key...",
|
|
432
|
-
"peerName": "alice",
|
|
433
180
|
"hosts": {
|
|
434
181
|
"claude_code": {
|
|
182
|
+
"apiKey": "hch-v2-team-key...",
|
|
183
|
+
"peerName": "alice",
|
|
435
184
|
"workspace": "team-acme",
|
|
436
185
|
"aiPeer": "claude"
|
|
437
186
|
}
|
|
@@ -442,10 +191,10 @@ Multiple people can share context by pointing to the same workspace. Each person
|
|
|
442
191
|
**Person B** (`~/.honcho/config.json`):
|
|
443
192
|
```json
|
|
444
193
|
{
|
|
445
|
-
"apiKey": "hch-v2-team-key...",
|
|
446
|
-
"peerName": "bob",
|
|
447
194
|
"hosts": {
|
|
448
195
|
"claude_code": {
|
|
196
|
+
"apiKey": "hch-v2-team-key...",
|
|
197
|
+
"peerName": "bob",
|
|
449
198
|
"workspace": "team-acme",
|
|
450
199
|
"aiPeer": "claude"
|
|
451
200
|
}
|
|
@@ -453,23 +202,20 @@ Multiple people can share context by pointing to the same workspace. Each person
|
|
|
453
202
|
}
|
|
454
203
|
```
|
|
455
204
|
|
|
456
|
-
Both Alice and Bob write to the `team-acme` workspace.
|
|
205
|
+
Both Alice and Bob write to the `team-acme` workspace. Each chat has its own session, so data doesn't collide, but Honcho's dialectic reasoning can draw on context from both users.
|
|
457
206
|
|
|
458
207
|
### Environment Variables
|
|
459
208
|
|
|
460
|
-
Environment variables
|
|
209
|
+
Environment variables override `hosts.claude_code` in `~/.honcho/config.json`.
|
|
461
210
|
|
|
462
211
|
| Variable | Required | Default | Description |
|
|
463
212
|
| ---------------------- | -------- | ------------- | ----------------------------------------------------------------- |
|
|
464
213
|
| `HONCHO_API_KEY` | **Yes** | — | Your Honcho API key from [app.honcho.dev](https://app.honcho.dev) |
|
|
465
214
|
| `HONCHO_PEER_NAME` | No | `$USER` | Your identity in the memory system |
|
|
466
|
-
| `HONCHO_WORKSPACE` | No | `claude_code` | Workspace name
|
|
467
|
-
| `HONCHO_AI_PEER` | No | `claude` | AI peer name
|
|
215
|
+
| `HONCHO_WORKSPACE` | No | `claude_code` | Workspace name |
|
|
216
|
+
| `HONCHO_AI_PEER` | No | `claude` | AI peer name (the old `HONCHO_CLAUDE_PEER` still works in an env-only setup) |
|
|
468
217
|
| `HONCHO_HOST` | No | auto-detected | Force host detection: `claude_code`, `cursor`, or `obsidian` |
|
|
469
|
-
| `
|
|
470
|
-
| `HONCHO_ENABLED` | No | `true` | Set to `false` to disable |
|
|
471
|
-
| `HONCHO_SAVE_MESSAGES` | No | `true` | Set to `false` to stop saving messages |
|
|
472
|
-
| `HONCHO_LOGGING` | No | `true` | Set to `false` to disable file logging to `~/.honcho/` |
|
|
218
|
+
| `HONCHO_BASE_URL` | No | Honcho cloud | Honcho API URL (the old `HONCHO_ENDPOINT` still works in an env-only setup, with no key or sign-in in the config file) |
|
|
473
219
|
|
|
474
220
|
## How It Works
|
|
475
221
|
|
|
@@ -477,29 +223,27 @@ Environment variables work for initial bootstrap (before a config file exists).
|
|
|
477
223
|
┌─────────────────────────────────────────────────────────────────┐
|
|
478
224
|
│ Claude Code │
|
|
479
225
|
├─────────────────────────────────────────────────────────────────┤
|
|
480
|
-
│ SessionStart │ UserPrompt │
|
|
226
|
+
│ SessionStart │ UserPrompt │ Stop │ SessionEnd │
|
|
481
227
|
│ ─────────── │ ─────────── │ ──────────── │ ────────── │
|
|
482
|
-
│ Load
|
|
483
|
-
│
|
|
228
|
+
│ Load peer card │ Save message │ Save Claude's │ Clean up │
|
|
229
|
+
│ + directives │ to Honcho │ reply │ │
|
|
484
230
|
└─────────────────────────────────────────────────────────────────┘
|
|
485
231
|
│
|
|
486
232
|
▼
|
|
487
233
|
┌─────────────────────────────────────────────────────────────────┐
|
|
488
234
|
│ Honcho API │
|
|
489
235
|
│ │
|
|
490
|
-
│ Your messages and Claude's
|
|
491
|
-
│
|
|
236
|
+
│ Your messages and Claude's replies → Persistent Memory → │
|
|
237
|
+
│ Recalled on demand through the chat tool │
|
|
492
238
|
└─────────────────────────────────────────────────────────────────┘
|
|
493
239
|
```
|
|
494
240
|
|
|
495
241
|
The plugin hooks into Claude Code's lifecycle events:
|
|
496
242
|
|
|
497
|
-
- **SessionStart**:
|
|
498
|
-
- **UserPrompt**: Saves your messages
|
|
499
|
-
- **
|
|
500
|
-
- **
|
|
501
|
-
- **Stop**: Flushes any pending messages
|
|
502
|
-
- **SessionEnd**: Uploads remaining messages and generates a summary
|
|
243
|
+
- **SessionStart**: Joins this chat's session to its repo and machine scopes, and injects the memory directives and your peer card
|
|
244
|
+
- **UserPrompt**: Saves your messages (nothing is retrieved per turn; Claude calls `chat` when it needs memory)
|
|
245
|
+
- **Stop**: Saves Claude's replies
|
|
246
|
+
- **SessionEnd**: Clears local per-chat state
|
|
503
247
|
|
|
504
248
|
## Troubleshooting
|
|
505
249
|
|
|
@@ -512,7 +256,7 @@ The plugin hooks into Claude Code's lifecycle events:
|
|
|
512
256
|
echo $env:HONCHO_API_KEY # Windows PowerShell
|
|
513
257
|
```
|
|
514
258
|
|
|
515
|
-
If empty, set it (see
|
|
259
|
+
If empty, run `/honcho setup`, or set it (see the environment-variable setup near the end) and restart your terminal.
|
|
516
260
|
|
|
517
261
|
2. **Check the plugin is installed:**
|
|
518
262
|
|
|
@@ -524,33 +268,27 @@ The plugin hooks into Claude Code's lifecycle events:
|
|
|
524
268
|
|
|
525
269
|
3. **Restart Claude Code** after making changes.
|
|
526
270
|
|
|
527
|
-
4. **Run `/honcho
|
|
271
|
+
4. **Run `/honcho status`** to see connection state, workspace, and session info.
|
|
528
272
|
|
|
529
|
-
###
|
|
273
|
+
### An old `◇ honcho ↗` in the status line
|
|
530
274
|
|
|
531
|
-
|
|
275
|
+
That's the statusLine script older versions of `/honcho:setup` installed. It's no longer maintained; the honcho button in the footer replaces it. To remove it, delete the `"statusLine"` entry that points at `honcho-statusline.sh` from `~/.claude/settings.json`, then delete `~/.honcho/honcho-statusline.sh`.
|
|
532
276
|
|
|
533
277
|
### Using a local Honcho instance
|
|
534
278
|
|
|
535
279
|
Via config file:
|
|
536
280
|
```json
|
|
537
|
-
{ "
|
|
281
|
+
{ "hosts": { "claude_code": { "baseUrl": "http://localhost:8000" } } }
|
|
538
282
|
```
|
|
539
283
|
|
|
540
284
|
Or via env var:
|
|
541
285
|
```bash
|
|
542
|
-
export
|
|
543
|
-
# or
|
|
544
|
-
export HONCHO_ENDPOINT="http://your-server:8000/v3"
|
|
286
|
+
export HONCHO_BASE_URL="http://localhost:8000"
|
|
545
287
|
```
|
|
546
288
|
|
|
547
289
|
### Temporarily disabling memory
|
|
548
290
|
|
|
549
|
-
|
|
550
|
-
export HONCHO_ENABLED="false"
|
|
551
|
-
```
|
|
552
|
-
|
|
553
|
-
Or set `"enabled": false` in your config file. Restart Claude Code to take effect.
|
|
291
|
+
Disable the plugin in Claude Code's `/plugin` menu, and enable it again when you're done.
|
|
554
292
|
|
|
555
293
|
---
|
|
556
294
|
|
|
@@ -586,6 +324,48 @@ This plugin provides skills to help you integrate Honcho into your projects and
|
|
|
586
324
|
|
|
587
325
|
Then remove the environment variables from your shell config if desired.
|
|
588
326
|
|
|
327
|
+
<details>
|
|
328
|
+
<summary>Claude Code before v2.1.287: set up with environment variables</summary>
|
|
329
|
+
|
|
330
|
+
Older Claude Code versions don't load the plugin's mod, so there is no `/honcho` command or Honcho pane. Memory still works once a key is set.
|
|
331
|
+
|
|
332
|
+
1. Get an API key (starts with `hch-`) at [app.honcho.dev](https://app.honcho.dev).
|
|
333
|
+
2. Set it in your environment.
|
|
334
|
+
|
|
335
|
+
**macOS / Linux** -- add these to your shell config (`~/.zshrc`, `~/.bashrc`, or `~/.profile`):
|
|
336
|
+
|
|
337
|
+
```bash
|
|
338
|
+
# Required
|
|
339
|
+
export HONCHO_API_KEY="hch-your-api-key-here"
|
|
340
|
+
|
|
341
|
+
# Optional (defaults shown)
|
|
342
|
+
export HONCHO_PEER_NAME="$USER" # Your name/identity
|
|
343
|
+
export HONCHO_WORKSPACE="claude_code" # Workspace name
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
Then reload your shell:
|
|
347
|
+
|
|
348
|
+
```bash
|
|
349
|
+
source ~/.zshrc # or ~/.bashrc
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
**Windows (PowerShell)** -- set a persistent user environment variable:
|
|
353
|
+
|
|
354
|
+
```powershell
|
|
355
|
+
# Required
|
|
356
|
+
[Environment]::SetEnvironmentVariable("HONCHO_API_KEY", "hch-your-api-key-here", "User")
|
|
357
|
+
|
|
358
|
+
# Optional
|
|
359
|
+
[Environment]::SetEnvironmentVariable("HONCHO_PEER_NAME", $env:USERNAME, "User")
|
|
360
|
+
[Environment]::SetEnvironmentVariable("HONCHO_WORKSPACE", "claude_code", "User")
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
Then restart your terminal so the new variables take effect.
|
|
364
|
+
|
|
365
|
+
3. Install the plugin (Step 1 above) and restart Claude Code.
|
|
366
|
+
|
|
367
|
+
</details>
|
|
368
|
+
|
|
589
369
|
---
|
|
590
370
|
|
|
591
371
|
## License
|