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.

Every workspace-scoped tool takes `workspace_id`. The simplest setup is for the client to set `X-Honcho-Workspace-ID` on the connection — then omit `workspace_id` on every call. Do not list or create a workspace just to rediscover a header that is already set.

If the header is unset and you don't already know the workspace:

1. Call `list_workspaces` and pick the workspace whose id or metadata best matches this work.
2. If none fit, call `create_workspace` with a descriptive id (and optional metadata like `{ "project": "...", "purpose": "..." }`).
3. Reuse that same `workspace_id` for the rest of the conversation.

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

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

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

Then add peers to the session:

```
create_peer
  workspace_id: "<workspace-id>"
  peer_id: "<user-name>"

create_peer
  workspace_id: "<workspace-id>"
  peer_id: "Assistant"

add_peers_to_session
  workspace_id: "<workspace-id>"
  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
  workspace_id: "<workspace-id>"
  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
  workspace_id: "<workspace-id>"
  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.

---

## Best Practices

- **Group messages into coherent context buckets** — give each distinct context its own `session_id` (a chat thread, a project, a channel) and reuse that same `session_id` for every turn within it, rather than minting a new one per turn. Honcho reasons over the messages in a session together, so keeping a context's messages in one bucket produces a coherent representation; scattering them across sessions fragments it.
- **Use one stable `peer_id` per real person**, reused across every session and channel. A fresh or per-channel ID (`user-web` vs. `user-discord`) builds separate, weaker representations instead of one.
- **`observe_me: false` skips building a model of a peer** — reserve it for deterministic bots (nothing meaningful to model). For a real AI assistant it's fine to leave observation on.
- **Reasoning is asynchronous** — don't poll or wait for it to finish before responding. A brand-new or low-volume peer legitimately has little to show yet.
- **Reach for reads before `chat`** — `get_session_context` / `get_peer_context` / `get_representation` / `search` are near-instant; `chat` runs live reasoning and takes a few seconds. Use `chat` only when you need a reasoned answer.

---

## General Tools

The full API for advanced use cases.

### Workspace Tools

| Tool | When to use |
| --- | --- |
| `list_workspaces` | Discover available workspaces (id, metadata, created_at). No `workspace_id` needed. |
| `create_workspace` | Get or create a workspace when none of the listed ones fit |
| `inspect_workspace` | Inspect a single workspace's details. Requires `workspace_id`. |
| `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.