@honcho-ai/claude-honcho 0.3.0-rc.1 → 0.3.2

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.
Files changed (63) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/LICENSE +21 -0
  3. package/README.md +605 -0
  4. package/dist/chunk-1nsms6f4.js +50 -0
  5. package/dist/chunk-1nsms6f4.js.map +10 -0
  6. package/dist/{chunk-jr0fd6n2.js → chunk-1xa1wr00.js} +2 -2
  7. package/dist/{chunk-9pntsn3x.js → chunk-43gww8dc.js} +1 -1
  8. package/dist/chunk-81cb25yy.js +35 -0
  9. package/dist/{chunk-6yybt92z.js.map → chunk-81cb25yy.js.map} +1 -1
  10. package/dist/{chunk-yfrrc1d5.js → chunk-acwn3613.js} +64 -106
  11. package/dist/chunk-acwn3613.js.map +13 -0
  12. package/dist/{chunk-49wja30f.js → chunk-d99xh4kg.js} +1 -1
  13. package/dist/{chunk-xdntcesh.js → chunk-g0m354bn.js} +758 -210
  14. package/dist/{chunk-xdntcesh.js.map → chunk-g0m354bn.js.map} +8 -4
  15. package/dist/{chunk-4ryv9310.js → chunk-mm5vjhpr.js} +240 -210
  16. package/dist/{chunk-4ryv9310.js.map → chunk-mm5vjhpr.js.map} +2 -2
  17. package/dist/{chunk-d2gc13m0.js → chunk-pdnbydfe.js} +10 -12
  18. package/dist/{chunk-d2gc13m0.js.map → chunk-pdnbydfe.js.map} +2 -2
  19. package/dist/{chunk-xtdvbfxw.js → chunk-qp4ng9m0.js} +6 -6
  20. package/dist/{chunk-xtdvbfxw.js.map → chunk-qp4ng9m0.js.map} +2 -2
  21. package/dist/{chunk-4zgbdwm4.js → chunk-w3tnmcx7.js} +6 -6
  22. package/dist/{chunk-4zgbdwm4.js.map → chunk-w3tnmcx7.js.map} +1 -1
  23. package/dist/hooks/post-tool-use.js +22 -21
  24. package/dist/hooks/post-tool-use.js.map +3 -3
  25. package/dist/hooks/pre-compact.js +21 -65
  26. package/dist/hooks/pre-compact.js.map +3 -4
  27. package/dist/hooks/pre-tool-honcho.js +5 -5
  28. package/dist/hooks/pre-tool-honcho.js.map +1 -1
  29. package/dist/hooks/save-user-message.js +45 -27
  30. package/dist/hooks/save-user-message.js.map +4 -3
  31. package/dist/hooks/session-end.js +13 -13
  32. package/dist/hooks/session-end.js.map +2 -2
  33. package/dist/hooks/session-start.js +38 -38
  34. package/dist/hooks/session-start.js.map +2 -2
  35. package/dist/hooks/stop.js +20 -20
  36. package/dist/hooks/stop.js.map +1 -1
  37. package/dist/hooks/user-prompt.js +367 -10
  38. package/dist/hooks/user-prompt.js.map +5 -3
  39. package/dist/mcp-server.js +550 -739
  40. package/dist/mcp-server.js.map +3 -3
  41. package/dist/skills/backfill-runner.js +545 -47
  42. package/dist/skills/backfill-runner.js.map +9 -4
  43. package/dist/skills/setup-runner.js +47 -194
  44. package/dist/skills/setup-runner.js.map +4 -6
  45. package/dist/skills/status-runner.js +16 -17
  46. package/dist/skills/status-runner.js.map +2 -2
  47. package/package.json +1 -1
  48. package/scripts/check-version.sh +2 -3
  49. package/dist/chunk-084dpgp3.js +0 -556
  50. package/dist/chunk-084dpgp3.js.map +0 -10
  51. package/dist/chunk-6yybt92z.js +0 -106
  52. package/dist/chunk-dxbm7kmf.js +0 -331
  53. package/dist/chunk-dxbm7kmf.js.map +0 -10
  54. package/dist/chunk-gnp95nzg.js +0 -438
  55. package/dist/chunk-gnp95nzg.js.map +0 -12
  56. package/dist/chunk-jgtvcc65.js +0 -90
  57. package/dist/chunk-jgtvcc65.js.map +0 -10
  58. package/dist/chunk-wm6hvkcv.js +0 -245
  59. package/dist/chunk-wm6hvkcv.js.map +0 -10
  60. package/dist/chunk-yfrrc1d5.js.map +0 -12
  61. /package/dist/{chunk-jr0fd6n2.js.map → chunk-1xa1wr00.js.map} +0 -0
  62. /package/dist/{chunk-9pntsn3x.js.map → chunk-43gww8dc.js.map} +0 -0
  63. /package/dist/{chunk-49wja30f.js.map → chunk-d99xh4kg.js.map} +0 -0
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "honcho",
3
- "version": "0.3.0-rc.1",
3
+ "version": "0.3.2",
4
4
  "description": "Persistent memory for Claude Code sessions using Honcho by Plastic Labs",
