138 lines
5.0 KiB
Markdown
138 lines
5.0 KiB
Markdown
# Honcho MCP Server — Instructions
|
||
|
||
## Quick Start: Bespoke Flow
|
||
|
||
The simplest way to use Honcho is the **bespoke flow** — three tools that handle everything for a standard user/assistant conversation.
|
||
|
||
### 1. Start a conversation (once per conversation)
|
||
|
||
```
|
||
start_conversation
|
||
```
|
||
|
||
Returns a `session_id`. Store it for the rest of this conversation.
|
||
|
||
### 2. Get personalization insights (before responding, when helpful)
|
||
|
||
```
|
||
get_personalization_insights
|
||
session_id: "<session_id>"
|
||
query: "What communication style does this user prefer?"
|
||
```
|
||
|
||
This calls Honcho's reasoning system to answer your question about the user, grounded in everything Honcho has learned across all their conversations. It takes a few seconds, so use it when personalization would genuinely improve your response.
|
||
|
||
**Good queries:**
|
||
|
||
- "What does this message reveal about the user's communication preferences?"
|
||
- "How formal or casual should I be?"
|
||
- "What is the user really asking for beyond their explicit question?"
|
||
- "What emotional state might the user be in right now?"
|
||
|
||
### 3. Record the turn (after every exchange)
|
||
|
||
```
|
||
add_turn
|
||
session_id: "<session_id>"
|
||
messages:
|
||
- role: "user"
|
||
content: "<exact user message>"
|
||
- role: "assistant"
|
||
content: "<your exact response>"
|
||
```
|
||
|
||
**Always** call this after responding so Honcho can learn from the conversation.
|
||
|
||
---
|
||
|
||
## General Tools
|
||
|
||
Beyond the bespoke flow, Honcho exposes the full API for advanced use cases.
|
||
|
||
### Workspace Tools
|
||
|
||
| Tool | When to use |
|
||
| --- | --- |
|
||
| `search_workspace` | Find messages across all sessions and peers |
|
||
| `get_workspace_metadata` | Read workspace-level settings |
|
||
| `set_workspace_metadata` | Store workspace-level settings |
|
||
|
||
### Peer Tools
|
||
|
||
| Tool | When to use |
|
||
| --- | --- |
|
||
| `create_peer` | Register a new participant (user or agent) |
|
||
| `list_peers` | See all participants in the workspace |
|
||
| `chat` | Ask Honcho what it knows about any peer. Accepts optional `reasoning_level` (`minimal`–`max`) to control depth vs. speed. |
|
||
| `get_peer_card` | Get compact biographical facts about a peer |
|
||
| `set_peer_card` | Manually set/correct facts about a peer |
|
||
| `get_peer_context` | Get full context (representation + peer card) |
|
||
| `get_representation` | Get the textual representation from conclusions |
|
||
| `get_peer_metadata` / `set_peer_metadata` | Custom attributes on a peer |
|
||
| `search_peer_messages` | Find messages by a specific peer |
|
||
|
||
### Session Tools
|
||
|
||
| Tool | When to use |
|
||
| --- | --- |
|
||
| `create_session` | Create a raw session (use `start_conversation` for the simple flow) |
|
||
| `list_sessions` | Discover existing conversations |
|
||
| `delete_session` | Permanently remove a session |
|
||
| `clone_session` | Fork a conversation (optionally up to a specific message) |
|
||
| `add_peers_to_session` / `remove_peers_from_session` | Manage session participants |
|
||
| `get_session_peers` | See who is in a session |
|
||
| `add_messages_to_session` | Add messages from specific peers |
|
||
| `get_session_messages` | Read conversation history |
|
||
| `search_session_messages` | Semantic search within a session |
|
||
| `get_session_context` | Get LLM-ready context (messages + summary) |
|
||
| `get_session_representation` | Get a peer's session-scoped representation |
|
||
| `get_session_metadata` / `set_session_metadata` | Custom attributes on a session |
|
||
|
||
### Conclusion Tools
|
||
|
||
| Tool | When to use |
|
||
| --- | --- |
|
||
| `list_conclusions` | See what Honcho has derived about a peer |
|
||
| `query_conclusions` | Semantic search across derived facts |
|
||
| `create_conclusions` | Inject facts manually |
|
||
| `delete_conclusion` | Remove incorrect or outdated facts |
|
||
|
||
### System Tools
|
||
|
||
| Tool | When to use |
|
||
| --- | --- |
|
||
| `schedule_dream` | Trigger memory consolidation for better insights |
|
||
| `get_queue_status` | Check if background processing is complete |
|
||
|
||
---
|
||
|
||
## Key Concepts
|
||
|
||
### Peers
|
||
|
||
A **peer** is any participant — human or AI. Each peer has a unique ID within the workspace.
|
||
|
||
### Sessions
|
||
|
||
A **session** is a conversation context. Sessions track message history, manage which peers participate, and provide context retrieval for LLMs.
|
||
|
||
### Conclusions
|
||
|
||
**Conclusions** are facts and observations that Honcho derives from conversations. They power the representation — Honcho's understanding of a peer.
|
||
|
||
### Representations
|
||
|
||
A **representation** is a formatted text summary built from a peer's conclusions. Query it with `get_representation` or `chat`.
|
||
|
||
### Peer Cards
|
||
|
||
A **peer card** is a compact list of biographical facts about a peer, automatically maintained by Honcho (or manually via `set_peer_card`).
|
||
|
||
### Reasoning Level
|
||
|
||
Several tools accept an optional `reasoning_level` parameter (`minimal`, `low`, `medium`, `high`, `max`). Higher levels produce more thorough answers but take longer and cost more. Default is `low`. Use `minimal` for the fastest lookups; use `high` or `max` when depth matters.
|
||
|
||
### Dreams
|
||
|
||
A **dream** is a background memory-consolidation process. It reviews conclusions, merges redundancies, and generates higher-level insights. Schedule one with `schedule_dream` after long conversations.
|