Honcho

Fetch conclusions by ID, from anywhere in the workspace — no observer/observed pair needed. Pass the `source_ids` of a conclusion to see the premises it was derived from; repeat to walk a reasoning chain down to the explicit facts it rests on. Each conclusion carries `level` (explicit = extracted from messages; deductive/inductive/contradiction = derived while dreaming), `source_ids` (the conclusions it was derived from, null for explicit), and `times_derived` (how many times it was independently reached). IDs that no longer exist are omitted rather than erroring, so a shorter result means som…

List the conclusions derived FROM a given conclusion — those naming it in their `source_ids`. This walks the reasoning tree upward (premise -> conclusion); `get_conclusions` on a conclusion's `source_ids` walks it downward. Use this to see what Honcho built on top of a fact before deleting or correcting it. Returns conclusion objects with pagination metadata.

Get messages from a specific date range. Use this to find what was discussed during a particular time period, or to compare information before vs after a date. Essential for knowledge update questions.

Get metadata for a resource. Scope is determined by which optional params are provided: - No scope params: get workspace metadata. - peer_id only: get peer metadata. - session_id only: get session metadata.

Retrieve messages for given message IDs along with surrounding context. Takes message IDs (from an observation's message_ids field) and retrieves those messages plus the messages immediately before and after each one to provide conversation context.

Get the peer card — a compact set of biographical facts about a peer. Use this when you need a quick summary of who someone is. Returns an array of fact strings, or null if no card exists yet.

Get comprehensive context for a peer — combines their representation (conclusions) and peer card. Use this when you need the full picture of what Honcho knows about someone. Returns an object with representation, peer_card, peer_id, and target_id.

Get the current processing queue status for background tasks (message derivation, dreams). Use this to check if Honcho is still processing messages before querying for insights. Returns work unit counts: total, completed, in-progress, and pending.

Get the reasoning chain for an observation - traverse the tree to find premises (for deductive) or sources (for inductive), and/or find conclusions derived from this observation. Use this to understand how an observation was derived or what conclusions depend on it.

Get the most recent observations about the peer. Useful for understanding what's been learned recently.

Get the formatted representation for a peer — a text summary built from their conclusions. Use this when you want the textual representation without the peer card. Returns a formatted string of conclusions.

List the sessions that belong to a scope (paginated). Use this to see which conversations a recall boundary covers. Returns session IDs with pagination metadata.

Get backfill progress for a scope, keyed by session ID. Each entry is pending, completed, or failed. Only sessions with a backfill enqueued appear, so an empty result means nothing is outstanding. Use this after add_sessions_to_scope to tell 'the scope hasn't caught up yet' apart from 'there is nothing to recall'.

Get optimized context for a session, suitable for LLM prompts. Includes recent messages and an optional summary of older ones. Pass peer_target to also include that peer's representation and card, read from peer_perspective's view, from a scope's view (scope), or from the global view (neither). Use this to build a context window for the next LLM call. Returns messages, summary, session ID, and (with peer_target) peer_representation and peer_card.

Get a single message from a session by ID. Use this when you already know the message ID and need the exact record. Returns the message object.

Get messages from a session (paginated), with optional metadata filtering. Use this to read the conversation history. Returns one page of messages with pagination metadata; pass page/size to walk past the first page.

Get all peers participating in a session. Use this to see who is in a conversation. Returns an array of peer IDs.

Search for messages containing specific text (case-insensitive). Unlike semantic search, this finds EXACT text matches. Use for finding specific names, dates, phrases, or keywords mentioned in conversations. Returns messages with surrounding context.

Ask Honcho for a reasoning-backed answer about this project using the current peer and session mapping. In unified observationMode this queries the user's self-collection (shared with other unified agents in the workspace); in directional it queries this AI peer's view of the user.

Create a durable Honcho memory for this Kilo project using the current peer and session mapping.

Get the persisted and effective Kilo Honcho settings, including workspace, peers, and session mapping.

Search the messages saved in this Honcho session only. It does not search other chats or sessions, or what Honcho has concluded about the user; use honcho_chat for that.

Persist a Honcho setting to ~/.honcho/config.json for future Kilo sessions. apiKey and baseUrl cannot be set here.

Set up Honcho for Kilo and save it to ~/.honcho/config.json. Ask the user what name Honcho should call them and pass it as peerName; every Honcho tool on the machine reads that name. When no API key is configured, or replaceKey is true, this tool opens a window on the user's screen where they paste their key from app.honcho.dev, so never ask for the key in chat. Pass workspace only when the user wants Kilo to share memory with another Honcho tool. Pass baseUrl only when the user asks to use a self-hosted Honcho server; the window then names that server and asks for its key. Memory starts with …

Show effective Honcho status for this Kilo project, including workspace, peers, sessions, and memory mode.

Inspect a session at a glance. Aggregates peer IDs, message count, and available summaries. Returns a single JSON object.

Inspect a workspace at a glance. Aggregates workspace metadata, configuration, peer IDs, and session IDs. Returns the first page of peers/sessions with total counts.

List conclusions (facts and observations) that Honcho has derived about a peer (paginated). Use this to see what Honcho has learned. If no target is given, returns self-conclusions. Each conclusion carries `level` (explicit = extracted from messages; deductive/inductive/contradiction = derived while dreaming), `source_ids` (the conclusions it was derived from, null for explicit), and `times_derived` (how many times it was independently reached). Returns conclusion objects with pagination metadata.

List peers in the given workspace (paginated). Use this to discover which users and agents exist. Returns peer IDs with pagination metadata; pass page/size to walk past the first page.

List the scopes in a workspace (paginated). A scope is a named set of sessions that acts as a recall boundary: chat with scope=<name> answers only from that scope's sessions. Returns each scope's id, metadata, and created_at.

List sessions in the given workspace (paginated). Use this to discover existing conversations. Returns session IDs with pagination metadata; pass page/size to walk past the first page.

List workspaces accessible to the current credentials (paginated). Skip this if the connection already set X-Honcho-Workspace-ID — that header is the workspace; omit workspace_id on other tools. Use this only when the header is unset and you don't already know the workspace ID. Returns each workspace's id, metadata, and created_at. If none fit, call create_workspace.

Semantic search across a peer's conclusions. Use this to find specific knowledge Honcho has derived — more targeted than list_conclusions. Each conclusion carries `level` (explicit = extracted from messages; deductive/inductive/contradiction = derived while dreaming), `source_ids` (the conclusions it was derived from, null for explicit), and `times_derived` (how many times it was independently reached). Returns an array of matching conclusions ranked by relevance.

Remove one or more peers from a session. Membership ends at the current time; messages the peer already wrote stay in the session, and its representation is not deleted. Scopes are not removed this way — use remove_session_from_scope.

Remove a session from a scope. Conclusions derived while it was a member are reconciled out asynchronously; the session itself is untouched.

Schedule a dream — a background memory-consolidation task for a peer. Dreams consolidate observations into higher-level insights and update peer cards. Use this after a long conversation to improve Honcho's memory quality.

Semantic search across messages and, when peer_id is given, that peer's saved conclusions. Message scope is determined by which optional params are provided: - No scope params: search all messages in the workspace. - peer_id only: search messages authored by that peer across all sessions. - session_id only: search messages within that session. - scope: search messages in that scope's member sessions (optionally narrowed to peer_id's messages). Not combinable with session_id. Conclusions require peer_id (self-conclusions are searched; conclusion IDs are usable with delete_conclusion). Returns {…

Search for observations in memory using semantic similarity. Use this to find relevant information about the peer when you need to recall specific details.

Search for messages using semantic similarity and retrieve conversation snippets. Returns matching messages with surrounding context (2 messages before and after). Nearby matches within the same session are merged into a single snippet to avoid repetition.

Semantic search for messages with optional date filtering. Combines the power of semantic search with time constraints. Use after_date to find recent mentions of a topic, or before_date to find what was said about something before a certain point. Best for knowledge update questions where you need to find the MOST RECENT discussion of a topic.

Set metadata for a resource. Overwrites existing metadata. Scope is determined by which optional params are provided: - No scope params: set workspace metadata. - peer_id only: set peer metadata. - session_id only: set session metadata.

Set or update the peer card — a list of biographical facts about a peer. Use this to manually establish or correct facts about a peer. Returns the updated peer card.

Edit your working notes for this peer, which carry over to your next dream. Apply a list of operations, each changing one entry: `add` a new entry, `replace` an entry's text, or `remove` an entry. Your entries are capped; a call that would grow them past the cap is rejected, so remove or shorten entries first.

Update the peer card with stable identity markers about the observed peer. An identity marker distinguishes the peer from others of its kind and persists across interactions. The peer may be any entity with identity that changes over time (human, agent, codebase, team, organization) — do not assume the peer is human. Each entry must start with one of four prefixes: `IDENTITY:` (canonical name, kind, aliases, IDs), `ATTRIBUTE:` (stable durable property, including explicitly stated standing preferences), `RELATIONSHIP:` (durable link to another entity), or `INSTRUCTION:` (standing rule of engage…

Ask a natural-language question about the whole workspace and get an answer from Honcho's reasoning system. Reasons across ALL peers and their conclusions — use for cross-peer analysis, common themes, or questions not tied to one peer. For questions about a single peer, use `chat` instead. Returns a natural-language answer, or 'None' if no relevant information exists. With `include_evidence`, returns an object instead: the answer plus what the agent read to produce it.