From 29bf690704ec6a22b82e517e29f062f8f9c114bf Mon Sep 17 00:00:00 2001 From: ajspig Date: Fri, 12 Jun 2026 15:53:12 -0400 Subject: [PATCH] docs: split honcho-mcp skill out of honcho-memory; address PR review Restructure honcho-memory into a concepts/strategy hub that routes to per-connection path skills, and add a dedicated honcho-mcp skill holding the MCP-tool mechanics that previously lived inline. Addresses review feedback on #784: - honcho-memory step 2 now leads with fast context reads, with chat as the slower escalation - honcho-mcp adds a "Speed: reads vs reasoning" section, describes what each context call returns, and a reasoning-levels table - get_representation framed as a contextualized snapshot insertable into a system prompt - drop schedule_dream from the tool table (manual escape hatch, not routine guidance) - prune queue-status references from honcho-cli; document honcho-mcp in vibecoding skill registry Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/skills/honcho-cli/SKILL.md | 6 +- .claude/skills/honcho-mcp/SKILL.md | 89 ++++++++++++++ .claude/skills/honcho-memory/SKILL.md | 109 +++--------------- .../documentation/introduction/vibecoding.mdx | 8 +- 4 files changed, 109 insertions(+), 103 deletions(-) create mode 100644 .claude/skills/honcho-mcp/SKILL.md diff --git a/.claude/skills/honcho-cli/SKILL.md b/.claude/skills/honcho-cli/SKILL.md index e2276669..716d6227 100644 --- a/.claude/skills/honcho-cli/SKILL.md +++ b/.claude/skills/honcho-cli/SKILL.md @@ -1,6 +1,6 @@ --- name: honcho-cli -description: Inspect and debug Honcho workspaces via the `honcho` CLI. Use when investigating peer representations, memory state, session context, queue status, or dialectic quality — any task that requires introspection of a Honcho deployment. +description: Inspect and debug Honcho workspaces via the `honcho` CLI. Use when investigating peer representations, memory state, session context, or dialectic quality — any task that requires introspection of a Honcho deployment, including verifying that a recall/record memory loop is actually working. allowed-tools: Bash(honcho:*), Bash(jq:*), Read, Grep --- @@ -30,7 +30,6 @@ allowed-tools: Bash(honcho:*), Bash(jq:*), Read, Grep - Run `honcho peer inspect` before `honcho peer chat` to understand context. - Use `honcho session context` to see exactly what an agent receives. - Never run `honcho workspace delete` without `honcho workspace inspect` first. -- Check queue status when derivation seems stalled. - Compare peer card with conclusions to understand memory state. ## Inspection tour @@ -82,9 +81,6 @@ honcho peer search "query" --json # Is observation enabled? honcho peer inspect --json | jq '.configuration' -# Is the deriver queue processing messages? -honcho workspace queue-status --json - # What conclusions exist? honcho conclusion list --observer --json honcho conclusion search "expected topic" --observer --json diff --git a/.claude/skills/honcho-mcp/SKILL.md b/.claude/skills/honcho-mcp/SKILL.md new file mode 100644 index 00000000..a84c69aa --- /dev/null +++ b/.claude/skills/honcho-mcp/SKILL.md @@ -0,0 +1,89 @@ +--- +name: honcho-mcp +description: Use Honcho as memory through its MCP server — recall what's known about the user and record turns so it keeps learning. Use when you have Honcho MCP tools available (create_session, add_messages_to_session, chat, search, conclusions, etc.) and want to remember a user across conversations. For the CLI access path use honcho-cli; for the concepts behind the loop see honcho-memory. +--- + +# Using Honcho via MCP + +You're connected to Honcho through its MCP server. This skill is the mechanics of the **recall → respond → record** loop using the MCP tools. For the mental model (peers, sessions, conclusions, why token-batching matters), see the `honcho-memory` skill; for the `honcho` CLI access path, see `honcho-cli`. + +> Tool names can vary slightly by deployment — check your actual tool list. This is the canonical set from `mcp.honcho.dev`. + +## Recommended flow + +``` +# 1. Once per conversation: session + peers +create_session session_id: "" +create_peer peer_id: "" +create_peer peer_id: "Assistant" +add_peers_to_session session_id: "" + peers: + - peer_id: "" observe_me: true observe_others: true + - peer_id: "Assistant" observe_me: false observe_others: true + +# 2. Before responding (when personalization helps): ask what Honcho knows +chat peer_id: "Assistant" + target_peer_id: "" + session_id: "" + query: "What communication style does this user prefer?" + +# 3. After every exchange: record the turn +add_messages_to_session session_id: "" + messages: + - peer_id: "" content: "" + - peer_id: "Assistant" content: "" +``` + +**Reuse the same `session_id` for the whole continuous conversation** (don't mint a new one per turn) — that's what lets the user's messages accumulate past the ~1,000-token reasoning threshold so Honcho actually reasons over them. And use **one stable `peer_id` per real person**, reused across every session and channel; a fresh or per-channel ID (`user-web` vs `user-discord`) builds separate, weaker representations instead of one. Set `observe_me: false` on the assistant peer — you want a model of the user, not of yourself. Reasoning is asynchronous; don't poll or wait for it. + +## Other useful tools + +| Tool | When to use | +| --- | --- | +| `search` | Semantic search across past messages (scope by peer or session). | +| `get_representation` | A contextualized snapshot of the peer's representation, as text you can drop straight into a system prompt to ground the model in who the user is. Fast read. | +| `get_peer_context` / `get_session_context` | Fuller context. `get_session_context` returns a blend of session summary + recent messages covering the whole session; pass a peer target to also fold in that peer's representation (otherwise it's session-local). `get_peer_context` returns the peer's representation + peer card. | +| `get_peer_card` / `set_peer_card` | Read or correct compact biographical facts. | +| `create_conclusions` | Store a fact directly instead of waiting for background reasoning. | +| `list_conclusions` / `query_conclusions` | Review what's known (check before storing duplicates) or find one to delete. | +| `delete_conclusion` | Remove an incorrect or outdated fact. | + +## Speed: reads vs. reasoning + +- **`chat` is the slow one** — it runs the dialectic (live reasoning over the user's memory), so it takes a few seconds. Use it when you need a reasoned answer, not for every turn. +- **`get_context` / `get_peer_context` / `get_representation` / `search` are reads** — near-instantaneous. Reach for these first when you just need the current representation or history; only call `chat` when you actually need reasoning. + +## Reasoning levels + +`chat` takes an optional `reasoning_level` (defaults to `low`) that trades speed for depth. Pick by task; higher = slower and costs more: + +| Level | Good for | +|-------|----------| +| `minimal` | fast factual lookups | +| `low` | default balance | +| `medium` | multi-step or ambiguous questions | +| `high` | complex synthesis across sources | +| `max` | deep research, the hardest queries | + +Full mechanics (model routing, thinking budgets, tool counts) are in the [chat docs](https://honcho.dev/docs/v3/documentation/features/chat.md). + +## Verifying it's working + +If memory seems off (the user isn't being remembered, `chat` comes back empty), the fastest way to check whether messages landed and the representation is building is the `honcho` CLI — see the **`honcho-cli`** skill (`honcho peer inspect`, `honcho conclusion list`, `honcho session context`). Reasoning is asynchronous and token-batched, so a brand-new or low-volume peer legitimately has little to show yet. + +## Connecting (if not connected yet) + +Get a free API key at (starts with `hch-`). Point your client at `https://mcp.honcho.dev` with two headers: + +- `Authorization: Bearer hch-your-key-here` +- `X-Honcho-User-Name: YourName` (what Honcho should call the user) + +Optional: `X-Honcho-Assistant-Name` (default `Assistant`) and `X-Honcho-Workspace-ID` (default `default`; set it to isolate memory per project). Client-specific config snippets (Claude Desktop, Claude Code, Cursor, Codex, Windsurf, VS Code, Cline, Zed) are in the [MCP integration guide](https://honcho.dev/docs/v3/guides/integrations/mcp.md). Restart the client fully after adding config. + +> Before hand-rolling, check whether your environment has a first-class Honcho integration that handles this for you: . + +## Resources + +- Full MCP usage walkthrough: +- MCP server & client setup: +- Full docs index (for agents): diff --git a/.claude/skills/honcho-memory/SKILL.md b/.claude/skills/honcho-memory/SKILL.md index ddff4bfc..b749829a 100644 --- a/.claude/skills/honcho-memory/SKILL.md +++ b/.claude/skills/honcho-memory/SKILL.md @@ -1,6 +1,6 @@ --- name: honcho-memory -description: Use a connected Honcho to give yourself persistent memory of the user — recall what you've learned about them and record new turns so you keep learning. Use when Honcho memory tools are available (via MCP or the honcho CLI) and you want to remember a user across conversations, recall their preferences, or store what was said. This is the runtime "how do I USE Honcho" skill — not for adding the SDK to a codebase (see honcho-integration for that). +description: Concepts and strategy for using a connected Honcho as persistent memory of the user — the recall/record loop, session and peer design, and token-batching so reasoning actually fires. Start here to understand how Honcho memory works, then use the path skill for your connection: honcho-mcp (MCP tools) or honcho-cli (CLI). For embedding the SDK into a codebase, use honcho-integration. --- # Using Honcho as Memory @@ -26,113 +26,29 @@ Reasoning happens **asynchronously**. After you record a turn, don't poll or wai Do this every conversation. It's the whole skill. 1. **Once per conversation** — make sure there's a session with you and the user as peers (observe the user, don't observe yourself). -2. **Before responding, when personalization helps** — ask Honcho what it knows about the user (`chat`), or pull relevant past context (`search`). Skip it for trivial turns; it costs a few seconds. +2. **Before responding, when personalization helps** — pull the user's current context (`get_context` / `get_representation`) or search past messages (`search`) — these are fast reads. For a reasoned answer to a specific question, ask the dialectic (`chat`) — that one takes a few seconds, so use it when it earns its keep. 3. **After every exchange** — record both the user's message and your reply. This is what makes Honcho learn. Don't skip it. Optionally, when you learn a durable fact you don't want to wait for background reasoning to surface, **store a conclusion** directly. --- -## How you're connected +## Pick your access path -Figure out which access path you have, then use the matching commands below. If you're unsure, list your available tools and look for Honcho memory tools (an MCP connection) before falling back to the CLI. +The loop is the same; the mechanics depend on how you reach Honcho. **Prefer a purpose-built integration over wiring up raw MCP yourself** — they handle sessions, peers, and the record loop for you, stay current, and are tuned per environment. -### Path A — MCP tools +1. **A first-class integration exists for your environment? Use it.** In Claude Code, install the [Claude Code plugin](https://honcho.dev/docs/v3/guides/integrations/claude-code.md) (`/plugin marketplace add plastic-labs/claude-honcho`) for persistent memory out of the box; there are also plugins/integrations for [OpenCode](https://honcho.dev/docs/v3/guides/integrations/opencode.md), LangGraph, CrewAI, Discord, and more. Browse the always-current list: . +2. **No integration, but you have MCP tools** (`create_session`, `add_messages_to_session`, `chat`, …) → use the **`honcho-mcp`** skill. The fallback for connected agents. +3. **`honcho` CLI available** in a terminal → use the **`honcho-cli`** skill — for the recall/record loop, and for verifying that memory is actually building (did messages land? is the representation growing? why doesn't it remember me?). +4. **Embedding Honcho into your own codebase** (not just using a connected instance) → use the **`honcho-integration`** skill. -The Honcho MCP server exposes these tools. Names can vary slightly by deployment, so check your actual tool list; this is the canonical set from `mcp.honcho.dev`. - -**Recommended flow:** - -``` -# 1. Once per conversation: session + peers -create_session session_id: "" -create_peer peer_id: "" -create_peer peer_id: "Assistant" -add_peers_to_session session_id: "" - peers: - - peer_id: "" observe_me: true observe_others: true - - peer_id: "Assistant" observe_me: false observe_others: true - -# 2. Before responding (when personalization helps): ask what Honcho knows -chat peer_id: "Assistant" - target_peer_id: "" - session_id: "" - query: "What communication style does this user prefer?" - -# 3. After every exchange: record the turn -add_messages_to_session session_id: "" - messages: - - peer_id: "" content: "" - - peer_id: "Assistant" content: "" -``` - -**Reuse the same `session_id` for the whole continuous conversation** (don't mint a new one per turn) — that's what lets the user's messages accumulate past the ~1,000-token reasoning threshold. And use **one stable `peer_id` per real person**, reused across every session and channel; a fresh or per-channel ID (`user-web` vs `user-discord`) builds separate, weaker representations instead of one. - -**Other useful tools:** - -| Tool | When to use | -| --- | --- | -| `search` | Semantic search across past messages (scope by peer or session). | -| `get_representation` | The user's representation as text — lightweight. | -| `get_peer_context` / `get_session_context` | Fuller context (representation + peer card, or LLM-ready history). Note: `get_session_context` is session-local — for cross-session memory, pass a peer target so it folds in that peer's representation. | -| `get_peer_card` / `set_peer_card` | Read or correct compact biographical facts. | -| `create_conclusions` | Store a fact directly instead of waiting for background reasoning. | -| `list_conclusions` / `query_conclusions` | Review what's known (check before storing duplicates) or find one to delete. | -| `delete_conclusion` | Remove an incorrect or outdated fact. | - -`chat` accepts an optional `reasoning_level` (`minimal` → `max`). Use `minimal`/`low` for quick lookups, `high`/`max` when depth genuinely matters — higher is slower and costs more. - -### Path B — `honcho` CLI - -If you have a terminal and the `honcho` CLI (`uv tool install honcho-cli`, then `honcho init`), the same loop maps to commands. Pass `--json` whenever you process output programmatically. - -```bash -# Recall — what does Honcho know about the user? -honcho peer chat "What communication style does this user prefer?" --json -honcho peer card --json -honcho peer search "topic" --json - -# Inspect what's stored -honcho conclusion list --observer --json -honcho conclusion search "topic" --observer --json -honcho session context --json - -# Record / correct -honcho conclusion create --observer "" -honcho conclusion delete -``` - -The CLI is strongest for **inspection and debugging** an existing deployment (peer memory, session context, queue status, dialectic quality). For deep debugging, see the `honcho-cli` skill. Note: recording live conversation turns is the MCP server's job — the CLI doesn't have a one-shot "add this exchange" command the way `add_messages_to_session` does. +If you're unsure, list your available tools and look for Honcho memory tools (an MCP connection) before falling back to the CLI. Even on the MCP path, the `honcho-cli` skill is the best way to **verify the loop is working** if memory seems off. --- ## Setup (if not connected yet) -You need a Honcho API key — get one free at . It starts with `hch-`. - -### First, check for a purpose-built integration - -Before hand-rolling raw MCP or CLI, see whether your environment already has a first-class Honcho integration or plugin — it'll handle session mapping, peer setup, and the record loop for you. - -**Fetch the integrations overview for the current list:** . It's the authoritative, always-current index — the specific integrations and install commands change often, so read it there rather than trusting any list baked into this skill. Broadly, it spans: - -- **Coding agents** (e.g. Claude Code, OpenCode plugins) -- **MCP clients** (Claude Desktop, Cursor, Windsurf, Cline, VS Code, and any MCP client) -- **Agent frameworks** (e.g. LangGraph, CrewAI, Vercel AI SDK, n8n) -- **Platform connectors** (e.g. Discord, Telegram, chat/email/meeting ingestion) - -If a purpose-built integration fits your environment, follow its guide from that page and skip the manual MCP/CLI setup below. If you're embedding Honcho into your own Python/TypeScript codebase, use the `honcho-integration` skill instead. Otherwise, wire it up directly: - -### Manual connection - -**MCP** — point your client at `https://mcp.honcho.dev` with two headers: - -- `Authorization: Bearer hch-your-key-here` -- `X-Honcho-User-Name: YourName` (what Honcho should call the user) - -Optional headers: `X-Honcho-Assistant-Name` (default `Assistant`) and `X-Honcho-Workspace-ID` (default `default`; set it to isolate memory per project). Client-specific config snippets (Claude Desktop, Claude Code, Cursor, Codex, Windsurf, VS Code, Cline, Zed) are in the [MCP integration guide](https://honcho.dev/docs/v3/guides/integrations/mcp.md). Restart the client fully after adding config. - -**CLI** — `uv tool install honcho-cli`, then `honcho init` (stores `apiKey` + `environmentUrl` in `~/.honcho/config.json`), then `honcho doctor` to verify connectivity. +You need a Honcho API key — get one free at (starts with `hch-`). Then connect via the path you picked above — a purpose-built integration (recommended), then `honcho-mcp` or `honcho-cli` for the raw connection. --- @@ -141,11 +57,12 @@ Optional headers: `X-Honcho-Assistant-Name` (default `Assistant`) and `X-Honcho- - **Always record turns.** Memory only grows from messages you feed in. Recording is the one non-optional step. - **Don't observe yourself.** The assistant peer should be `observe_me: false` — you want a model of the user, not of the agent. - **One stable peer ID per entity.** Reuse the same `peer_id` for a person across every session and channel; splitting them (`user`, `user-web`, `user-discord`) builds separate representations and fragments memory. -- **Scope sessions so reasoning actually fires.** Reasoning is token-batched per peer (~1,000 tokens within a session). Keep a continuous interaction in one session and let trickle inputs accumulate there; many tiny sessions each stall below the threshold and never get reasoned over. +- **Scope sessions so reasoning actually fires.** Reasoning is token-batched per peer (~1,000 tokens within a session). Scope a session to one active interaction (per-conversation, per-channel, per-task, per-project); create a new one when context genuinely resets (new topic, new day), reuse it while context should keep accumulating. Many tiny sessions each stall below the threshold and never get reasoned over. - **Don't block on reasoning.** It's asynchronous. Respond now; the representation will be richer next time. -- **Recall when it pays off.** Querying takes a few seconds and costs tokens — use it when personalization improves the response, skip it for trivial turns. +- **Reads are cheap; reasoning isn't.** Fetching the representation/context (`get_context`, `get_representation`, `search`) is a near-instant read — use it freely. The dialectic (`chat`) runs live reasoning and takes a few seconds, so save it for when you genuinely need a reasoned answer, not every turn. - **Check before you store.** Background reasoning derives most conclusions automatically. Store a conclusion manually only for a durable fact you want available immediately; `list`/`query` first to avoid duplicates. - **One workspace per app/user-context.** Don't scatter the same user's memory across multiple workspaces. +- **Unify memory across tools with a shared workspace + peer ID.** To give one user continuous memory across several apps or agents (e.g. Claude Code, Cursor, your own app), point them at the same workspace and reuse the same peer ID — that shared ID is what links the representation. See [Unified Memory Setup](https://honcho.dev/docs/v3/guides/recipes/unified-memory-setup.md). ## Resources diff --git a/docs/v3/documentation/introduction/vibecoding.mdx b/docs/v3/documentation/introduction/vibecoding.mdx index 47538cc2..6eb5da31 100644 --- a/docs/v3/documentation/introduction/vibecoding.mdx +++ b/docs/v3/documentation/introduction/vibecoding.mdx @@ -143,9 +143,13 @@ Invoke with `/honcho-integration` in your coding agent. #### honcho-memory -**For using Honcho at runtime.** Once Honcho is connected to your agent (via the [MCP server](#mcp-server) or the [CLI](#cli)), this skill teaches the agent how to actually *use* it as memory: the recall → respond → record loop, which tools map to each step, and when to query versus store. Use this when your agent already has Honcho available and you want it to remember the user across conversations — as opposed to `honcho-integration`, which adds the SDK to a codebase. +**Concepts & strategy for using Honcho at runtime.** The hub skill: it teaches the recall → respond → record loop, session and peer design, and token-batching (so reasoning actually fires) — the durable model behind using Honcho as memory, independent of how you're connected. It routes to the path skill for your connection (`honcho-mcp` or `honcho-cli`). Use this when your agent already has Honcho available and you want it to remember the user across conversations — as opposed to `honcho-integration`, which adds the SDK to a codebase. -Invoke implicitly when you ask a Honcho-connected agent to remember or recall something about the user. +#### honcho-mcp + +**For using Honcho through the MCP server.** The mechanics of the recall/record loop with the [MCP tools](#mcp-server) — `create_session`, `add_messages_to_session`, `chat`, `search`, conclusions, and the rest — plus the session/peer reuse that keeps a user's memory unified. The most direct skill for an MCP-connected agent ("how do I use these Honcho tools?"). + +Invoke implicitly when an MCP-connected agent needs to remember or recall something about the user. #### honcho-cli