RomanNum3ral
/
honcho
mirror of https://github.com/plastic-labs/honcho.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: updating vibecoding and integrations page to better match thier target audience

This commit is contained in:
ajspig 2026-03-17 10:54:45 -04:00
parent 3422a67c3b
commit 0f30c33c05
4 changed files with 320 additions and 110 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/docs.json
View File

@ -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"]

134
docs/v3/documentation/introduction/vibecoding.mdx
View File

@ -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:
<CodeGroup>
```bash Install via npx (Recommended)
@ -45,20 +21,16 @@ curl -o ~/.claude/skills/honcho-integration.md https://raw.githubusercontent.com
```
</CodeGroup>
### 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 <your-api-key>
X-Honcho-User-Name: <user-identifier>
```
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)

216
docs/v3/guides/integrations/mcp.mdx
View File

@ -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
<Note>
If you don't have node installed you will need to do that. Claude Desktop or Claude Code can help!
</Note>
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 <your-honcho-key>` |
| `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
<AccordionGroup>
<Accordion title="Claude Desktop" icon="desktop">
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.
</Accordion>
<Accordion title="Claude Code" icon="terminal">
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 <your-honcho-key>" \
--header "X-Honcho-User-Name:<your-name>"
```
</Accordion>
<Accordion title="Cursor" icon="code">
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 <your-honcho-key>",
"USER_NAME": "<your-name>"
}
}
}
}
```
Restart Cursor. Honcho tools will be available to the AI assistant in Composer and chat.
</Accordion>
<Accordion title="Windsurf" icon="wind">
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 <your-honcho-key>",
"USER_NAME": "<your-name>"
}
}
}
}
```
Restart Windsurf. Honcho tools will appear in Cascade.
</Accordion>
<Accordion title="Cline (VS Code)" icon="plug">
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 <your-honcho-key>",
"USER_NAME": "<your-name>"
}
}
}
}
```
</Accordion>
<Accordion title="Other MCP Clients" icon="puzzle-piece">
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 <your-honcho-key>" \
--header "X-Honcho-User-Name:<your-name>"
```
See [modelcontextprotocol.io/clients](https://modelcontextprotocol.io/clients) for a list of MCP-compatible clients.
</Accordion>
</AccordionGroup>
---
## 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)!
<CardGroup cols={2}>
<Card title="Claude Code Plugin" icon="terminal" href="/v3/guides/integrations/claude-code">
Deeper integration with hooks, git awareness, and auto-context loading
</Card>
<Card title="MCP Server Source" icon="github" href="https://github.com/plastic-labs/honcho/tree/main/mcp">
Source code, full tool reference, and self-hosting instructions
</Card>
<Card title="Honcho Architecture" icon="sitemap" href="../../documentation/core-concepts/architecture">
Learn about peers, sessions, and dialectic reasoning
</Card>
<Card title="Instructions Template" icon="file-lines" href="https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md">
System prompt instructions for teaching your AI to use Honcho
</Card>
</CardGroup>

66
docs/v3/guides/overview.mdx
View File

@ -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'
---
<Note> Before you start a guide, follow [Quickstart](/v3/documentation/introduction/quickstart) to get up and running with Honcho in your language of choice. </Note>
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:
<CardGroup cols={2}>
<Card title="MCP Integration" icon="link" href="/v3/guides/integrations/mcp">
Get Honcho running with a single prompt in Claude Code
<Card title="Claude Code" icon="terminal" href="/v3/guides/integrations/claude-code">
Long-term memory that survives context wipes, session restarts, and project switches
</Card>
<Card title="LangGraph" icon="diagram-project" href="/v3/guides/integrations/langgraph">
Add persistent memory and theory of mind to your LangGraph agents
<Card title="MCP Server" icon="star-of-life" href="/v3/guides/integrations/mcp">
Add Honcho memory to Claude Desktop, Cursor, Windsurf, Cline, and any MCP client
</Card>
<Card title="Hermes Agent" icon="bolt" href="/v3/guides/community/hermes">
Cross-session memory for Nous Research's Hermes agent
</Card>
<Card title="OpenClaw" icon="lobster" href="/v3/guides/integrations/openclaw">
Memory across every channel — WhatsApp, Telegram, Discord, Slack, and more
</Card>
<Card title="Agent Zero" icon="triangle" href="/v3/guides/community/agent0">
Persistent memory plugin for the Agent Zero framework
</Card>
</CardGroup>
## 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:
<CardGroup cols={2}>
<Card title="Discord Bot" icon="discord" href="/v3/guides/discord">
@ -34,7 +38,37 @@ Real-world examples of what you can build with Honcho:
<Card title="Telegram Bot" icon="telegram" href="/v3/guides/telegram">
Create a Telegram bot with persistent user understanding
</Card>
<Card title="Gmail" icon="envelope" href="/v3/guides/gmail">
Import email threads into Honcho — peers, sessions, and messages from your inbox
</Card>
<Card title="Granola" icon="calendar" href="/v3/guides/granola">
Ingest meeting transcripts with speaker turns and participant data
</Card>
<Card title="Reachy Mini" icon="robot" href="/v3/guides/integrations/reachy-mini">
Build an embodied voice robot that remembers users across sessions
Build an embodied voice robot with long-term memory
</Card>
</CardGroup>
## Agent Frameworks
Use Honcho as a memory layer in your agent orchestration stack:
<CardGroup cols={2}>
<Card title="LangGraph" icon="diagram-project" href="/v3/guides/integrations/langgraph">
Add persistent memory and theory of mind to your LangGraph agents
</Card>
<Card title="CrewAI" icon="users-gear" href="/v3/guides/integrations/crewai">
Give CrewAI agents memory that persists across sessions
</Card>
<Card title="n8n" icon="share-nodes" href="/v3/guides/integrations/n8n">
Build intelligent automation workflows with persistent memory
</Card>
</CardGroup>
## Migrations
Coming from another memory provider?
<CardGroup cols={2}>
<Card title="Migrate from Mem0" icon="arrow-right-arrow-left" href="/v3/guides/migrations/mem0">
Transfer your data and update your integration code
</Card>
</CardGroup>