From 0f30c33c0584ddc0ff86787891c37d33e482e678 Mon Sep 17 00:00:00 2001 From: ajspig Date: Tue, 17 Mar 2026 10:54:45 -0400 Subject: [PATCH] docs: updating vibecoding and integrations page to better match thier target audience --- docs/docs.json | 14 +- .../documentation/introduction/vibecoding.mdx | 134 +++++------ docs/v3/guides/integrations/mcp.mdx | 216 +++++++++++++++++- docs/v3/guides/overview.mdx | 66 ++++-- 4 files changed, 320 insertions(+), 110 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 09d4f258..e6fa6e0c 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -99,6 +99,13 @@ "v3/guides/integrations/openclaw" ] }, + { + "group": "Community Integrations", + "pages": [ + "v3/guides/community/agent0", + "v3/guides/community/hermes" + ] + }, { "group": "Tutorials", "pages": [ @@ -109,13 +116,6 @@ "v3/guides/gmail" ] }, - { - "group": "Community Integrations", - "pages": [ - "v3/guides/community/agent0", - "v3/guides/community/hermes" - ] - }, { "group": "Migrations", "pages": ["v3/guides/migrations/mem0"] diff --git a/docs/v3/documentation/introduction/vibecoding.mdx b/docs/v3/documentation/introduction/vibecoding.mdx index 0cda6e69..1081f13d 100644 --- a/docs/v3/documentation/introduction/vibecoding.mdx +++ b/docs/v3/documentation/introduction/vibecoding.mdx @@ -1,39 +1,15 @@ --- -title: "AI-Powered Honcho Setup" +title: "Agentic Development" icon: "wand-magic-sparkles" -description: "Agent skills and starter prompt for building with Honcho" -sidebarTitle: 'Vibecoding Setup' +description: "Let your coding agent help you integrate Honcho" +sidebarTitle: "Agentic Development" --- -These docs are designed to be easily consumable by LLMs. Each page has a button that lets you copy the page as Markdown or paste directly into ChatGPT or Claude. - -We follow the llms.txt standard. There are both an llms.txt and llms-full.txt available: - -- [llms.txt](/llms.txt) -- [llms-full.txt](/llms-full.txt) - ---- - -## Claude Code Plugin - - -Use Honcho to build with Honcho! The [plugin](/v3/guides/integrations/claudecode) provides claude code persistent memory that survives context wipes and session restarts. - -```bash -/plugin marketplace add plastic-labs/claude-honcho -/plugin install honcho@honcho # Tools for Claude to use Honcho to manage it's own context -/plugin install honcho-dev@honcho # Skills to teach claude how to integrate Honcho -``` - -The markeplace also includes all the agent skills below, so you can use `/honcho-dev:integrate` directly after installing. - -See the [full Claude Code integration guide](/v3/guides/integrations/claudecode) for setup details. - ---- +Building a Honcho integration? These tools let your AI assistant do the scaffolding while you focus on the product. ## Agent Skills -We provide agent skills for coding assistants like Claude Code, Cursor, Windsurf, and others. +Install the Honcho skill in Claude Code, Cursor, Windsurf, or any agent: ```bash Install via npx (Recommended) @@ -45,20 +21,16 @@ curl -o ~/.claude/skills/honcho-integration.md https://raw.githubusercontent.com ``` -### Available Skills +### `/honcho-integration` -#### honcho-integration - -**For new integrations.** This skill helps you add Honcho to an existing Python or TypeScript codebase. It provides a guided, interactive experience: +**For new integrations.** Guided integration for adding Honcho to an existing Python or TypeScript codebase. The skill: 1. **Explores your codebase** to understand your language, framework, and existing AI/LLM integrations 2. **Interviews you** about which entities should be peers, your preferred integration pattern, and session structure 3. **Implements the integration** based on your answers—installing the SDK, creating peers, configuring sessions, and wiring up the chat endpoint 4. **Verifies the setup** to ensure everything is configured correctly -Invoke with `/honcho-integration` in your coding agent. - -#### migrate-honcho-py / migrate-honcho-ts +### `/migrate-honcho-py` / `/migrate-honcho-ts` **For SDK upgrades.** Migrates code from v1.6.0 to v2.0.0 (required for Honcho 3.0.0+). Use when upgrading the SDK or seeing errors about removed APIs like `observations`, `Representation`, `.core`, or `get_config`. @@ -72,46 +44,56 @@ Both skills handle: terminology changes (`Observation` → `Conclusion`), `Repre --- -## Universal Starter Prompt +## MCP Server +Give your coding agent (or any MCP client) direct access to Honcho during development. + +### Bespoke Flow (High-Level) +For agents that just need memory without managing sessions: + +| Tool | What it does | +| --- | --- | +| `start_conversation` | Creates a peer + session in one call | +| `add_turn` | Logs a user/assistant exchange | +| `get_personalization_insights` | Retrieves learned context about the peer | + +### General Tools (Full API) +For fine-grained control over the Honcho data model: + +- **Workspace:** `inspect_workspace`, `list_workspaces`, `search_workspace`, `get/set_workspace_metadata` +- **Peers:** `create_peer`, `list_peers`, `chat`, `get_peer_card`, `get_peer_context`, `get_representation`, `search_peer_messages` +- **Sessions:** `create_session`, `list_sessions`, `clone_session`, `add_messages`, `get_session_context`, `inspect_session`, `get_session_summaries` +- **Conclusions:** `list_conclusions`, `query_conclusions`, `create_conclusions`, `delete_conclusion` +- **System:** `schedule_dream`, `get_queue_status` + +### Setup + +Connect via SSE or Streamable HTTP transport: ``` -I want to start building with Honcho - an open source memory library for building stateful agents. - -## Honcho Resources - -**Documentation:** -- Main docs: https://docs.honcho.dev -- API Reference: https://docs.honcho.dev/v3/api-reference/introduction -- Quickstart: https://docs.honcho.dev/v3/documentation/introduction/quickstart -- Architecture: https://docs.honcho.dev/v3/documentation/core-concepts/architecture - -**Code & Examples:** -- Core repo: https://github.com/plastic-labs/honcho -- Python SDK: https://github.com/plastic-labs/honcho-python -- TypeScript SDK: https://github.com/plastic-labs/honcho-node -- Discord bot starter: https://github.com/plastic-labs/discord-python-starter -- Telegram bot example: https://github.com/plastic-labs/telegram-python-starter - -**What Honcho Does:** -Honcho is an open source memory library with a managed service for building stateful agents. It enables agents to build and maintain state about any entity--users, agents, groups, ideas, and more. Because it's a continual learning system, it understands entities that change over time. - -When you write messages to Honcho, they're stored and processed in the background. Custom reasoning models perform formal logical reasoning to generate conclusions about each peer. These conclusions are stored as representations that you can query to provide rich context for your agents. - -**Architecture Overview:** -- Core primitives: Workspaces contain Peers (any entity that persists but changes) and Sessions (interaction threads between peers) -- Peers can observe other peers in sessions (configurable with observe_me and observe_others) -- Background reasoning processes messages to extract premises, draw conclusions, and build representations -- Representations enable continuous improvement as new messages refine existing conclusions and scaffold new ones over time -- Chat endpoint provides personalized responses based on learned context -- Supports any LLM (OpenAI, Anthropic, open source) -- Can use managed service or self-host - -Please assess the resources above and ask me relevant questions to help build a well-structured application using Honcho. Consider asking about: -- What I'm trying to build -- My technical preferences and stack -- Whether I want to use the managed service or self-host -- My experience level with the technologies involved -- Specific features I need (multi-peer sessions, perspective-taking, streaming, etc.) - -Once you understand my needs, help me create a working implementation with proper memory and statefulness. +URL: https://mcp.honcho.dev/mcp +Headers: + Authorization: Bearer + X-Honcho-User-Name: ``` + +Works with Claude Desktop, Cursor, Codeium, and any MCP-compatible client. + + +--- + +## CLI + +Quick commands for local development and testing. + +Coming soon. + +--- + +## LLM-Friendly Docs + +These docs are designed to be easily consumable by LLMs. Each page has a button that lets you copy the page as Markdown or paste directly into ChatGPT or Claude. + +We follow the llms.txt standard: + +- [llms.txt](/llms.txt) +- [llms-full.txt](/llms-full.txt) diff --git a/docs/v3/guides/integrations/mcp.mdx b/docs/v3/guides/integrations/mcp.mdx index 9c828580..2147c88f 100644 --- a/docs/v3/guides/integrations/mcp.mdx +++ b/docs/v3/guides/integrations/mcp.mdx @@ -1,19 +1,64 @@ --- title: "Model Context Protocol (MCP)" icon: 'star-of-life' -description: "Use Honcho in Claude Desktop" +description: "Add Honcho memory to any MCP-compatible client" sidebarTitle: 'MCP' --- -You can let Claude use Honcho to manage its own memory in the native desktop app by using the Honcho MCP integration! Follow these steps: +Honcho ships a hosted MCP server at `mcp.honcho.dev` that works with any client that supports the Model Context Protocol. Connect it once and your AI assistant gets persistent memory — it can store conversations, recall context, and personalize responses across sessions. -1. Go to https://app.honcho.dev and get an API key. Then go to Claude Desktop and navigate to custom MCP servers. +## Prerequisites - -If you don't have node installed you will need to do that. Claude Desktop or Claude Code can help! - +1. **Honcho API key** — Sign up at [app.honcho.dev](https://app.honcho.dev) and copy your key (starts with `hch-`). +2. **Node.js** — Most MCP clients use `npx mcp-remote` to bridge to remote servers. Install from [nodejs.org](https://nodejs.org) if you don't have it. + +## Available Tools + +The MCP server exposes two tiers of tools: + +### Bespoke Flow (Simple) + +For most use cases, these three tools are all you need: + +| Tool | What it does | +|------|-------------| +| `start_conversation` | Start a new conversation, returns a session ID | +| `get_personalization_insights` | Ask Honcho about the user for personalized responses | +| `add_turn` | Record user + assistant messages | + +### General Tools + +For advanced use cases, the full API surface is available: + +- **Workspace** — `inspect_workspace`, `list_workspaces`, `search_workspace`, `get_workspace_metadata`, `set_workspace_metadata` +- **Peers** — `create_peer`, `list_peers`, `chat`, `get_peer_card`, `set_peer_card`, `get_peer_context`, `get_representation`, `get_peer_metadata`, `set_peer_metadata`, `search_peer_messages` +- **Sessions** — `create_session`, `list_sessions`, `delete_session`, `clone_session`, `add_peers_to_session`, `remove_peers_from_session`, `get_session_peers`, `add_messages_to_session`, `get_session_messages`, `search_session_messages`, `get_session_context`, `get_session_representation`, `get_session_metadata`, `set_session_metadata` +- **Conclusions** — `list_conclusions`, `query_conclusions`, `create_conclusions`, `delete_conclusion` +- **System** — `schedule_dream`, `get_queue_status` + +See the [full tool reference](https://github.com/plastic-labs/honcho/tree/main/mcp) for parameter details. + +## Configuration Headers + +All clients pass the same configuration via HTTP headers: + +| Header | Required | Description | +|--------|----------|-------------| +| `Authorization` | Yes | `Bearer ` | +| `X-Honcho-User-Name` | Yes | Your name — what the assistant calls you | +| `X-Honcho-Assistant-Name` | No | Custom assistant name (default: "Assistant") | +| `X-Honcho-Workspace-ID` | No | Custom workspace ID (default: "default") | +| `X-Honcho-Base-URL` | No | Custom API base URL (default: `https://api.honcho.dev`) | + +--- + +## Client Setup + + + + +Navigate to **Settings > Developer > Edit Config** in Claude Desktop and add Honcho: -2. Add Honcho to your Claude desktop config. You must provide a username for Honcho to refer to you as -- preferably what you want Claude to actually call you. ```json { "mcpServers": { @@ -36,7 +81,140 @@ If you don't have node installed you will need to do that. Claude Desktop or Cla } ``` -You may customize your assistant name and/or workspace ID. Both are optional. +Restart Claude Desktop. The Honcho tools should appear in the tools menu. + +**Adding instructions:** Claude Desktop doesn't support system prompts directly, but you can create a project and paste [these instructions](https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md) into the "Project Instructions" field so Claude knows how to use Honcho's memory tools. + + + + + +Claude Code has a dedicated Honcho plugin with deeper integration (hooks, git awareness, auto-context). See the [Claude Code guide](/v3/guides/integrations/claude-code) for the full setup. + +If you just want the raw MCP server without the plugin, add it to your Claude Code MCP config: + +```bash +claude mcp add honcho \ + -- npx mcp-remote https://mcp.honcho.dev \ + --header "Authorization:Bearer " \ + --header "X-Honcho-User-Name:" +``` + + + + + +Open **Settings > MCP** in Cursor and add a new server: + +```json +{ + "mcpServers": { + "honcho": { + "command": "npx", + "args": [ + "mcp-remote", + "https://mcp.honcho.dev", + "--header", + "Authorization:${AUTH_HEADER}", + "--header", + "X-Honcho-User-Name:${USER_NAME}" + ], + "env": { + "AUTH_HEADER": "Bearer ", + "USER_NAME": "" + } + } + } +} +``` + +Restart Cursor. Honcho tools will be available to the AI assistant in Composer and chat. + + + + + +Open **Settings > MCP** in Windsurf and add a new server: + +```json +{ + "mcpServers": { + "honcho": { + "command": "npx", + "args": [ + "mcp-remote", + "https://mcp.honcho.dev", + "--header", + "Authorization:${AUTH_HEADER}", + "--header", + "X-Honcho-User-Name:${USER_NAME}" + ], + "env": { + "AUTH_HEADER": "Bearer ", + "USER_NAME": "" + } + } + } +} +``` + +Restart Windsurf. Honcho tools will appear in Cascade. + + + + + +In VS Code with the Cline extension, go to **Cline Settings > MCP Servers** and add: + +```json +{ + "mcpServers": { + "honcho": { + "command": "npx", + "args": [ + "mcp-remote", + "https://mcp.honcho.dev", + "--header", + "Authorization:${AUTH_HEADER}", + "--header", + "X-Honcho-User-Name:${USER_NAME}" + ], + "env": { + "AUTH_HEADER": "Bearer ", + "USER_NAME": "" + } + } + } +} +``` + + + + + +Any client that supports the MCP standard can connect to Honcho. The pattern is the same — point `mcp-remote` at `https://mcp.honcho.dev` with the required headers. + +For **stdio-based clients** (most desktop apps), use the JSON config format shown above. + +For **SSE-based clients** or direct connections, you can connect to the MCP server URL directly with the headers set in your HTTP client configuration. + +```bash +# Generic command-line usage +npx mcp-remote https://mcp.honcho.dev \ + --header "Authorization:Bearer " \ + --header "X-Honcho-User-Name:" +``` + +See [modelcontextprotocol.io/clients](https://modelcontextprotocol.io/clients) for a list of MCP-compatible clients. + + + + +--- + +## Optional Customization + +You can set additional headers to customize your workspace: ```json { @@ -66,8 +244,24 @@ You may customize your assistant name and/or workspace ID. Both are optional. } ``` -3. Restart the Claude Desktop app. Upon relaunch, it should start Honcho and the tools should be available! +--- -4. Finally, Claude needs instructions on how to use Honcho. The Desktop app doesn't allow you to add system prompts directly, but you can create a project and paste these [instructions](https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md) into the "Project Instructions" field. +## Next Steps -Claude should then query for insights before responding and write your messages to storage! If you come up with more creative ways to get Claude to manage its own memory with Honcho, feel free to [let us know](https://discord.gg/plasticlabs) or make a PR on this [repo](https://github.com/plastic-labs/honcho/tree/main/mcp)! + + + Deeper integration with hooks, git awareness, and auto-context loading + + + + Source code, full tool reference, and self-hosting instructions + + + + Learn about peers, sessions, and dialectic reasoning + + + + System prompt instructions for teaching your AI to use Honcho + + diff --git a/docs/v3/guides/overview.mdx b/docs/v3/guides/overview.mdx index d6f4454a..f5c80a36 100644 --- a/docs/v3/guides/overview.mdx +++ b/docs/v3/guides/overview.mdx @@ -2,30 +2,34 @@ title: "Guides, Cookbooks, and Integrations" sidebarTitle: 'Overview' description: 'Helpful guides and design patterns for building with Honcho' -icon: 'hat-wizard' +icon: 'puzzle-piece' --- - Before you start a guide, follow [Quickstart](/v3/documentation/introduction/quickstart) to get up and running with Honcho in your language of choice. +Honcho plugs into whatever you're already building. Add memory to an AI assistant, connect an external data source, wire Honcho into your agent framework, or migrate from another provider. -These guides provide concrete examples and implementation patterns for building with Honcho. Whether you're integrating Honcho into existing platforms, exploring advanced features, or getting up and running quickly, you'll find working code you can adapt to your needs. - -Each guide focuses on a specific use case with practical examples. The goal is to get you from idea to working prototype as quickly as possible, then provide the depth you need to scale and customize. - - -## Getting Started -Quick integration guides to get up and running: +## AI Assistants +Add persistent memory to AI assistants and agents: - - Get Honcho running with a single prompt in Claude Code + + Long-term memory that survives context wipes, session restarts, and project switches - - Add persistent memory and theory of mind to your LangGraph agents + + Add Honcho memory to Claude Desktop, Cursor, Windsurf, Cline, and any MCP client + + + Cross-session memory for Nous Research's Hermes agent + + + Memory across every channel — WhatsApp, Telegram, Discord, Slack, and more + + + Persistent memory plugin for the Agent Zero framework -## Showcase -Real-world examples of what you can build with Honcho: +## Platform Connectors +Connect external platforms to Honcho — real-time chat bots or batch data ingestion: @@ -34,7 +38,37 @@ Real-world examples of what you can build with Honcho: Create a Telegram bot with persistent user understanding + + Import email threads into Honcho — peers, sessions, and messages from your inbox + + + Ingest meeting transcripts with speaker turns and participant data + - Build an embodied voice robot that remembers users across sessions + Build an embodied voice robot with long-term memory + + + +## Agent Frameworks +Use Honcho as a memory layer in your agent orchestration stack: + + + + Add persistent memory and theory of mind to your LangGraph agents + + + Give CrewAI agents memory that persists across sessions + + + Build intelligent automation workflows with persistent memory + + + +## Migrations +Coming from another memory provider? + + + + Transfer your data and update your integration code