5
5
  "author": {
6
6
  "name": "Plastic Labs",
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,605 @@
1
+ # Honcho Plugins for Claude Code
2
+
3
+ [![Honcho Banner](./assets/honcho_clawd.png)](https://honcho.dev)
4
+
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
+ [![npm](https://img.shields.io/npm/v/@honcho-ai/claude-honcho)](https://www.npmjs.com/package/@honcho-ai/claude-honcho)
7
+ [![Honcho](https://img.shields.io/badge/Honcho-Memory%20API-blue)](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)
48
+ - [Node.js](https://nodejs.org) on your PATH
49
+
50
+ The plugin ships as a self-contained bundle -- no other dependencies needed.
51
+
52
+ ## Quick Start
53
+
54
+ ### Step 1: Get Your Honcho API Key
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
93
+
94
+ ```
95
+ /plugin marketplace add plastic-labs/claude-honcho
96
+ /plugin install honcho@honcho
97
+ ```
98
+
99
+ ### Step 4: Restart Claude Code
100
+
101
+ ```bash
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
+ ```
106
+
107
+ ### Step 5: (Optional) Kick off your conversation with an interview
108
+
109
+ ```
110
+ /honcho:interview
111
+ ```
112
+
113
+ Claude will interview you about your personal preferences in order to kickstart a representation
114
+ of you. What it learns will be saved in Honcho and remembered forever. The interview is specific
115
+ to the peer name you chose in your environment: it will carry across different projects!
116
+
117
+ ## What You Get
118
+
119
+ - **Persistent Memory** — Claude remembers your preferences, projects, and context across sessions
120
+ - **Survives Context Wipes** — Even when Claude's context window resets, memory persists
121
+ - **Git Awareness** — Detects branch switches, commits, and changes made outside Claude
122
+ - **Flexible Sessions** — Map sessions per directory, per git branch, or per chat instance
123
+ - **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
+ - **Team Support** — Multiple people can share a workspace and build context together
126
+ - **MCP Tools** — Search memory, query knowledge about you, and save insights
127
+
128
+ ## MCP Tools
129
+
130
+ The honcho plugin provides these tools via MCP:
131
+
132
+ | Tool | Description |
133
+ | -------------------- | -------------------------------------------------------------- |
134
+ | `search` | Semantic search across session messages and saved conclusions |
135
+ | `chat` | Query Honcho's knowledge about the user (dialectic reasoning) |
136
+ | `create_conclusion` | Save insights about the user to memory |
137
+ | `list_conclusions` | List saved conclusions |
138
+ | `query_conclusions` | Semantic search over saved conclusions |
139
+ | `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
+ | `get_config` | View current configuration and status |
144
+ | `set_config` | Change any configuration field programmatically |
145
+ | `honcho_remember` | Fan-out dialectic recall (only registered when `rememberTool: true`) |
146
+
147
+ ## Skills
148
+
149
+ | Command | Description |
150
+ | ------------------- | ----------------------------------------------------------- |
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
+ | `/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
+ | `/honcho:insights` | Distill memory into CLAUDE.md edits, style rules, skill ideas |
158
+
159
+ ---
160
+
161
+ ## Configuration
162
+
163
+ 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.
164
+
165
+ ### Config File Reference
166
+
167
+ ```jsonc
168
+ {
169
+ // Required
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
176
+ "hosts": {
177
+ "claude_code": {
178
+ "workspace": "claude_code", // Workspace for Claude Code sessions
179
+ "aiPeer": "claude", // AI identity in this workspace
180
+ },
181
+ "cursor": {
182
+ "workspace": "cursor",
183
+ "aiPeer": "cursor"
184
+ }
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
+ }
302
+ }
303
+ ```
304
+
305
+ Then restart Claude Code — MCP tools register at startup.
306
+
307
+ When it's on, the injected session-start directives steer Claude to use it proactively as the primary recall path.
308
+
309
+ ### Observation Mode
310
+
311
+ Controls how Honcho stores and retrieves conclusions about you. Change it via `set_config` or edit `config.json` directly. Requires a Claude Code restart.
312
+
313
+ | Mode | Behavior | Best for |
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 |
317
+
318
+ > **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.
319
+
320
+ To change:
321
+
322
+ - Ask Claude: *"Set my observation mode to directional"*
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
+ ```
335
+
336
+ > **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.
337
+
338
+ ### Migrating Observations
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
+ ```
382
+
383
+ If you use multiple AI agents, run the script once per agent:
384
+
385
+ ```bash
386
+ # Migrate Claude's observations to unified
387
+ python scripts/migrate-observations.py -w agents --from-observer claude --user ajspig
388
+
389
+ # Migrate Hermes' observations to unified
390
+ python scripts/migrate-observations.py -w agents --from-observer hermes --user ajspig
391
+ ```
392
+
393
+ Run with `--help` for all options.
394
+
395
+ 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.
396
+
397
+ ### Host-Aware Configuration
398
+
399
+ 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.
400
+
401
+ **Host detection priority:**
402
+ 1. `HONCHO_HOST` env var (explicit override)
403
+ 2. `cursor_version` in hook stdin (Cursor detected)
404
+ 3. `CURSOR_PROJECT_DIR` env var (Cursor child process)
405
+ 4. Default: `claude_code`
406
+
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
+ ### Team Setup with Shared Context
425
+
426
+ 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.
427
+
428
+ **Person A** (`~/.honcho/config.json`):
429
+ ```json
430
+ {
431
+ "apiKey": "hch-v2-team-key...",
432
+ "peerName": "alice",
433
+ "hosts": {
434
+ "claude_code": {
435
+ "workspace": "team-acme",
436
+ "aiPeer": "claude"
437
+ }
438
+ }
439
+ }
440
+ ```
441
+
442
+ **Person B** (`~/.honcho/config.json`):
443
+ ```json
444
+ {
445
+ "apiKey": "hch-v2-team-key...",
446
+ "peerName": "bob",
447
+ "hosts": {
448
+ "claude_code": {
449
+ "workspace": "team-acme",
450
+ "aiPeer": "claude"
451
+ }
452
+ }
453
+ }
454
+ ```
455
+
456
+ 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.
457
+
458
+ ### Environment Variables
459
+
460
+ 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`.
461
+
462
+ | Variable | Required | Default | Description |
463
+ | ---------------------- | -------- | ------------- | ----------------------------------------------------------------- |
464
+ | `HONCHO_API_KEY` | **Yes** | — | Your Honcho API key from [app.honcho.dev](https://app.honcho.dev) |
465
+ | `HONCHO_PEER_NAME` | No | `$USER` | Your identity in the memory system |
466
+ | `HONCHO_WORKSPACE` | No | `claude_code` | Workspace name (used only when no config file exists) |
467
+ | `HONCHO_AI_PEER` | No | `claude` | AI peer name |
468
+ | `HONCHO_HOST` | No | auto-detected | Force host detection: `claude_code`, `cursor`, or `obsidian` |
469
+ | `HONCHO_ENDPOINT` | No | `production` | `production`, `local`, or a full URL |
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/` |
473
+
474
+ ## How It Works
475
+
476
+ ```
477
+ ┌─────────────────────────────────────────────────────────────────┐
478
+ │ Claude Code │
479
+ ├─────────────────────────────────────────────────────────────────┤
480
+ │ SessionStart │ UserPrompt │ PostToolUse │ SessionEnd │
481
+ │ ─────────── │ ─────────── │ ──────────── │ ────────── │
482
+ │ Load context │ Save message │ Log activity │ Upload all │
483
+ │ from Honcho │ to Honcho │ to Honcho │ + summary │
484
+ └─────────────────────────────────────────────────────────────────┘
485
+ │
486
+ ▼
487
+ ┌─────────────────────────────────────────────────────────────────┐
488
+ │ Honcho API │
489
+ │ │
490
+ │ Your messages and Claude's work → Persistent Memory → │
491
+ │ Retrieved as context at session start │
492
+ └─────────────────────────────────────────────────────────────────┘
493
+ ```
494
+
495
+ The plugin hooks into Claude Code's lifecycle events:
496
+
497
+ - **SessionStart**: Loads your context and history from Honcho
498
+ - **UserPrompt**: Saves your messages and retrieves relevant context
499
+ - **PostToolUse**: Logs Claude's actions (file edits, commands, etc.)
500
+ - **PreCompact**: Anchors a memory snapshot before context compaction so knowledge survives summarization
501
+ - **Stop**: Flushes any pending messages
502
+ - **SessionEnd**: Uploads remaining messages and generates a summary
503
+
504
+ ## Troubleshooting
505
+
506
+ ### "Not configured" or no memory loading
507
+
508
+ 1. **Check your API key is set:**
509
+
510
+ ```bash
511
+ echo $HONCHO_API_KEY # macOS / Linux
512
+ echo $env:HONCHO_API_KEY # Windows PowerShell
513
+ ```
514
+
515
+ If empty, set it (see Step 2 in Quick Start) and restart your terminal.
516
+
517
+ 2. **Check the plugin is installed:**
518
+
519
+ ```
520
+ /plugin
521
+ ```
522
+
523
+ You should see `honcho@honcho` in the list.
524
+
525
+ 3. **Restart Claude Code** after making changes.
526
+
527
+ 4. **Run `/honcho:status`** to see connection state, workspace, and session info.
528
+
529
+ ### Memory not persisting between sessions
530
+
531
+ Make sure `saveMessages` is not set to `false` in your config (or `HONCHO_SAVE_MESSAGES` in env).
532
+
533
+ ### Using a local Honcho instance
534
+
535
+ Via config file:
536
+ ```json
537
+ { "endpoint": { "environment": "local" } }
538
+ ```
539
+
540
+ Or via env var:
541
+ ```bash
542
+ export HONCHO_ENDPOINT="local" # Uses localhost:8000
543
+ # or
544
+ export HONCHO_ENDPOINT="http://your-server:8000/v3"
545
+ ```
546
+
547
+ ### Temporarily disabling memory
548
+
549
+ ```bash
550
+ export HONCHO_ENABLED="false"
551
+ ```
552
+
553
+ Or set `"enabled": false` in your config file. Restart Claude Code to take effect.
554
+
555
+ ---
556
+
557
+ # `honcho-dev` Plugin
558
+
559
+ **Skills for building AI applications with the Honcho SDK.**
560
+
561
+ This plugin provides skills to help you integrate Honcho into your projects and migrate between SDK versions.
562
+
563
+ ## Skills
564
+
565
+ | Command | Description |
566
+ | ------------------------ | -------------------------------------------------- |
567
+ | `/honcho-dev:integrate` | Add Honcho memory to your project or bot framework |
568
+ | `/honcho-dev:migrate-py` | Migrate Python code to the latest Honcho SDK |
569
+ | `/honcho-dev:migrate-ts` | Migrate TypeScript code to the latest Honcho SDK |
570
+
571
+ ## Installation
572
+
573
+ ```
574
+ /plugin install honcho-dev@honcho
575
+ ```
576
+
577
+ ---
578
+
579
+ ## Uninstalling
580
+
581
+ ```
582
+ /plugin uninstall honcho@honcho
583
+ /plugin uninstall honcho-dev@honcho
584
+ /plugin marketplace remove honcho
585
+ ```
586
+
587
+ Then remove the environment variables from your shell config if desired.
588
+
589
+ ---
590
+
591
+ ## License
592
+
593
+ MIT — see [LICENSE](LICENSE)
594
+
595
+ ---
596
+
597
+ ## Links
598
+
599
+ - **Issues**: [GitHub Issues](https://github.com/plastic-labs/honcho/issues)
600
+ - **Discord**: [Join the Community](https://discord.gg/plasticlabs)
601
+ - **X (Twitter)**: [@honchodotdev](https://x.com/honchodotdev)
602
+ - **Plastic Labs**: [plasticlabs.ai](https://plasticlabs.ai)
603
+ - **Honcho**: [honcho.dev](https://honcho.dev) — The memory API
604
+ - **Documentation**: [docs.honcho.dev](https://docs.honcho.dev)
605
+ - **Blog**: [Read about Honcho, Agents, and Memory](https://blog.plasticlabs.ai)
@@ -0,0 +1,50 @@
1
+ // src/redact.ts
2
+ var DEFAULT_RULES = [
3
+ {
4
+ pattern: /\b(\w*(?:PASSWORD|PASSWD|PWD|SECRET|TOKEN|API_?KEY|ACCESS_KEY|CREDENTIALS?)\w*)\s*=\s*("[^"]*"|'[^']*'|[^\s;|&"']+)/gi,
5
+ replacement: "$1=***"
6
+ },
7
+ {
8
+ pattern: /(--(?:password|passwd|pwd|token|api-?key|secret|auth)[= ])(?:"[^"]*"|'[^']*'|[^\s;|&"']+)/gi,
9
+ replacement: "$1***"
10
+ },
11
+ {
12
+ pattern: /(authorization:\s*(?:bearer|basic|token)\s+)[^\s"']+/gi,
13
+ replacement: "$1***"
14
+ },
15
+ {
16
+ pattern: /([a-z][a-z0-9+.-]*:\/\/[^/\s:@]+:)[^@\s]+@/gi,
17
+ replacement: "$1***@"
18
+ },
19
+ {
20
+ pattern: /\b(?:hch[_-]?[A-Za-z0-9_-]{16,}|AKIA[0-9A-Z]{16}|sk-[A-Za-z0-9_-]{16,}|(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|glpat-[A-Za-z0-9_-]{20,}|npm_[A-Za-z0-9]{36})\b/g,
21
+ replacement: "***"
22
+ }
23
+ ];
24
+ function validateRedactPattern(source) {
25
+ try {
26
+ new RegExp(source);
27
+ return null;
28
+ } catch (e) {
29
+ return `Invalid regex ${JSON.stringify(source)}: ${e instanceof Error ? e.message : String(e)}`;
30
+ }
31
+ }
32
+ function redactSecrets(text, extraPatterns) {
33
+ let result = text;
34
+ for (const rule of DEFAULT_RULES) {
35
+ result = result.replace(rule.pattern, rule.replacement);
36
+ }
37
+ for (const source of extraPatterns ?? []) {
38
+ try {
39
+ result = result.replace(new RegExp(source, "gi"), "***");
40
+ } catch {
41
+ continue;
42
+ }
43
+ }
44
+ return result;
45
+ }
46
+
47
+ export { validateRedactPattern, redactSecrets };
48
+
49
+ //# debugId=69506780623A432464756E2164756E21
50
+ //# sourceMappingURL=chunk-1nsms6f4.js.map