---
canonical_url: "https://docs.composio.dev/toolkits/honcho"
markdown_url: "https://docs.composio.dev/toolkits/honcho.md"
product: "platform"
version: null
last_updated: null
---

# Honcho

Honcho provides memory, context, and theory-of-mind infrastructure for building stateful AI agents.

- **Category:** artificial intelligence
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 16
- **Triggers:** 0
- **Slug:** `HONCHO`
- **Version:** 00000000_00

## Tools

### Chat With Peer

**Slug:** `HONCHO_CHAT_WITH_PEER`

Run usage-bearing agentic search and reasoning over a peer's learned representation to answer a question. Higher reasoning levels generally cost more and take longer. Returns one non-streaming JSON response.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Question or reasoning prompt for the peer, from 1 to 10,000 characters. |
| `target` | string | No | Optional target peer to reason about from the selected peer's perspective. |
| `peer_id` | string | Yes | Peer whose learned representation should answer. |
| `session_id` | string | No | Optional session that scopes the representation used to answer. |
| `workspace_id` | string | Yes | Workspace containing the peer. |
| `reasoning_level` | string ("minimal" | "low" | "medium" | "high" | "max") | No | Reasoning effort. Prefer minimal or low unless deeper synthesis is needed; higher levels may increase usage cost and latency. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Conclusions

**Slug:** `HONCHO_CREATE_CONCLUSIONS`

Store a batch of 1-100 explicit conclusions about peers, optionally tied to sessions.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `conclusions` | array | Yes | One to 100 explicit conclusions to store. |
| `workspace_id` | string | Yes | Workspace in which to store the conclusions. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Messages

**Slug:** `HONCHO_CREATE_MESSAGES`

Add a batch of 1-100 attributed messages to a Honcho session. Message-level reasoning settings can trigger usage-bearing processing.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `messages` | array | Yes | One to 100 attributed messages to add to the session. |
| `session_id` | string | Yes | Session receiving the messages. |
| `workspace_id` | string | Yes | Workspace containing the session. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Session

**Slug:** `HONCHO_DELETE_SESSION`

Permanently delete one known session and its session-scoped data. Honcho marks the session inactive immediately and completes deletion asynchronously.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Session to delete permanently. |
| `workspace_id` | string | Yes | Workspace containing the session. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Message

**Slug:** `HONCHO_GET_MESSAGE`

Return one message by its exact ID within a session.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `message_id` | string | Yes | Opaque message ID returned by create or list messages. |
| `session_id` | string | Yes | Session containing the message. |
| `workspace_id` | string | Yes | Workspace containing the session. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get or Create Peer

**Slug:** `HONCHO_GET_OR_CREATE_PEER`

Return a peer by ID within a workspace, creating it with the supplied metadata and configuration when absent. Existing peers are returned unchanged.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `peer_id` | string | Yes | Stable peer ID containing only letters, digits, underscores, or hyphens. |
| `metadata` | object | No | Arbitrary JSON metadata applied only when the peer is created. |
| `workspace_id` | string | Yes | Workspace that owns the peer. |
| `configuration` | object | No | Optional peer configuration applied only when the peer is created. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get or Create Session

**Slug:** `HONCHO_GET_OR_CREATE_SESSION`

Return a session by ID, or create it with initial peers, metadata, and configuration when absent. Creation may create missing peers and start usage-bearing processing when reasoning features are enabled; existing sessions remain unchanged.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `peers` | object | No | Initial membership keyed by peer ID. Missing peers may be created by Honcho. |
| `metadata` | object | No | Arbitrary JSON metadata applied only when the session is created. |
| `session_id` | string | Yes | Stable session ID containing only letters, digits, underscores, or hyphens. |
| `workspace_id` | string | Yes | Workspace that owns the session. |
| `configuration` | object | No | Optional creation-time reasoning, summary, dream, and peer-card settings. Enabling these features can start usage-bearing background processing. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get or Create Workspace

**Slug:** `HONCHO_GET_OR_CREATE_WORKSPACE`

Return a workspace by ID, or create it with metadata and configuration when absent. Enabling reasoning features during creation may start usage-bearing background processing.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `metadata` | object | No | Arbitrary JSON metadata applied only when the workspace is created. |
| `workspace_id` | string | Yes | Stable workspace ID containing only letters, digits, underscores, or hyphens. |
| `configuration` | object | No | Optional creation-time reasoning, summary, dream, and peer-card settings. Enabling these features can start usage-bearing background processing. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Peer Representation

