@honcho-ai/claude-honcho 0.3.0-rc.1 → 0.3.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/LICENSE +21 -0
- package/README.md +522 -0
- package/package.json +1 -1
- package/scripts/check-version.sh +2 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Plastic Labs
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,522 @@
|
|
|
1
|
+
# Honcho Plugins for Claude Code
|
|
2
|
+
|
|
3
|
+
[](https://honcho.dev)
|
|
4
|
+
|
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
|
6
|
+
[](https://www.npmjs.com/package/@honcho-ai/claude-honcho)
|
|
7
|
+
[](https://honcho.dev)
|
|
8
|
+
|
|
9
|
+
A plugin marketplace for Claude Code, powered by [Honcho](https://honcho.dev) from Plastic Labs.
|
|
10
|
+
|
|
11
|
+
## Plugins
|
|
12
|
+
|
|
13
|
+
| Plugin | Description |
|
|
14
|
+
| ------------------------------------ | ----------------------------------------------- |
|
|
15
|
+
| **[honcho](#honcho-plugin)** | Persistent memory for Claude Code sessions |
|
|
16
|
+
| **[honcho-dev](#honcho-dev-plugin)** | Skills for building AI apps with the Honcho SDK |
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Installation
|
|
21
|
+
|
|
22
|
+
Add the marketplace to Claude Code:
|
|
23
|
+
|
|
24
|
+
```
|
|
25
|
+
/plugin marketplace add plastic-labs/claude-honcho
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Then install the plugin(s) you want:
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
/plugin install honcho@honcho
|
|
32
|
+
/plugin install honcho-dev@honcho
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
You'll need to restart Claude Code for the plugins to take effect. Follow the instructions below for setting up each plugin.
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
# `honcho` Plugin
|
|
40
|
+
|
|
41
|
+
**Persistent memory for Claude Code using [Honcho](https://honcho.dev).**
|
|
42
|
+
|
|
43
|
+
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.
|
|
44
|
+
|
|
45
|
+
## Prerequisites
|
|
46
|
+
|
|
47
|
+
A Honcho API key from [app.honcho.dev](https://app.honcho.dev). Nothing else --
|
|
48
|
+
the plugin ships as a self-contained bundle and runs on the Node runtime Claude
|
|
49
|
+
Code already provides.
|
|
50
|
+
|
|
51
|
+
## Quick Start
|
|
52
|
+
|
|
53
|
+
### Step 1: Get Your Honcho API Key
|
|
54
|
+
|
|
55
|
+
1. Go to **[app.honcho.dev](https://app.honcho.dev)**
|
|
56
|
+
2. Sign up or log in
|
|
57
|
+
3. Copy your API key (starts with `hch-`)
|
|
58
|
+
|
|
59
|
+
### Step 2: Set Environment Variables
|
|
60
|
+
|
|
61
|
+
**macOS / Linux** -- add these to your shell config (`~/.zshrc`, `~/.bashrc`, or `~/.profile`):
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
# Required
|
|
65
|
+
export HONCHO_API_KEY="hch-your-api-key-here"
|
|
66
|
+
|
|
67
|
+
# Optional (defaults shown)
|
|
68
|
+
export HONCHO_PEER_NAME="$USER" # Your name/identity
|
|
69
|
+
export HONCHO_WORKSPACE="claude_code" # Workspace name
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Then reload your shell:
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
source ~/.zshrc # or ~/.bashrc
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
**Windows (PowerShell)** -- set a persistent user environment variable:
|
|
79
|
+
|
|
80
|
+
```powershell
|
|
81
|
+
# Required
|
|
82
|
+
[Environment]::SetEnvironmentVariable("HONCHO_API_KEY", "hch-your-api-key-here", "User")
|
|
83
|
+
|
|
84
|
+
# Optional
|
|
85
|
+
[Environment]::SetEnvironmentVariable("HONCHO_PEER_NAME", $env:USERNAME, "User")
|
|
86
|
+
[Environment]::SetEnvironmentVariable("HONCHO_WORKSPACE", "claude_code", "User")
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Then restart your terminal so the new variables take effect.
|
|
90
|
+
|
|
91
|
+
### Step 3: Install the Plugin
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
/plugin marketplace add plastic-labs/claude-honcho
|
|
95
|
+
/plugin install honcho@honcho
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Step 4: Restart Claude Code
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
# Exit Claude Code (ctrl+c or /exit)
|
|
102
|
+
# Start it again -- you should see the Honcho pixel art and memory loading on startup.
|
|
103
|
+
claude
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### Step 5: (Optional) Kick off your conversation with an interview
|
|
107
|
+
|
|
108
|
+
```
|
|
109
|
+
/honcho:interview
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Claude will interview you about your personal preferences in order to kickstart a representation
|
|
113
|
+
of you. What it learns will be saved in Honcho and remembered forever. The interview is specific
|
|
114
|
+
to the peer name you chose in your environment: it will carry across different projects!
|
|
115
|
+
|
|
116
|
+
## What You Get
|
|
117
|
+
|
|
118
|
+
- **Persistent Memory** — Claude remembers your preferences, projects, and context across sessions
|
|
119
|
+
- **Survives Context Wipes** — Even when Claude's context window resets, memory persists
|
|
120
|
+
- **Git Awareness** — Detects branch switches, commits, and changes made outside Claude
|
|
121
|
+
- **Flexible Sessions** — Map sessions per directory, per git branch, or per chat instance
|
|
122
|
+
- **AI Self-Awareness** — Claude knows what it was working on, even after restarts
|
|
123
|
+
- **Cross-Tool Context** — Link workspaces across Claude Code, Cursor, and other hosts so context flows between tools
|
|
124
|
+
- **Team Support** — Multiple people can share a workspace and build context together
|
|
125
|
+
- **MCP Tools** — Search memory, query knowledge about you, and save insights
|
|
126
|
+
|
|
127
|
+
## MCP Tools
|
|
128
|
+
|
|
129
|
+
The honcho plugin provides these tools via MCP:
|
|
130
|
+
|
|
131
|
+
| Tool | Description |
|
|
132
|
+
| ------------------- | ------------------------------------------------ |
|
|
133
|
+
| `search` | Semantic search across session messages |
|
|
134
|
+
| `chat` | Query Honcho's knowledge about the user |
|
|
135
|
+
| `create_conclusion` | Save insights about the user to memory |
|
|
136
|
+
| `get_config` | View current configuration and status |
|
|
137
|
+
| `set_config` | Change any configuration field programmatically |
|
|
138
|
+
|
|
139
|
+
## Skills
|
|
140
|
+
|
|
141
|
+
| Command | Description |
|
|
142
|
+
| ------------------- | ----------------------------------------------------------- |
|
|
143
|
+
| `/honcho:status` | Show current memory status and connection info |
|
|
144
|
+
| `/honcho:config` | Interactive configuration menu |
|
|
145
|
+
| `/honcho:setup` | First-time setup — validate API key and create config |
|
|
146
|
+
| `/honcho:interview` | Interview to capture stable, cross-project user preferences |
|
|
147
|
+
| `/honcho:import` | Backfill past Claude Code sessions into Honcho memory |
|
|
148
|
+
| `/honcho:insights` | Distill memory into CLAUDE.md edits, style rules, skill ideas |
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## Configuration
|
|
153
|
+
|
|
154
|
+
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.
|
|
155
|
+
|
|
156
|
+
### Config File Reference
|
|
157
|
+
|
|
158
|
+
```jsonc
|
|
159
|
+
{
|
|
160
|
+
// Required
|
|
161
|
+
"apiKey": "hch-v2-...",
|
|
162
|
+
|
|
163
|
+
// Identity
|
|
164
|
+
"peerName": "alice", // Your name (default: $USER)
|
|
165
|
+
|
|
166
|
+
// Host-specific settings — each tool gets its own workspace and AI peer
|
|
167
|
+
"hosts": {
|
|
168
|
+
"claude_code": {
|
|
169
|
+
"workspace": "claude_code", // Workspace for Claude Code sessions
|
|
170
|
+
"aiPeer": "claude", // AI identity in this workspace
|
|
171
|
+
},
|
|
172
|
+
"cursor": {
|
|
173
|
+
"workspace": "cursor",
|
|
174
|
+
"aiPeer": "cursor"
|
|
175
|
+
}
|
|
176
|
+
},
|
|
177
|
+
|
|
178
|
+
// Session mapping
|
|
179
|
+
"sessionStrategy": "per-directory", // "per-directory" | "git-branch" | "chat-instance"
|
|
180
|
+
"sessionPeerPrefix": true, // Prefix session names with peerName (default: true)
|
|
181
|
+
|
|
182
|
+
// Message handling
|
|
183
|
+
"saveMessages": true,
|
|
184
|
+
"messageUpload": {
|
|
185
|
+
"maxUserTokens": null, // Truncate user messages (null = no limit)
|
|
186
|
+
"maxAssistantTokens": null, // Truncate assistant messages (null = no limit)
|
|
187
|
+
"summarizeAssistant": false // Summarize instead of sending full assistant text
|
|
188
|
+
},
|
|
189
|
+
|
|
190
|
+
// Context retrieval
|
|
191
|
+
"contextRefresh": {
|
|
192
|
+
"messageThreshold": 30, // Refresh context every N messages
|
|
193
|
+
"ttlSeconds": 300, // Cache TTL for context
|
|
194
|
+
"skipDialectic": false // Skip dialectic chat() calls in user-prompt hook
|
|
195
|
+
},
|
|
196
|
+
|
|
197
|
+
// Observation mode
|
|
198
|
+
"observationMode": "unified", // "unified" (default) | "directional"
|
|
199
|
+
|
|
200
|
+
// Endpoint
|
|
201
|
+
"endpoint": {
|
|
202
|
+
"environment": "production" // "production" | "local"
|
|
203
|
+
// or: "baseUrl": "http://your-server:8000/v3"
|
|
204
|
+
},
|
|
205
|
+
|
|
206
|
+
// Miscellaneous
|
|
207
|
+
"localContext": { "maxEntries": 50 }, // Max entries in claude-context.md
|
|
208
|
+
"enabled": true,
|
|
209
|
+
"logging": true,
|
|
210
|
+
|
|
211
|
+
// Advanced: force all hosts to use the same workspace
|
|
212
|
+
"globalOverride": false
|
|
213
|
+
}
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
### Session Strategies
|
|
217
|
+
|
|
218
|
+
Session strategy controls how Honcho maps your conversations to sessions. Change it with `/honcho:config` or `set_config`:
|
|
219
|
+
|
|
220
|
+
| Strategy | Behavior | Best for |
|
|
221
|
+
| --- | --- | --- |
|
|
222
|
+
| `per-directory` (default) | One session per project directory. Stable across restarts. | Most users — each project accumulates its own memory |
|
|
223
|
+
| `git-branch` | Session name includes the current git branch. Switching branches switches sessions. | Feature-branch workflows where context per branch matters |
|
|
224
|
+
| `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 |
|
|
225
|
+
|
|
226
|
+
### Observation Mode
|
|
227
|
+
|
|
228
|
+
Controls how Honcho stores and retrieves conclusions about you. Change it via `set_config` or edit `config.json` directly. Requires a Claude Code restart.
|
|
229
|
+
|
|
230
|
+
| Mode | Behavior | Best for |
|
|
231
|
+
| --- | --- | --- |
|
|
232
|
+
| `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 |
|
|
233
|
+
| `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 |
|
|
234
|
+
|
|
235
|
+
> **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](https://app.honcho.dev). The only override the plugin applies is `observeOthers: true` on the AI peer in `directional` mode.
|
|
236
|
+
|
|
237
|
+
To change:
|
|
238
|
+
|
|
239
|
+
- Ask Claude: *"Set my observation mode to directional"*
|
|
240
|
+
- Or edit `~/.honcho/config.json`:
|
|
241
|
+
```json
|
|
242
|
+
{ "observationMode": "directional" }
|
|
243
|
+
```
|
|
244
|
+
- Or per-host:
|
|
245
|
+
```json
|
|
246
|
+
{
|
|
247
|
+
"hosts": {
|
|
248
|
+
"claude_code": { "observationMode": "directional" }
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
> **Note:** Switching modes doesn't automatically migrate existing conclusions. Each mode reads from a different collection. See [Migrating Observations](#migrating-observations) below to move conclusions between collections.
|
|
254
|
+
|
|
255
|
+
### Migrating Observations
|
|
256
|
+
|
|
257
|
+
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:
|
|
258
|
+
|
|
259
|
+
```bash
|
|
260
|
+
# Requires: pip install honcho-ai
|
|
261
|
+
# Set your API key: export HONCHO_API_KEY="hch-..."
|
|
262
|
+
|
|
263
|
+
# Dry run — see what would be migrated (directional → unified)
|
|
264
|
+
python scripts/migrate-observations.py \
|
|
265
|
+
--workspace agents \
|
|
266
|
+
--from-observer claude \
|
|
267
|
+
--user ajspig \
|
|
268
|
+
--dry-run
|
|
269
|
+
|
|
270
|
+
# Execute the migration
|
|
271
|
+
python scripts/migrate-observations.py \
|
|
272
|
+
--workspace agents \
|
|
273
|
+
--from-observer claude \
|
|
274
|
+
--user ajspig
|
|
275
|
+
|
|
276
|
+
# Execute and delete the source conclusions after migration
|
|
277
|
+
python scripts/migrate-observations.py \
|
|
278
|
+
--workspace agents \
|
|
279
|
+
--from-observer claude \
|
|
280
|
+
--user ajspig \
|
|
281
|
+
--delete-source
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
The script:
|
|
285
|
+
- Reads all conclusions from the source collection (e.g., `observer=claude, observed=ajspig`)
|
|
286
|
+
- Deduplicates by content against the destination (e.g., `observer=ajspig, observed=ajspig`)
|
|
287
|
+
- Creates only the conclusions that don't already exist in the destination
|
|
288
|
+
- Handles rate limiting with automatic retries
|
|
289
|
+
|
|
290
|
+
To migrate in the other direction (unified → directional):
|
|
291
|
+
|
|
292
|
+
```bash
|
|
293
|
+
python scripts/migrate-observations.py \
|
|
294
|
+
--workspace agents \
|
|
295
|
+
--from-observer ajspig \
|
|
296
|
+
--to-observer claude \
|
|
297
|
+
--user ajspig
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
If you use multiple AI agents, run the script once per agent:
|
|
301
|
+
|
|
302
|
+
```bash
|
|
303
|
+
# Migrate Claude's observations to unified
|
|
304
|
+
python scripts/migrate-observations.py -w agents --from-observer claude --user ajspig
|
|
305
|
+
|
|
306
|
+
# Migrate Hermes' observations to unified
|
|
307
|
+
python scripts/migrate-observations.py -w agents --from-observer hermes --user ajspig
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
Run with `--help` for all options.
|
|
311
|
+
|
|
312
|
+
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.
|
|
313
|
+
|
|
314
|
+
### Host-Aware Configuration
|
|
315
|
+
|
|
316
|
+
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.
|
|
317
|
+
|
|
318
|
+
**Host detection priority:**
|
|
319
|
+
1. `HONCHO_HOST` env var (explicit override)
|
|
320
|
+
2. `cursor_version` in hook stdin (Cursor detected)
|
|
321
|
+
3. `CURSOR_PROJECT_DIR` env var (Cursor child process)
|
|
322
|
+
4. Default: `claude_code`
|
|
323
|
+
|
|
324
|
+
### Global Override
|
|
325
|
+
|
|
326
|
+
If you want all hosts to share a single workspace (instead of per-host isolation), set `globalOverride: true` and a flat `workspace` field:
|
|
327
|
+
|
|
328
|
+
```jsonc
|
|
329
|
+
{
|
|
330
|
+
"globalOverride": true,
|
|
331
|
+
"workspace": "shared",
|
|
332
|
+
"hosts": {
|
|
333
|
+
"claude_code": { "aiPeer": "claude" },
|
|
334
|
+
"cursor": { "aiPeer": "cursor" }
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
All tools will read and write to the `shared` workspace. Each tool still uses its own AI peer name.
|
|
340
|
+
|
|
341
|
+
### Team Setup with Shared Context
|
|
342
|
+
|
|
343
|
+
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.
|
|
344
|
+
|
|
345
|
+
**Person A** (`~/.honcho/config.json`):
|
|
346
|
+
```json
|
|
347
|
+
{
|
|
348
|
+
"apiKey": "hch-v2-team-key...",
|
|
349
|
+
"peerName": "alice",
|
|
350
|
+
"hosts": {
|
|
351
|
+
"claude_code": {
|
|
352
|
+
"workspace": "team-acme",
|
|
353
|
+
"aiPeer": "claude"
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
}
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
**Person B** (`~/.honcho/config.json`):
|
|
360
|
+
```json
|
|
361
|
+
{
|
|
362
|
+
"apiKey": "hch-v2-team-key...",
|
|
363
|
+
"peerName": "bob",
|
|
364
|
+
"hosts": {
|
|
365
|
+
"claude_code": {
|
|
366
|
+
"workspace": "team-acme",
|
|
367
|
+
"aiPeer": "claude"
|
|
368
|
+
}
|
|
369
|
+
}
|
|
370
|
+
}
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
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.
|
|
374
|
+
|
|
375
|
+
### Environment Variables
|
|
376
|
+
|
|
377
|
+
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`.
|
|
378
|
+
|
|
379
|
+
| Variable | Required | Default | Description |
|
|
380
|
+
| ---------------------- | -------- | ------------- | ----------------------------------------------------------------- |
|
|
381
|
+
| `HONCHO_API_KEY` | **Yes** | — | Your Honcho API key from [app.honcho.dev](https://app.honcho.dev) |
|
|
382
|
+
| `HONCHO_PEER_NAME` | No | `$USER` | Your identity in the memory system |
|
|
383
|
+
| `HONCHO_WORKSPACE` | No | `claude_code` | Workspace name (used only when no config file exists) |
|
|
384
|
+
| `HONCHO_AI_PEER` | No | `claude` | AI peer name |
|
|
385
|
+
| `HONCHO_HOST` | No | auto-detected | Force host detection: `claude_code`, `cursor`, or `obsidian` |
|
|
386
|
+
| `HONCHO_ENDPOINT` | No | `production` | `production`, `local`, or a full URL |
|
|
387
|
+
| `HONCHO_ENABLED` | No | `true` | Set to `false` to disable |
|
|
388
|
+
| `HONCHO_SAVE_MESSAGES` | No | `true` | Set to `false` to stop saving messages |
|
|
389
|
+
| `HONCHO_LOGGING` | No | `true` | Set to `false` to disable file logging to `~/.honcho/` |
|
|
390
|
+
|
|
391
|
+
## How It Works
|
|
392
|
+
|
|
393
|
+
```
|
|
394
|
+
┌─────────────────────────────────────────────────────────────────┐
|
|
395
|
+
│ Claude Code │
|
|
396
|
+
├─────────────────────────────────────────────────────────────────┤
|
|
397
|
+
│ SessionStart │ UserPrompt │ PostToolUse │ SessionEnd │
|
|
398
|
+
│ ─────────── │ ─────────── │ ──────────── │ ────────── │
|
|
399
|
+
│ Load context │ Save message │ Log activity │ Upload all │
|
|
400
|
+
│ from Honcho │ to Honcho │ to Honcho │ + summary │
|
|
401
|
+
└─────────────────────────────────────────────────────────────────┘
|
|
402
|
+
│
|
|
403
|
+
▼
|
|
404
|
+
┌─────────────────────────────────────────────────────────────────┐
|
|
405
|
+
│ Honcho API │
|
|
406
|
+
│ │
|
|
407
|
+
│ Your messages and Claude's work → Persistent Memory → │
|
|
408
|
+
│ Retrieved as context at session start │
|
|
409
|
+
└─────────────────────────────────────────────────────────────────┘
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
The plugin hooks into Claude Code's lifecycle events:
|
|
413
|
+
|
|
414
|
+
- **SessionStart**: Loads your context and history from Honcho
|
|
415
|
+
- **UserPrompt**: Saves your messages and retrieves relevant context
|
|
416
|
+
- **PostToolUse**: Logs Claude's actions (file edits, commands, etc.)
|
|
417
|
+
- **PreCompact**: Anchors a memory snapshot before context compaction so knowledge survives summarization
|
|
418
|
+
- **Stop**: Flushes any pending messages
|
|
419
|
+
- **SessionEnd**: Uploads remaining messages and generates a summary
|
|
420
|
+
|
|
421
|
+
## Troubleshooting
|
|
422
|
+
|
|
423
|
+
### "Not configured" or no memory loading
|
|
424
|
+
|
|
425
|
+
1. **Check your API key is set:**
|
|
426
|
+
|
|
427
|
+
```bash
|
|
428
|
+
echo $HONCHO_API_KEY # macOS / Linux
|
|
429
|
+
echo $env:HONCHO_API_KEY # Windows PowerShell
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
If empty, set it (see Step 2 in Quick Start) and restart your terminal.
|
|
433
|
+
|
|
434
|
+
2. **Check the plugin is installed:**
|
|
435
|
+
|
|
436
|
+
```
|
|
437
|
+
/plugin
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
You should see `honcho@honcho` in the list.
|
|
441
|
+
|
|
442
|
+
3. **Restart Claude Code** after making changes.
|
|
443
|
+
|
|
444
|
+
4. **Run `/honcho:status`** to see connection state, workspace, and session info.
|
|
445
|
+
|
|
446
|
+
### Memory not persisting between sessions
|
|
447
|
+
|
|
448
|
+
Make sure `saveMessages` is not set to `false` in your config (or `HONCHO_SAVE_MESSAGES` in env).
|
|
449
|
+
|
|
450
|
+
### Using a local Honcho instance
|
|
451
|
+
|
|
452
|
+
Via config file:
|
|
453
|
+
```json
|
|
454
|
+
{ "endpoint": { "environment": "local" } }
|
|
455
|
+
```
|
|
456
|
+
|
|
457
|
+
Or via env var:
|
|
458
|
+
```bash
|
|
459
|
+
export HONCHO_ENDPOINT="local" # Uses localhost:8000
|
|
460
|
+
# or
|
|
461
|
+
export HONCHO_ENDPOINT="http://your-server:8000/v3"
|
|
462
|
+
```
|
|
463
|
+
|
|
464
|
+
### Temporarily disabling memory
|
|
465
|
+
|
|
466
|
+
```bash
|
|
467
|
+
export HONCHO_ENABLED="false"
|
|
468
|
+
```
|
|
469
|
+
|
|
470
|
+
Or set `"enabled": false` in your config file. Restart Claude Code to take effect.
|
|
471
|
+
|
|
472
|
+
---
|
|
473
|
+
|
|
474
|
+
# `honcho-dev` Plugin
|
|
475
|
+
|
|
476
|
+
**Skills for building AI applications with the Honcho SDK.**
|
|
477
|
+
|
|
478
|
+
This plugin provides skills to help you integrate Honcho into your projects and migrate between SDK versions.
|
|
479
|
+
|
|
480
|
+
## Skills
|
|
481
|
+
|
|
482
|
+
| Command | Description |
|
|
483
|
+
| ------------------------ | -------------------------------------------------- |
|
|
484
|
+
| `/honcho-dev:integrate` | Add Honcho memory to your project or bot framework |
|
|
485
|
+
| `/honcho-dev:migrate-py` | Migrate Python code to the latest Honcho SDK |
|
|
486
|
+
| `/honcho-dev:migrate-ts` | Migrate TypeScript code to the latest Honcho SDK |
|
|
487
|
+
|
|
488
|
+
## Installation
|
|
489
|
+
|
|
490
|
+
```
|
|
491
|
+
/plugin install honcho-dev@honcho
|
|
492
|
+
```
|
|
493
|
+
|
|
494
|
+
---
|
|
495
|
+
|
|
496
|
+
## Uninstalling
|
|
497
|
+
|
|
498
|
+
```
|
|
499
|
+
/plugin uninstall honcho@honcho
|
|
500
|
+
/plugin uninstall honcho-dev@honcho
|
|
501
|
+
/plugin marketplace remove honcho
|
|
502
|
+
```
|
|
503
|
+
|
|
504
|
+
Then remove the environment variables from your shell config if desired.
|
|
505
|
+
|
|
506
|
+
---
|
|
507
|
+
|
|
508
|
+
## License
|
|
509
|
+
|
|
510
|
+
MIT — see [LICENSE](LICENSE)
|
|
511
|
+
|
|
512
|
+
---
|
|
513
|
+
|
|
514
|
+
## Links
|
|
515
|
+
|
|
516
|
+
- **Issues**: [GitHub Issues](https://github.com/plastic-labs/honcho/issues)
|
|
517
|
+
- **Discord**: [Join the Community](https://discord.gg/plasticlabs)
|
|
518
|
+
- **X (Twitter)**: [@honchodotdev](https://x.com/honchodotdev)
|
|
519
|
+
- **Plastic Labs**: [plasticlabs.ai](https://plasticlabs.ai)
|
|
520
|
+
- **Honcho**: [honcho.dev](https://honcho.dev) — The memory API
|
|
521
|
+
- **Documentation**: [docs.honcho.dev](https://docs.honcho.dev)
|
|
522
|
+
- **Blog**: [Read about Honcho, Agents, and Memory](https://blog.plasticlabs.ai)
|
package/package.json
CHANGED
package/scripts/check-version.sh
CHANGED
|
@@ -25,13 +25,12 @@ LOCAL_VERSION=$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p
|
|
|
25
25
|
[ -z "$LOCAL_VERSION" ] && exit 0
|
|
26
26
|
|
|
27
27
|
REMOTE_JSON=$(curl --max-time 2 -fsSL \
|
|
28
|
-
"https://
|
|
28
|
+
"https://registry.npmjs.org/@honcho-ai/claude-honcho/latest" \
|
|
29
29
|
2>/dev/null) || exit 0
|
|
30
30
|
|
|
31
|
-
# Pull the version of the "honcho" plugin entry. Naive but adequate for our schema.
|
|
32
31
|
REMOTE_VERSION=$(printf '%s' "$REMOTE_JSON" \
|
|
33
32
|
| tr -d '\n' \
|
|
34
|
-
| sed -n 's/.*"
|
|
33
|
+
| sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' \
|
|
35
34
|
| head -n1)
|
|
36
35
|
[ -z "$REMOTE_VERSION" ] && exit 0
|
|
37
36
|
|