docs: updating claude-codes with recent changes (#1021)

2026-08-14 17:39:14 -04:00 · 2026-08-14 17:39:14 -04:00 · 444897975c
parent 16f490e345
commit 444897975c
1 changed files with 135 additions and 32 deletions
--- a/docs/v3/guides/integrations/claude-code.mdx
+++ b/docs/v3/guides/integrations/claude-code.mdx
@ -37,7 +37,7 @@ source ~/.zshrc  # or ~/.bashrc
 ### Step 3: Install the Plugin

 <Note>
-This plugin requires [Bun](https://bun.sh). If you don't have it: `curl -fsSL https://bun.sh/install | bash`
+This plugin requires [Node.js](https://nodejs.org) on your PATH.
 </Note>

 Open Claude Code and run:
@ -74,10 +74,11 @@ Claude will interview you about your personal preferences to kickstart a represe

 - **Persistent Memory** — Claude remembers your preferences, projects, and context across sessions
 - **Survives Context Wipes** — Even when Claude's context window resets, memory persists
+- **Configurable Memory Injection** — Choose exactly what context is injected at session start and per turn
 - **Git Awareness** — Detects branch switches, commits, and changes made outside Claude
 - **Flexible Sessions** — Map sessions per directory, per git branch, or per chat instance
 - **AI Self-Awareness** — Claude knows what it was working on, even after restarts
- **Cross-Tool Context** — Link workspaces across Claude Code, Cursor, and other hosts so context flows between tools
+- **Secret Redaction** — Built-in patterns (plus your own) scrub secrets from tool summaries before upload
 - **Team Support** — Multiple people can share a workspace and build context together
 - **MCP Tools** — Search memory, query knowledge about you, and save insights

@ -97,8 +98,7 @@ All configuration lives in a single global file at `~/.honcho/config.json`. You
  "hosts": {
    "claude_code": {
      "workspace": "claude_code",   // Workspace for Claude Code sessions
-      "aiPeer": "claude",           // AI identity in this workspace
-      "linkedHosts": ["cursor"]     // Read context from other hosts (optional)
+      "aiPeer": "claude"            // AI identity in this workspace
    },
    "cursor": {
      "workspace": "cursor",
@ -112,6 +112,8 @@ All configuration lives in a single global file at `~/.honcho/config.json`. You

  // Message handling
  "saveMessages": true,
+  "saveToolUse": false,               // Save [Tool] action summaries (default: false)
+  "saveGitEvents": false,             // Save [Git External] state-change events (default: false)
  "messageUpload": {
    "maxUserTokens": null,            // Truncate user messages (null = no limit)
    "maxAssistantTokens": null,       // Truncate assistant messages (null = no limit)
@ -124,6 +126,19 @@ All configuration lives in a single global file at `~/.honcho/config.json`. You
    "ttlSeconds": 300,                // Cache TTL for context
    "skipDialectic": false            // Skip dialectic chat() calls in user-prompt hook
  },
+  "reasoningLevel": "medium",         // Default dialectic reasoning tier: "minimal" | "low" | "medium" | "high" | "max"
+
+  // Memory injection (see "Memory Injection" below)
+  "injection": {
+    "sessionStart": ["directives", "summary", "peerCard"],
+    "perTurn": ["userContext"]
+  },
+
+  // On-demand recall tool (see "The honcho_remember Tool" below)
+  "rememberTool": false,
+
+  // Observation mode
+  "observationMode": "unified",       // "unified" (default) | "directional"

  // Endpoint
  "endpoint": {
@ -132,7 +147,8 @@ All configuration lives in a single global file at `~/.honcho/config.json`. You
  },

  // Miscellaneous
-  "localContext": { "maxEntries": 50 },
+  "redactPatterns": [],               // Extra regexes redacted from tool summaries (additive to built-in secret patterns)
+  "statusline": "on",                 // Memory statusline visibility: "on" | "off"
  "enabled": true,
  "logging": true,

@ -141,7 +157,82 @@ All configuration lives in a single global file at `~/.honcho/config.json`. You
 }
 ```

-### Session Strategies
+## Memory Injection
+
+The `injection` config block controls exactly what memory is injected into Claude's context, on two surfaces: **once at session start** and **per prompt**. Each surface selects zero or more components; retrieval knobs shape what those components emit.
+
+Configure it interactively with `/honcho:config` (under the memory injection settings), by asking Claude to use `set_config`, or by editing `~/.honcho/config.json` directly.
+
+### Session-Start Components
+
+Injected once when a session opens. Default: `["directives", "summary", "peerCard"]`.
+
+| Component | What it injects |
+| --- | --- |
+| `directives` | Static memory-usage guidance — tells Claude to treat injected memory as background, use `chat`/`search` for recall, and save insights with `create_conclusion` |
+| `summary` | The session's long summary narrative (skipped on a fresh session) |
+| `peerCard` | Your peer card — a structured identity/attribute list |
+| `peerRepresentation` | Your full derived representation, injected at full length |
+| `briefing` | A nudge for Claude to call the `get_briefing` MCP tool instead of injecting the summary and peer card inline. The tool call renders as an expandable row in the UI, so you can see exactly what was loaded. Use it *in place of* `summary`/`peerCard`, not alongside them |
+
+```json
+{ "injection": { "sessionStart": ["directives", "briefing"] } }
+```
+
+### Per-Turn Components
+
+Injected with each non-trivial prompt. Default: `["userContext"]`.
+
+| Component | What it injects |
+| --- | --- |
+| `userContext` | A fresh, prompt-scoped context fetch for *you* — conclusions selected by semantic search over your representation, shaped by the retrieval knobs below |
+| `assistantContext` | The same context fetch, but for the AI peer — what Honcho has derived about the assistant itself |
+| `sessionContext` | Recent raw messages from the currently mapped Honcho session, which can span other Claude instances sharing the session name |
+| `dialectic` | A reasoned `chat()` answer over your representation, seeded from `dialecticTemplate`. Off by default — it is much slower than a context fetch, so it runs on its own time budget |
+
+### Retrieval Knobs
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `searchTopK` | `10` | Top-K conclusions pulled by the context fetch's semantic search |
+| `maxConclusions` | `15` | Max conclusions injected per context fetch |
+| `searchMaxDistance` | `0.6` | Max cosine distance for the semantic search — lower is stricter |
+| `searchQuerySource` | `"prompt"` | What drives the per-turn search: the raw `"prompt"` or extracted `"topics"` |
+| `sessionContextTokens` | `1500` | Token budget for the `sessionContext` message fetch |
+| `dialecticTemplate` | compact factual recall | Query template for the `dialectic` component; the user's prompt is substituted into `%{user_query}` |
+| `dialecticReasoning` | `"medium"` | Reasoning tier for the per-turn `dialectic` call — kept separate from the top-level `reasoningLevel` so per-turn dialectic can stay cheap |
+
+If injected context feels off-topic, lower `searchMaxDistance` (stricter relevance); if it feels too sparse, raise it or bump `searchTopK`.
+
+### Injection Visibility
+
+By default, per-turn components report a one-line summary in the terminal instead of printing their full contents. To see exactly what a component injects, list it in `showContents`:
+
+```json
+{ "injection": { "showContents": ["userContext", "sessionContext"] } }
+```
+
+Components not listed still inject — they just stay quiet about it.
+
+## The `honcho_remember` Tool
+
+An experimental on-demand recall tool. When enabled, Claude gets a `honcho_remember` MCP tool that fans out up to 5 parallel dialectic queries about you and returns per-question answers — useful before starting a task, when catching up ("where were we?"), or whenever your history could shape the response.
+
+To enable it, just ask Claude: *"Set my Honcho rememberTool config to true"* (it uses the `set_config` tool). Or set it in `~/.honcho/config.json`:
+
+```json
+{
+  "hosts": {
+    "claude_code": { "rememberTool": true }
+  }
+}
+```
+
+Then restart Claude Code — MCP tools register at startup.
+
+When it's on, the injected session-start directives steer Claude to use it proactively as the primary recall path.
+
+## Session Strategies

 Session strategy controls how Honcho maps your conversations to sessions:

@ -153,7 +244,20 @@ Session strategy controls how Honcho maps your conversations to sessions:

 Session names are prefixed with your `peerName` by default (e.g., `alice-my-project`). Set `sessionPeerPrefix: false` if you're the only user and want shorter names.

-### Host-Aware Configuration
+Linked git worktrees resolve to their main repository's session, so a worktree shares memory with the repo it belongs to.
+
+## Observation Mode
+
+Controls how Honcho stores and retrieves conclusions about you. Change it via `set_config` or edit `config.json` directly. Requires a Claude Code restart.
+
+| Mode | Behavior | Best for |
+| --- | --- | --- |
+| `unified` (default) | All agents write to your self-observation collection (`observer=you, observed=you`). Conclusions are portable — switch between agents without losing memory. | Most users — a unified context hub across agents |
+| `directional` | Each AI peer keeps its own separate view of you (`observer=aiPeer, observed=you`). | Multi-peer workspaces where you want isolated per-agent representations |
+
+Switching modes doesn't automatically migrate existing conclusions — each mode reads from a different collection. The [plugin repository](https://github.com/plastic-labs/claude-honcho) ships a `migrate-observations.py` script to copy conclusions between collections.
+
+## Host-Aware Configuration

 The plugin auto-detects which tool is running it (Claude Code, Cursor, etc.) and reads the matching block from `hosts`. Each host gets its own workspace and AI peer name, so data stays separated by default.

@ -163,28 +267,7 @@ The plugin auto-detects which tool is running it (Claude Code, Cursor, etc.) and
 3. `CURSOR_PROJECT_DIR` env var (Cursor child process)
 4. Default: `claude_code`

-### Linking Hosts for Cross-Tool Context
-
-If you use both Claude Code and Cursor, you can link them so context from one is readable in the other. Writes always stay in the current host's workspace — linking only adds read access.
-
-```jsonc
-{
-  "hosts": {
-    "claude_code": {
-      "workspace": "claude_code",
-      "aiPeer": "claude",
-      "linkedHosts": ["cursor"]  // Claude Code can read Cursor's context
-    },
-    "cursor": {
-      "workspace": "cursor",
-      "aiPeer": "cursor",
-      "linkedHosts": ["claude_code"]  // Cursor can read Claude Code's context
-    }
-  }
-}
-```
-
-Or use `/honcho:config` and select **Workspace > Linking** to set this up interactively.
+Each host block can also carry its own `apiKey` (useful when different tools authenticate against different Honcho orgs) and override most settings — `sessionStrategy`, `injection`, `rememberTool`, `observationMode`, and more.

 ### Global Override

@ -237,6 +320,14 @@ Multiple people can share context by pointing to the same workspace. Each person

 Both Alice and Bob write to the `team-acme` workspace. Their sessions are namespaced (e.g., `alice-my-project`, `bob-my-project`) so data doesn't collide, but Honcho's dialectic reasoning can draw on context from both users.

+## Secret Redaction
+
+Tool-capture summaries are scrubbed against built-in secret patterns (API keys, tokens, credentials) before upload. Add your own patterns with `redactPatterns` — an array of regexes applied on top of the defaults:
+
+```json
+{ "redactPatterns": ["internal-[a-z0-9]+", "ACME_SECRET_\\w+"] }
+```
+
 ## Logging

 The plugin logs activity to `~/.honcho/` and to Claude Code's verbose mode, so you can see exactly how Honcho is being used — what context is loaded at session start, what messages are saved, and what context is injected into Claude's prompts. Set `logging` to `false` in your config (or `HONCHO_LOGGING=false`) to disable file logging.
@ -247,20 +338,30 @@ The plugin provides these tools via MCP:

 | Tool | Description |
 |------|-------------|
-| `search` | Semantic search across session messages |
-| `chat` | Query Honcho's knowledge about the user |
+| `search` | Semantic search across session messages and saved conclusions |
+| `chat` | Query Honcho's knowledge about the user (dialectic reasoning) |
 | `create_conclusion` | Save insights about the user to memory |
+| `list_conclusions` | List saved conclusions |
+| `query_conclusions` | Semantic search over saved conclusions |
+| `delete_conclusion` | Delete a conclusion by ID |
+| `get_briefing` | Load the session briefing: session summary + peer card |
+| `get_context` | Retrieve the full context object (representation + peer card) |
+| `get_representation` | Retrieve the user's representation string |
 | `get_config` | View current configuration and status |
 | `set_config` | Change any configuration field programmatically |
+| `honcho_remember` | Fan-out dialectic recall (only registered when `rememberTool: true`) |

 ## Skills (Slash Commands)

 | Command | Description |
 | ------- | ----------- |
 | `/honcho:status` | Show current memory status and connection info |
-| `/honcho:config` | Interactive configuration menu |
+| `/honcho:config` | Interactive configuration menu (including memory injection settings) |
 | `/honcho:setup` | First-time setup — validate API key and create config |
 | `/honcho:interview` | Interview to capture stable, cross-project user preferences |
+| `/honcho:briefing` | Load the session briefing via a visible tool call |
+| `/honcho:import` | Backfill past Claude Code sessions into Honcho memory |
+| `/honcho:insights` | Distill memory into CLAUDE.md edits, style rules, and skill ideas |

 ### The Interview

@ -289,6 +390,8 @@ Environment variables work for initial bootstrap (before a config file exists).
 | `HONCHO_ENDPOINT` | No | `production` | `production`, `local`, or a full URL |
 | `HONCHO_ENABLED` | No | `true` | Set to `false` to disable |
 | `HONCHO_SAVE_MESSAGES` | No | `true` | Set to `false` to stop saving messages |
+| `HONCHO_SAVE_TOOL_USE` | No | `false` | Set to `true` to save tool action summaries |
+| `HONCHO_SAVE_GIT_EVENTS` | No | `false` | Set to `true` to save external git state-change events |
 | `HONCHO_LOGGING` | No | `true` | Set to `false` to disable file logging to `~/.honcho/` |

 ### Using a local Honcho instance