**Slug:** `HONCHO_GET_PEER_REPRESENTATION`

Return a curated subset of conclusions representing a peer. Supplying search_query performs semantic retrieval and may consume paid search capacity; omit it for the existing default representation.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `target` | string | No | Optional target peer represented from the selected peer's perspective. |
| `peer_id` | string | Yes | Peer whose representation to retrieve. |
| `session_id` | string | No | Optional session within which to scope the representation. |
| `search_query` | string | No | Optional semantic query used to curate conclusions. Supplying it may consume paid search capacity. |
| `search_top_k` | integer | No | With search_query, retrieve up to this many semantic matches (1-100). |
| `workspace_id` | string | Yes | Workspace containing the peer. |
| `max_conclusions` | integer | No | Maximum conclusions to include in the representation (1-100). |
| `search_max_distance` | number | No | With search_query, use this maximum cosine distance from 0 to 1. |
| `include_most_frequent` | boolean | No | With search_query, also include frequently recurring conclusions. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Conclusions

**Slug:** `HONCHO_LIST_CONCLUSIONS`

Return one page of stored conclusions in a workspace; use Search Conclusions for semantic retrieval.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `size` | integer | No | Maximum conclusions in this page (1-100). |
| `reverse` | boolean | No | Return results in reverse provider order. |
| `next_cursor` | string | No | Continuation value from a previous call; omit for the first page. |
| `workspace_id` | string | Yes | Workspace whose conclusions to list. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Messages

**Slug:** `HONCHO_LIST_MESSAGES`

Return one page of messages in a session; use Get Message for exact-ID retrieval.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `size` | integer | No | Maximum messages in this page (1-100). |
| `reverse` | boolean | No | Return results in reverse provider order. |
| `session_id` | string | Yes | Session whose messages to list. |
| `next_cursor` | string | No | Continuation value from a previous call; omit for the first page. |
| `workspace_id` | string | Yes | Workspace containing the session. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Peers

**Slug:** `HONCHO_LIST_PEERS`

Return one page of peers in a workspace.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `size` | integer | No | Maximum peers in this page (1-100). |
| `reverse` | boolean | No | Return results in reverse provider order. |
| `next_cursor` | string | No | Continuation value from a previous call; omit for the first page. |
| `workspace_id` | string | Yes | Workspace whose peers to list. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Sessions

**Slug:** `HONCHO_LIST_SESSIONS`

Return one page of sessions in a workspace.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `size` | integer | No | Maximum sessions in this page (1-100). |
| `reverse` | boolean | No | Return results in reverse provider order. |
| `next_cursor` | string | No | Continuation value from a previous call; omit for the first page. |
| `workspace_id` | string | Yes | Workspace whose sessions to list. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Workspaces

**Slug:** `HONCHO_LIST_WORKSPACES`

Return one page of Honcho workspaces visible to the connected admin key.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `size` | integer | No | Maximum workspaces in this page (1-100). |
| `reverse` | boolean | No | Return results in reverse provider order. |
| `next_cursor` | string | No | Opaque continuation value returned by a previous call; omit for the first page. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search Conclusions

**Slug:** `HONCHO_SEARCH_CONCLUSIONS`

Semantically search stored conclusions in a workspace. This operation may consume paid search or embedding capacity; use List Conclusions to browse stored conclusions without semantic retrieval.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Natural-language semantic query. |
| `top_k` | integer | No | Maximum semantic matches to return (1-100). |
| `observed_id` | string | Yes | ID of the peer the matching conclusions must be about. |
| `observer_id` | string | Yes | ID of the peer whose perspective the conclusions were recorded from. |
| `max_distance` | number | No | Optional maximum cosine distance from 0 to 1; lower values require closer matches. |
| `workspace_id` | string | Yes | Workspace whose conclusions to search. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search Messages

**Slug:** `HONCHO_SEARCH_MESSAGES`

Semantically search messages at workspace, peer, or session scope. WARNING: this operation may consume paid search or embedding capacity; use list or get message tools for exact or chronological retrieval.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum matching messages to return (1-100). |
| `query` | string | Yes | Natural-language semantic search query. |
| `scope` | string ("workspace" | "peer" | "session") | Yes | Boundary for the semantic search: workspace, peer, or session. |
| `peer_id` | string | No | Peer to search. Required only when scope is peer; otherwise omit it. |
| `session_id` | string | No | Session to search. Required only when scope is session; otherwise omit it. |
| `workspace_id` | string | Yes | Workspace to search within. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |