honcho/mcp/instructions.md

# Honcho MCP Server — Instructions

## Quick Start: Recommended Flow

The simplest way to use Honcho for a standard user/assistant conversation. Three steps using the general tools.

### 1. Start a conversation (once per conversation)

Create a session and set up the user and assistant peers:

```
create_session
  session_id: "<unique-id>"
```

Then add peers to the session:

```
create_peer
  peer_id: "<user-name>"

create_peer
  peer_id: "Assistant"

add_peers_to_session
  session_id: "<session_id>"
  peers:
    - peer_id: "<user-name>"
      observe_me: true
      observe_others: true
    - peer_id: "Assistant"
      observe_me: false
      observe_others: true
```

Store the `session_id` for the rest of this conversation.

### 2. Get personalization insights (before responding, when helpful)

```
chat
  peer_id: "Assistant"
  query: "What communication style does this user prefer?"
  target_peer_id: "<user-name>"
  session_id: "<session_id>"
```

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_messages_to_session
  session_id: "<session_id>"
  messages:
    - peer_id: "<user-name>"
      content: "<exact user message>"
    - peer_id: "Assistant"
      content: "<your exact response>"
```

**Always** call this after responding so Honcho can learn from the conversation.

---

## General Tools

The full API for advanced use cases.

### Workspace Tools

| Tool | When to use |
| --- | --- |
| `inspect_workspace` | Inspect a single workspace's details |
| `list_workspaces` | Enumerate available workspaces |
| `search` | Semantic search across messages — scope with optional `peer_id` or `session_id` params |
| `get_metadata` | Read metadata for workspace, peer, or session (scope with optional `peer_id` or `session_id`) |
| `set_metadata` | Store metadata for workspace, peer, or session (scope with optional `peer_id` or `session_id`) |

### 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 |

### Session Tools

| Tool | When to use |
| --- | --- |
| `create_session` | Create or get a session with the given ID |
| `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` | Add peers to a session with optional per-session config |
| `remove_peers_from_session` | Remove peers from a session |
| `get_session_peers` | See who is in a session |
| `inspect_session` | Inspect detailed session structure/metadata |
| `add_messages_to_session` | Add messages from specific peers |
| `get_session_messages` | Read conversation history (paginated, with optional metadata filters) |
| `get_session_message` | Get a single message from a session by ID |
| `get_session_context` | Get LLM-ready context (messages + summary) |

### 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.