From 8d104078a0b5d4e581815ace6cb0a0f8222d9bae Mon Sep 17 00:00:00 2001 From: ajspig Date: Thu, 16 Jul 2026 17:10:54 -0400 Subject: [PATCH] fix: add instructions.md into the mcp server & delete mcp skill in favor of including it in honcho-memory. --- README.md | 2 +- .../documentation/introduction/vibecoding.mdx | 8 +- docs/v3/guides/integrations/mcp.mdx | 14 +-- mcp/instructions.md | 10 +++ mcp/src/instructions.d.ts | 5 ++ mcp/src/server.ts | 12 ++- mcp/wrangler.toml | 5 ++ skills/honcho-mcp/SKILL.md | 89 ------------------- skills/honcho-memory/SKILL.md | 15 ++-- 9 files changed, 42 insertions(+), 118 deletions(-) create mode 100644 mcp/src/instructions.d.ts delete mode 100644 skills/honcho-mcp/SKILL.md diff --git a/README.md b/README.md index cfadf651..76ef2ed6 100644 --- a/README.md +++ b/README.md @@ -226,7 +226,7 @@ For wiring the Honcho SDK into an existing application, install the integration npx skills add plastic-labs/honcho ``` -Then invoke `/honcho-integration` in Claude Code (or `/honcho-dev:integrate` via the plugin marketplace). The same command also installs the memory skills — `honcho-memory` (concepts: the recall/record loop, session and peer strategy) plus its path skills `honcho-mcp` and `honcho-cli` that teach an already-connected agent how to actually drive the tools. Details: [agentic development guide](https://honcho.dev/docs/v3/documentation/introduction/vibecoding). +Then invoke `/honcho-integration` in Claude Code (or `/honcho-dev:integrate` via the plugin marketplace). The same command also installs the memory skills — `honcho-memory` (concepts: the recall/record loop, session and peer strategy, plus how to connect and drive an MCP-connected Honcho) and `honcho-cli` (inspecting and debugging a deployment). Details: [agentic development guide](https://honcho.dev/docs/v3/documentation/introduction/vibecoding). ### Other MCP clients diff --git a/docs/v3/documentation/introduction/vibecoding.mdx b/docs/v3/documentation/introduction/vibecoding.mdx index 6eb5da31..1fb812c6 100644 --- a/docs/v3/documentation/introduction/vibecoding.mdx +++ b/docs/v3/documentation/introduction/vibecoding.mdx @@ -143,13 +143,7 @@ Invoke with `/honcho-integration` in your coding agent. #### honcho-memory -**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. - -#### 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. +**Concepts & strategy for using Honcho at runtime.** The hub skill: it teaches the recall → respond → record loop and session and peer design — the durable model behind using Honcho as memory, independent of how you're connected — plus how to connect via MCP and drive the [MCP tools](#mcp-server). 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. (An MCP-connected agent also receives usage guidance directly from the server on connect.) #### honcho-cli diff --git a/docs/v3/guides/integrations/mcp.mdx b/docs/v3/guides/integrations/mcp.mdx index 37d2f977..9f56a664 100644 --- a/docs/v3/guides/integrations/mcp.mdx +++ b/docs/v3/guides/integrations/mcp.mdx @@ -269,19 +269,11 @@ Example with all headers (Claude Desktop format): --- -## Available Tools +## Using the Tools -The recommended flow for a standard conversation uses `create_session` + `add_messages_to_session` + `chat`. See the [full instructions](https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md) for a complete walkthrough. +Once connected, the Honcho MCP server tells your assistant how to use the tools automatically — it ships usage instructions (the recall → respond → record loop, the full tool list, and reasoning levels) on connect, so there's nothing extra to configure. -**Workspace** — `inspect_workspace`, `list_workspaces`, `search`, `get_metadata`, `set_metadata` - -**Peers** — `create_peer`, `list_peers`, `chat`, `get_peer_card`, `set_peer_card`, `get_peer_context`, `get_representation` - -**Sessions** — `create_session`, `list_sessions`, `delete_session`, `clone_session`, `add_peers_to_session`, `remove_peers_from_session`, `get_session_peers`, `inspect_session`, `add_messages_to_session`, `get_session_messages`, `get_session_message`, `get_session_context` - -**Conclusions** — `list_conclusions`, `query_conclusions`, `create_conclusions`, `delete_conclusion` - -**System** — `schedule_dream`, `get_queue_status` +If you want to read that guidance yourself, it's the [full instructions](https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md). --- diff --git a/mcp/instructions.md b/mcp/instructions.md index 10cae48d..2abc05ff 100644 --- a/mcp/instructions.md +++ b/mcp/instructions.md @@ -70,6 +70,16 @@ add_messages_to_session --- +## Best Practices + +- **Group messages into coherent context buckets** — give each distinct context its own `session_id` (a chat thread, a project, a channel) and reuse that same `session_id` for every turn within it, rather than minting a new one per turn. Honcho reasons over the messages in a session together, so keeping a context's messages in one bucket produces a coherent representation; scattering them across sessions fragments it. +- **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. +- **`observe_me: false` skips building a model of a peer** — reserve it for deterministic bots (nothing meaningful to model). For a real AI assistant it's fine to leave observation on. +- **Reasoning is asynchronous** — don't poll or wait for it to finish before responding. A brand-new or low-volume peer legitimately has little to show yet. +- **Reach for reads before `chat`** — `get_session_context` / `get_peer_context` / `get_representation` / `search` are near-instant; `chat` runs live reasoning and takes a few seconds. Use `chat` only when you need a reasoned answer. + +--- + ## General Tools The full API for advanced use cases. diff --git a/mcp/src/instructions.d.ts b/mcp/src/instructions.d.ts new file mode 100644 index 00000000..1cde2fab --- /dev/null +++ b/mcp/src/instructions.d.ts @@ -0,0 +1,5 @@ +// Markdown files are bundled as text strings via the wrangler `Text` rule. +declare module "*.md" { + const content: string; + export default content; +} diff --git a/mcp/src/server.ts b/mcp/src/server.ts index 6bbd5e08..363cf9c0 100644 --- a/mcp/src/server.ts +++ b/mcp/src/server.ts @@ -5,12 +5,16 @@ import { register as registerPeerTools } from "./tools/peers.js"; import { register as registerSessionTools } from "./tools/sessions.js"; import { register as registerConclusionTools } from "./tools/conclusions.js"; import { register as registerSystemTools } from "./tools/system.js"; +import instructions from "../instructions.md"; export function createServer(ctx: ToolContext): McpServer { - const server = new McpServer({ - name: "Honcho MCP Server", - version: "3.0.0", - }); + const server = new McpServer( + { + name: "Honcho MCP Server", + version: "3.0.0", + }, + { instructions }, + ); registerWorkspaceTools(server, ctx); registerPeerTools(server, ctx); diff --git a/mcp/wrangler.toml b/mcp/wrangler.toml index c83d240f..987b0b6b 100644 --- a/mcp/wrangler.toml +++ b/mcp/wrangler.toml @@ -3,6 +3,11 @@ main = "src/index.ts" compatibility_date = "2024-12-09" compatibility_flags = ["nodejs_compat"] +# Bundle Markdown (e.g. instructions.md) as text strings so it can be imported. +rules = [ + { type = "Text", globs = ["**/*.md"], fallthrough = true }, +] + [env.production] name = "honcho-mcp" diff --git a/skills/honcho-mcp/SKILL.md b/skills/honcho-mcp/SKILL.md deleted file mode 100644 index c9369a66..00000000 --- a/skills/honcho-mcp/SKILL.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -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. Setting `observe_me: false` on the assistant peer skips building a model of it — reserve that for deterministic bots (nothing meaningful to model) or whenever you simply don't need a representation of the assistant; for an AI assistant it's perfectly fine to leave observation on. 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_session_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/skills/honcho-memory/SKILL.md b/skills/honcho-memory/SKILL.md index 2bc749e3..4c19decc 100644 --- a/skills/honcho-memory/SKILL.md +++ b/skills/honcho-memory/SKILL.md @@ -1,6 +1,6 @@ --- name: honcho-memory -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. +description: Concepts and strategy for using a connected Honcho as persistent memory of the user — the recall/record loop and session and peer design. Start here to understand how Honcho memory works, then connect — via a first-class integration for your environment if one exists (preferred), or raw MCP tools (covered here) or the honcho-cli skill (CLI). For embedding the SDK into a codebase, use honcho-integration. --- # Using Honcho as Memory @@ -14,7 +14,7 @@ This skill is for when Honcho is **already connected** to you and you want to us ## The mental model - **Peer** — any participant, human or AI. You and the user are both peers. Honcho builds a representation of peers it observes (typically the user, not you). -- **Session** — one conversation thread; messages live in sessions. Reasoning runs on **token-batched** input: Honcho only reasons over a peer once that peer accumulates **~1,000 tokens within a single session** (it queues short turns like "yes"/"ok" until the batch is meaningful — nothing is lost, it just waits). Scope sessions so each observed peer clears that bar; don't fragment a continuous conversation across many thin sessions, or each one stalls below the threshold. For low-volume or trickle inputs, append to one ongoing session rather than spinning up a new one each time. See [design patterns](https://honcho.dev/docs/v3/documentation/core-concepts/design-patterns.md) and [token batching](https://honcho.dev/docs/v3/documentation/core-concepts/reasoning.md). +- **Session** — one conversation thread; messages live in sessions. Honcho reasons over the messages in a session together, so scope each session to one coherent context (a conversation, channel, task, or project) and keep that context's turns in the same session rather than fragmenting them across many thin ones. For low-volume or trickle inputs, append to one ongoing session rather than spinning up a new one each time. See [design patterns](https://honcho.dev/docs/v3/documentation/core-concepts/design-patterns.md) and [reasoning](https://honcho.dev/docs/v3/documentation/core-concepts/reasoning.md). - **Message** — the raw turns you feed in. No messages → no reasoning → no memory. - **Conclusion** — a fact Honcho derived (or you stored) about a peer. Conclusions power the representation. - **Representation / peer card** — the synthesized understanding of a peer, queryable via `chat`. A peer's representation **accumulates across every session** it appears in — that's the cross-conversation memory. Session-scoped data (recent messages, summaries) stays local to one session. @@ -39,7 +39,7 @@ Three ways to pull memory, cheapest first: - **Context** (`get_session_context`) — the fuller session view: a session summary + recent messages covering the conversation, and — *only if you target a peer* — that peer's representation folded in. Without a peer target it's session-local (recent turns + summary) and carries no cross-conversation memory. Near-instant read. - **Dialectic** (`chat`) — a *reasoned* natural-language answer to a specific question ("How does this user like to receive feedback?"). Runs live reasoning, so it takes a few seconds. Use it when a plain read won't answer the question. -The dialectic (`chat`) also takes a **reasoning level** that trades speed for depth — from `minimal` (fast factual lookup) through `low` (the default balance) to `max` (deep synthesis for the hardest questions). Pick the lowest level that answers the question; higher levels are slower and cost more. The full level-by-level table and model routing live in the path skills (`honcho-mcp`, `honcho-cli`) and the [chat docs](https://honcho.dev/docs/v3/documentation/features/chat.md). +The dialectic (`chat`) also takes a **reasoning level** that trades speed for depth — from `minimal` (fast factual lookup) through `low` (the default balance) to `max` (deep synthesis for the hardest questions). Pick the lowest level that answers the question; higher levels are slower and cost more. The full level-by-level table and model routing are in the [chat docs](https://honcho.dev/docs/v3/documentation/features/chat.md). --- @@ -48,7 +48,7 @@ The dialectic (`chat`) also takes a **reasoning level** that trades speed for de 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. 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. +2. **No integration, but you have MCP tools** (`create_session`, `add_messages_to_session`, `chat`, …) → drive them with the loop above. The MCP server injects its own usage guide on connect, so there's nothing extra to load; to connect a client yourself, see [Setup](#setup-if-not-connected-yet) below. This is 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. @@ -58,7 +58,10 @@ If you're unsure, list your available tools and look for Honcho memory tools (an ## Setup (if not connected yet) -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. +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), or a raw connection: + +- **MCP** — point your client at `https://mcp.honcho.dev` with two headers: `Authorization: Bearer hch-your-key-here` and `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). Restart the client fully after adding config. Per-client config snippets (Claude Desktop, Cursor, Codex, Windsurf, VS Code, Cline, Zed) are in the [MCP integration guide](https://honcho.dev/docs/v3/guides/integrations/mcp.md). Once connected, the server tells your assistant how to use the tools automatically. +- **CLI** — use the `honcho-cli` skill. --- @@ -67,7 +70,7 @@ You need a Honcho API key — get one free at (starts w - **Always record turns.** Memory only grows from messages you feed in. Recording is the one non-optional step. - **Modeling the assistant is optional.** Setting `observe_me: false` on the assistant peer skips building a model of it — required only for deterministic bots (scripted output, nothing meaningful to model). For an AI assistant it's fine to leave observation on if you also want a model 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). 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. +- **Scope sessions to coherent context buckets.** Honcho reasons over a session's messages together. 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. Keeping a context's turns in one session produces a coherent representation; scattering them fragments it. - **Don't block on reasoning.** It's asynchronous. Respond now; the representation will be richer next time. - **Reads are cheap; reasoning isn't.** Fetching the representation/context (`get_session_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.