honcho/mcp/instructions.md

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.