# Table of Contents - [SDK and API Compatibility Guide - Honcho](#sdk-and-api-compatibility-guide-honcho) - [Changelog - Honcho](#changelog-honcho) - [Architecture - Honcho](#architecture-honcho) - [Deploying Honcho - Honcho](#deploying-honcho-honcho) - [Spellbooks and Tutorials - Honcho](#spellbooks-and-tutorials-honcho) - [🫡 Welcome to Honcho - Honcho](#-welcome-to-honcho-honcho) - [Guidelines - Honcho](#guidelines-honcho) - [Self-Hosting Honcho - Honcho](#self-hosting-honcho-honcho) - [Honcho MCP - Honcho](#honcho-mcp-honcho) - [Dialectic Endpoint - Honcho](#dialectic-endpoint-honcho) - [Contributing Guidelines - Honcho](#contributing-guidelines-honcho) - [Spellbooks and Tutorials - Honcho](#spellbooks-and-tutorials-honcho) - [Discord Bots with Honcho - Honcho](#discord-bots-with-honcho-honcho) - [License - Honcho](#license-honcho) - [Model Context Protocol (MCP) - Honcho](#model-context-protocol-mcp-honcho) - [Contributing Guidelines - Honcho](#contributing-guidelines-honcho) - [Streaming Responses - Honcho](#streaming-responses-honcho) - [Quickstart - Honcho](#quickstart-honcho) - [Create App - Honcho](#create-app-honcho) - [License - Honcho](#license-honcho) - [Troubleshooting - Honcho](#troubleshooting-honcho) - [Discord Bots with Honcho - Honcho](#discord-bots-with-honcho-honcho) - [Local Environment Setup - Honcho](#local-environment-setup-honcho) - [License - Honcho](#license-honcho) - [CrewAI - Honcho](#crewai-honcho) - [Architecture & Intuition - Honcho](#architecture-intuition-honcho) - [Honcho Reasoning - Honcho](#honcho-reasoning-honcho) - [Migrating from Mem0 - Honcho](#migrating-from-mem0-honcho) - [Telegram Bots with Honcho - Honcho](#telegram-bots-with-honcho-honcho) - [Honcho Overview - Honcho](#honcho-overview-honcho) - [Storing Data - Honcho](#storing-data-honcho) - [Get App By Name - Honcho](#get-app-by-name-honcho) - [Get All Apps - Honcho](#get-all-apps-honcho) - [Get App - Honcho](#get-app-honcho) - [Configuration Guide - Honcho](#configuration-guide-honcho) - [Get Or Create App - Honcho](#get-or-create-app-honcho) - [Summarizer - Honcho](#summarizer-honcho) - [Update App - Honcho](#update-app-honcho) - [Create Collection - Honcho](#create-collection-honcho) - [Terminology - Honcho](#terminology-honcho) - [Storing Data - Honcho](#storing-data-honcho) - [Honcho - Honcho](#honcho-honcho) - [Delete Collection - Honcho](#delete-collection-honcho) - [Local vs Global Representations - Honcho](#local-vs-global-representations-honcho) - [LangGraph - Honcho](#langgraph-honcho) - [Dialectic Endpoint - Honcho](#dialectic-endpoint-honcho) - [Architecture & Intuition - Honcho](#architecture-intuition-honcho) - [Peer Representations - Honcho](#peer-representations-honcho) - [Local Environment Setup - Honcho](#local-environment-setup-honcho) - [Queue Status - Honcho](#queue-status-honcho) - [Agent Zero - Honcho](#agent-zero-honcho) - [Chat Endpoint - Honcho](#chat-endpoint-honcho) - [Pi - Honcho](#pi-honcho) - [Streaming Responses - Honcho](#streaming-responses-honcho) - [Configuration Guide - Honcho](#configuration-guide-honcho) - [Hermes Agent + Honcho - Honcho](#hermes-agent-honcho-honcho) - [Paperclip - Honcho](#paperclip-honcho) - [Agentic Development - Honcho](#agentic-development-honcho) - [Guides, Cookbooks, and Integrations - Honcho](#guides-cookbooks-and-integrations-honcho) - [OpenClaw - Honcho](#openclaw-honcho) - [Quickstart - Honcho](#quickstart-honcho) - [Advanced Features - Honcho](#advanced-features-honcho) - [Search - Honcho](#search-honcho) - [Voice Agent - Reachy Mini - Honcho](#voice-agent-reachy-mini-honcho) - [Get Collection By Name - Honcho](#get-collection-by-name-honcho) - [Summarizer - Honcho](#summarizer-honcho) - [Zo Computer - Honcho](#zo-computer-honcho) - [File Uploads - Honcho](#file-uploads-honcho) - [Working Representations - Honcho](#working-representations-honcho) - [Delete Document - Honcho](#delete-document-honcho) - [Update Collection - Honcho](#update-collection-honcho) - [Get Collection - Honcho](#get-collection-honcho) - [Get Collections - Honcho](#get-collections-honcho) - [Create Document - Honcho](#create-document-honcho) - [The Honcho Dashboard - Honcho](#the-honcho-dashboard-honcho) - [Get Document - Honcho](#get-document-honcho) - [Create Key - Honcho](#create-key-honcho) - [Get Documents - Honcho](#get-documents-honcho) - [Quickstart - Honcho](#quickstart-honcho) - [The Honcho Dashboard - Honcho](#the-honcho-dashboard-honcho) - [Query Documents - Honcho](#query-documents-honcho) - [Update Message - Honcho](#update-message-honcho) - [Update Document - Honcho](#update-document-honcho) - [Delete Session - Honcho](#delete-session-honcho) - [Clone Session - Honcho](#clone-session-honcho) - [Create Session - Honcho](#create-session-honcho) - [Dreaming - Honcho](#dreaming-honcho) - [Get Messages - Honcho](#get-messages-honcho) - [Get Message - Honcho](#get-message-honcho) - [Design Patterns - Honcho](#design-patterns-honcho) - [Chat - Honcho](#chat-honcho) - [Get Metamessages - Honcho](#get-metamessages-honcho) - [Configure Reasoning - Honcho](#configure-reasoning-honcho) - [Discord Bots with Honcho - Honcho](#discord-bots-with-honcho-honcho) - [AI-Powered Honcho Setup - Honcho](#ai-powered-honcho-setup-honcho) - [Create Message For Session - Honcho](#create-message-for-session-honcho) - [Create Batch Messages For Session - Honcho](#create-batch-messages-for-session-honcho) - [Get Metamessage - Honcho](#get-metamessage-honcho) - [Get Session - Honcho](#get-session-honcho) - [Create Metamessage - Honcho](#create-metamessage-honcho) - [Queue Status - Honcho](#queue-status-honcho) - [Update Metamessage - Honcho](#update-metamessage-honcho) - [Model Context Protocol (MCP) - Honcho](#model-context-protocol-mcp-honcho) - [Get Or Create User - Honcho](#get-or-create-user-honcho) - [Create User - Honcho](#create-user-honcho) - [Get User By Name - Honcho](#get-user-by-name-honcho) - [Claude Code - Honcho](#claude-code-honcho) - [Peer Card - Honcho](#peer-card-honcho) - [Get Sessions - Honcho](#get-sessions-honcho) - [CrewAI - Honcho](#crewai-honcho) --- # SDK and API Compatibility Guide - Honcho [Skip to main content](https://docs.honcho.dev/changelog/compatibility-guide#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Overview SDK and API Compatibility Guide [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Current Versions](https://docs.honcho.dev/changelog/compatibility-guide#current-versions) * [Version Compatibility Table](https://docs.honcho.dev/changelog/compatibility-guide#version-compatibility-table) This guide helps you match the right SDK version to your Honcho API version. Newer SDK patch versions are always backward-compatible within the same major version — install the latest patch for your range. [​](https://docs.honcho.dev/changelog/compatibility-guide#current-versions) Current Versions ----------------------------------------------------------------------------------------------- TypeScript SDK -------------- **Latest:** v2.1.1 npm install @honcho-ai/sdk Python SDK ---------- **Latest:** v2.1.1 pip install honcho-ai [​](https://docs.honcho.dev/changelog/compatibility-guide#version-compatibility-table) Version Compatibility Table --------------------------------------------------------------------------------------------------------------------- | Honcho API Version | TypeScript SDK | Python SDK | | --- | --- | --- | | v3.0.6 (Current) | v2.1.1 | v2.1.1 | | v3.0.5 | v2.1.0 | v2.1.0 | | v3.0.4 | v2.1.0 | v2.1.0 | | v3.0.3 | v2.1.0 | v2.1.0 | | v3.0.2 | v2.0.0+ | v2.0.0+ | | v3.0.1 | v2.0.0+ | v2.0.0+ | | v3.0.0 | v2.0.0+ | v2.0.0+ | | v2.5.1 | v1.6.0 | v1.6.0 | | v2.5.0 | v1.6.0 | v1.6.0 | | v2.4.3 | v1.5.0 | v1.5.0 | | v2.4.2 | v1.5.0 | v1.5.0 | | v2.4.1 | v1.5.0 | v1.5.0 | | v2.4.0 | v1.5.0 | v1.5.0 | | v2.3.3 | v1.4.1 | v1.4.1 | | v2.3.2 | v1.4.0 | v1.4.0 | | v2.3.1 | v1.4.0 | v1.4.0 | | v2.3.0 | v1.4.0 | v1.4.0 | | v2.2.0 | v1.3.0 | v1.3.0 | | v2.1.1 | v1.2.1 | v1.2.2 | | v2.1.0 | v1.2.1 | v1.2.2 | | v2.0.5 | v1.1.0 | v1.1.0 | | v2.0.4 | v1.1.0 | v1.1.0 | [Changelog](https://docs.honcho.dev/changelog/introduction) ⌘I --- # Changelog - Honcho [Skip to main content](https://docs.honcho.dev/changelog/introduction#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Overview Changelog [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Honcho API and SDK Changelogs](https://docs.honcho.dev/changelog/introduction#honcho-api-and-sdk-changelogs) * [Getting Help](https://docs.honcho.dev/changelog/introduction#getting-help) Welcome to the Honcho changelog! This section documents all notable changes to the Honcho API and SDKs. How to Read This Changelog Each release is documented with: * **Added**: New features and capabilities * **Changed**: Modifications to existing functionality * **Deprecated**: Features that will be removed in future versions * **Removed**: Features that have been removed * **Fixed**: Bug fixes and corrections * **Security**: Security-related improvements [​](https://docs.honcho.dev/changelog/introduction#version-format) Version Format ------------------------------------------------------------------------------------ Honcho follows [Semantic Versioning](https://semver.org/) : * **MAJOR** version for incompatible API changes * **MINOR** version for backwards-compatible functionality additions * **PATCH** version for backwards-compatible bug fixes ### [​](https://docs.honcho.dev/changelog/introduction#honcho-api-and-sdk-changelogs) Honcho API and SDK Changelogs * Honcho API * Python SDK * TypeScript SDK [​](https://docs.honcho.dev/changelog/introduction#v3-0-6-current) v3.0.6 (Current) ### [​](https://docs.honcho.dev/changelog/introduction#changed) Changed * Tightened transaction scopes across search, agent tools, queue manager, and webhook delivery to minimize DB connection hold time during external operations (#525) * Search operations refactored to two-phase pattern — external work (embeddings, LLM calls) completes before opening a transaction (#525) * Agent tool executor performs external operations before acquiring DB sessions (#525) * Queue manager transaction scope reduced to only the critical section (#525) * Webhook delivery no longer holds a DB session parameter (#525) ### [​](https://docs.honcho.dev/changelog/introduction#fixed) Fixed * Session leakage in non-session-scoped dialectic chat calls (#526) ### [​](https://docs.honcho.dev/changelog/introduction#added) Added * Health check endpoint (`/health`) for container orchestration and load balancer probes (#510) [​](https://docs.honcho.dev/changelog/introduction#v3-0-5) v3.0.5 ### [​](https://docs.honcho.dev/changelog/introduction#fixed-2) Fixed * explicit rollback on all transactions to force connection closed [​](https://docs.honcho.dev/changelog/introduction#v3-0-4) v3.0.4 ### [​](https://docs.honcho.dev/changelog/introduction#added-2) Added * JSONB metadata validation enforces 100 key limit and max depth of 5 (#419) ### [​](https://docs.honcho.dev/changelog/introduction#changed-2) Changed * Schemas refactored from single `schemas.py` into `schemas/api.py`, `schemas/configuration.py`, and `schemas/internal.py` with backwards-compatible re-exports (#419) ### [​](https://docs.honcho.dev/changelog/introduction#fixed-3) Fixed * Missing `deleted_at` filter on `RepresentationManager._query_documents_recent()` and `._query_documents_most_derived()` allowed soft-deleted documents to leak into the deriver’s working representation (#456) * `CleanupStaleItemsCompletedEvent` emitted spuriously when no queue item was actually deleted (#454) * Empty JSON file uploads caused unhandled errors; now returns normalized error responses (#434) * Memory leak: `_observation_locks` switched to `WeakValueDictionary` to prevent unbounded growth (#419) * SQL injection in `dependencies.py`: parameterized `set_config` calls to prevent injection via request context (#419) * NUL byte crashes: string inputs (message content, queries, peer cards) now stripped at schema level (#419) * Filter recursion depth capped at 5 to prevent stack overflow (#419) * Dedup-skipped observations now correctly reflected in created counts (#477) * External vector store support for message search — routes queries through configured external vector store with oversampling and deduplication to handle chunked embeddings (#479) * Dialectic agent no longer holds a DB connection during LLM calls — embeddings are pre-computed before tool execution, DB sessions isolated in `extract_preferences`, `query_documents` no longer accepts a DB session parameter (#477) [​](https://docs.honcho.dev/changelog/introduction#v3-0-3) v3.0.3 ### [​](https://docs.honcho.dev/changelog/introduction#added-3) Added * Consolidated session context into a single DB session with 40/60 token budget allocation between summary and messages * Observation validation via `ObservationInput` Pydantic schema with partial-success support and batch embedding with per-observation fallback * Peer card hard cap of 40 facts with case-insensitive deduplication and whitespace normalization * Safe integer coercion (`_safe_int`) for all LLM tool inputs to handle non-integer values like `"Infinity"` * Embedding pre-computation and reuse across multiple search calls in dialectic and representation flows * Peer existence validation in dialectic chat endpoints — raises ResourceNotFoundException instead of silently failing * Logging filter to suppress noisy `GET /metrics` access logs * Oolong long-context aggregation benchmark (synth and real variants, 1K–4M token context windows) * MolecularBench fact quality evaluation (ambiguity, decontextuality, minimality scoring) * CoverageBench information recall evaluation (gold fact extraction, coverage matching, QA verification) * LoCoMo summary-as-context baseline evaluation * Webhook delivery tests, dependency lifecycle tests, queue cleanup tests, summarizer fallback tests * Parallel test execution via pytest-xdist with worker-specific databases * `test_reasoning_levels.py` script for LOCOM dataset testing across reasoning levels ### [​](https://docs.honcho.dev/changelog/introduction#changed-3) Changed * Workspace deletion is now async — returns 202 Accepted, validates no active sessions (409 Conflict), cascade-deletes in background * Redis caching layer now stores plain-dict instead of ORM objects, with v2-prefixed keys, storage, resilient `safe_cache_set`/`safe_cache_delete` helpers, and deferred post-commit cache invalidation * All `get_or_create_*` CRUD operations now use savepoints (`db.begin_nested()`) instead of commit/rollback for race condition prevention * Reconciler vector sync uses direct ORM mutation instead of batch parameterized UPDATE statements * Summarizer enforces hard word limit in prompt and creates fallback text for empty summaries with `summary_tokens = 0` * Blocked Gemini responses (SAFETY, RECITATION, PROHIBITED\_CONTENT, BLOCKLIST) now raise `LLMError` to trigger retry/backup-provider logic * Gemini client explicitly sets `max_output_tokens` from `max_tokens` parameter * All deriver and metrics collector logging replaced with structured `logging.getLogger(__name__)` calls * Dreamer specialist prompts updated to enforce durable-facts-only peer cards with max 40 entries and deduplication * `GetOrCreateResult` changed from `NamedTuple` to `dataclass` with `async post_commit()` method * FastAPI upgraded from 0.111.0 to 0.131.0; added pyarrow dependency * Queue status filtering to only show user-facing tasks (representation, summary, dream); excludes internal infrastructure tasks ### [​](https://docs.honcho.dev/changelog/introduction#fixed-4) Fixed * JWT timestamp bug — `JWTParams.t` was evaluated once at class definition time instead of per-instance * Session cache invalidation on deletion was missing * `get_peer_card()` now properly propagates `ResourceNotFoundException` instead of swallowing it * `set_peer_card()` ensures peer exists via `get_or_create_peers()` before updating * Backup provider failover with proper tool input type safety * Removed `setup_admin_jwt()` from server startup * Sentry coroutine detection switched from `asyncio.iscoroutinefunction` to `inspect.iscoroutinefunction` ### [​](https://docs.honcho.dev/changelog/introduction#removed) Removed * `explicit.py` and `obex.py` benchmarks replaced by coverage.py and molecular.py * Claude Code review automation workflow (`.github/workflows/claude.yml`) * Coverage reporting from default pytest configuration [​](https://docs.honcho.dev/changelog/introduction#v3-0-2) v3.0.2 ### [​](https://docs.honcho.dev/changelog/introduction#added-4) Added * Documentation for reasoning\_level and Claude Code plugin ### [​](https://docs.honcho.dev/changelog/introduction#changed-4) Changed * Gave dreaming sub-agents better prompting around peer card creation, tweaked overall prompts ### [​](https://docs.honcho.dev/changelog/introduction#fixed-5) Fixed * Added message-search fallback for memory search tool, necessary in fresh sessions * Made FLUSH\_ENABLED a config value * Removed N+1 query in search\_messages [​](https://docs.honcho.dev/changelog/introduction#v3-0-1) v3.0.1 ### [​](https://docs.honcho.dev/changelog/introduction#fixed-6) Fixed * Token counting in Explicit Agent Loop * Backwards compatibility of queue items [​](https://docs.honcho.dev/changelog/introduction#v3-0-0) v3.0.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-5) Added * Agentic Dreamer for intelligent memory consolidation using LLM agents * Agentic Dialectic for query answering using LLM agents with tool use * Reasoning levels configuration for dialectic (`minimal`, `low`, `medium`, `high`, `max`) * Prometheus token tracking for deriver and dialectic operations * n8n integration * Cloud Events for auditable telemetry * External Vector Store support for turbopuffer and lancedb with reconciliation flow ### [​](https://docs.honcho.dev/changelog/introduction#changed-5) Changed * API route renaming for consistency * Dreamer and dialectic now respect peer card configuration settings * Observations renamed to Conclusions across API and SDKs * Deriver to buffer representation tasks to normalize workloads * Local Representation tasks to create singular QueueItems * getContext endpoint to use `search_query` rather than force `last_user_message` ### [​](https://docs.honcho.dev/changelog/introduction#fixed-7) Fixed * Dream scheduling bugs * Summary creation when start\_message\_id > end\_message\_id * Cashews upgrade to prevent NoScriptError * Memory leak in `accumulate_metric` call ### [​](https://docs.honcho.dev/changelog/introduction#removed-2) Removed * Peer card configuration from message configuration; peer cards no longer created/updated in deriver process [​](https://docs.honcho.dev/changelog/introduction#v2-5-1) v2.5.1 ### [​](https://docs.honcho.dev/changelog/introduction#fixed-8) Fixed * Backwards compatibility for `message_ids` field in documents to handle legacy tuple format [​](https://docs.honcho.dev/changelog/introduction#v2-5-0) v2.5.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-6) Added * Message level configurations * CRUD operations for observations * Comprehensive test cases for harness * Peer level get\_context * Set Peer Card Method * Manual dreaming trigger endpoint ### [​](https://docs.honcho.dev/changelog/introduction#changed-6) Changed * Configurations to support more flags for fine-grained control of the deriver, peer cards, summaries, etc. * Working Representations to support more fine-grained parameters ### [​](https://docs.honcho.dev/changelog/introduction#fixed-9) Fixed * File uploads to match `MessageCreate` structure * Cache invalidation strategy [​](https://docs.honcho.dev/changelog/introduction#v2-4-3) v2.4.3 ### [​](https://docs.honcho.dev/changelog/introduction#added-7) Added * Redis caching to improve DB IO * Backup LLM provider to avoid failures when a provider is down ### [​](https://docs.honcho.dev/changelog/introduction#changed-7) Changed * QueueItems to use standardized columns * Improved Deduplication logic for Representation Tasks * More finegrained metrics for representation, summary, and peer card tasks * DB constraint to follow standard naming conventions [​](https://docs.honcho.dev/changelog/introduction#v2-4-2) v2.4.2 ### [​](https://docs.honcho.dev/changelog/introduction#fixed-10) Fixed * Langfuse tracing to have readable waterfalls * Alembic Migrations to match models.py * message\_in\_seq correctly included in webhook payload ### [​](https://docs.honcho.dev/changelog/introduction#changed-8) Changed * Alembic to always use a session pooler * Statement timeout during alembic operations to 5 min [​](https://docs.honcho.dev/changelog/introduction#v2-4-1) v2.4.1 ### [​](https://docs.honcho.dev/changelog/introduction#added-8) Added * Alembic migration validation test suite ### [​](https://docs.honcho.dev/changelog/introduction#fixed-11) Fixed * Alembic migrations to batch changes * Batch message creation sequence number ### [​](https://docs.honcho.dev/changelog/introduction#changed-9) Changed * Logging infrastructure to remove noisy messages * Sentry integration is centralized [​](https://docs.honcho.dev/changelog/introduction#v2-4-0) v2.4.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-9) Added * Unified `Representation` class * vllm client support * Periodic queue cleanup logic * WIP Dreaming Feature * LongMemEval to Test Bench * Prometheus Client for better Metrics * Performance metrics instrumentation * Error reporting to deriver * Workspace Delete Method * Multi-db option in test harness ### [​](https://docs.honcho.dev/changelog/introduction#changed-10) Changed * Working Representations are Queried on the fly rather than cached in metadata * EmbeddingStore to RepresentationFactory * Summary Response Model to use public\_id of message for cutoff * Semantic across codebase to reference resources based on `observer` and `observed` * Prompts for Deriver & Dialectic to reference peer\_id and add examples * `Get Context` route returns peer card and representation in addition to messages and summaries * Refactoring logger.info calls to logger.debug where applicable ### [​](https://docs.honcho.dev/changelog/introduction#fixed-12) Fixed * Gemini client to use async methods [​](https://docs.honcho.dev/changelog/introduction#v2-3-3) v2.3.3 ### [​](https://docs.honcho.dev/changelog/introduction#changed-11) Changed * Deriver Rollup Queue processes interleaved messages for more context ### [​](https://docs.honcho.dev/changelog/introduction#fixed-13) Fixed * Dialectic Streaming to follow SSE conventions * Sentry tracing in the deriver [​](https://docs.honcho.dev/changelog/introduction#v2-3-2) v2.3.2 ### [​](https://docs.honcho.dev/changelog/introduction#added-10) Added * Get peer cards endpoint (`GET /v2/peers/{peer_id}/card`) for retrieving targeted peer context information ### [​](https://docs.honcho.dev/changelog/introduction#changed-12) Changed * Replaced Mirascope dependency with small client implementation for better control * Optimized deriver performance by using joins on messages table instead of storing token count in queue payload * Database scope optimization for various operations * Batch representation task processing for ~10x speed improvement in practice ### [​](https://docs.honcho.dev/changelog/introduction#fixed-14) Fixed * Separated clean and claim work units in queue manager to prevent race conditions * Skip locked ActiveQueueSession rows on delete operations * Langfuse SDK integration updates for compatibility * Added configurable maximum message size to prevent token overflow in deriver * Various minor bugfixes [​](https://docs.honcho.dev/changelog/introduction#v2-3-1) v2.3.1 ### [​](https://docs.honcho.dev/changelog/introduction#fixed-15) Fixed * Added max message count to deriver in order to not overflow token limits [​](https://docs.honcho.dev/changelog/introduction#v2-3-0) v2.3.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-11) Added * `getSummaries` endpoint to get all available summaries for a session directly * Peer Card feature to improve context for deriver and dialectic ### [​](https://docs.honcho.dev/changelog/introduction#changed-13) Changed * Session Peer limit to be based on observers instead, renamed config value to `SESSION_OBSERVERS_LIMIT` * `Messages` can take a custom timestamp for the `created_at` field, defaulting to the current time * `get_context` endpoint returns detailed `Summary` object rather than just summary content * Working representations use a FIFO queue structure to maintain facts rather than a full rewrite * Optimized deriver enqueue by prefetching message sequence numbers (eliminates N+1 queries) ### [​](https://docs.honcho.dev/changelog/introduction#fixed-16) Fixed * Deriver uses `get_context` internally to prevent context window limit errors * Embedding store will truncate context when querying documents to prevent embedding token limit errors * Queue manager to schedule work based on available works rather than total number of workers * Queue manager to use atomic db transactions rather than long lived transaction for the worker lifecycle * Timestamp formats unified to ISO 8601 across the codebase * Internal get\_context method’s cutoff value is exclusive now [​](https://docs.honcho.dev/changelog/introduction#v2-2-0) v2.2.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-12) Added * Arbitrary filters now available on all search endpoints * Search combines full-text and semantic using reciprocal rank fusion * Webhook support (currently only supports queue\_empty and test events, more to come) * Small test harness and custom test format for evaluating Honcho output quality * Added MCP server and documentation for it ### [​](https://docs.honcho.dev/changelog/introduction#changed-14) Changed * Search has 10 results by default, max 100 results * Queue structure generalized to handle more event types * Summarizer now exhaustive by default and tuned for performance ### [​](https://docs.honcho.dev/changelog/introduction#fixed-17) Fixed * Resolve race condition for peers that leave a session while sending messages * Added explicit rollback to solve integrity error in queue * Re-introduced Sentry tracing to deriver * Better integrity logic in get\_or\_create API methods [​](https://docs.honcho.dev/changelog/introduction#v2-1-2) v2.1.2 ### [​](https://docs.honcho.dev/changelog/introduction#fixed-18) Fixed * Summarizer module to ignore empty summaries and pass appropriate one to get\_context * Structured Outputs calls with OpenAI provider to pass strict=True to Pydantic Schema [​](https://docs.honcho.dev/changelog/introduction#v2-1-1) v2.1.1 ### [​](https://docs.honcho.dev/changelog/introduction#added-13) Added * Test harness for custom Honcho evaluations * Better support for session and peer aware dialectic queries * Langfuse settings * Added recent history to dialectic prompt, dynamic based on new context window size setting ### [​](https://docs.honcho.dev/changelog/introduction#fixed-19) Fixed * Summary queue logic * Formatting of logs * Filtering by session * Peer targeting in queries ### [​](https://docs.honcho.dev/changelog/introduction#changed-15) Changed * Made query expansion in dialectic off by default * Overhauled logging * Refactor summarization for performance and code clarity * Refactor queue payloads for clarity [​](https://docs.honcho.dev/changelog/introduction#v2-1-0) v2.1.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-14) Added * File uploads * Brand new “ROTE” deriver system * Updated dialectic system * Local working representations * Better logging for deriver/dialectic * Deriver Queue Status no longer has redundant data ### [​](https://docs.honcho.dev/changelog/introduction#fixed-20) Fixed * Document insertion * Session-scoped and peer-targeted dialectic queries work now * Minor bugs ### [​](https://docs.honcho.dev/changelog/introduction#removed-3) Removed * Peer-level messages ### [​](https://docs.honcho.dev/changelog/introduction#changed-16) Changed * Dialectic chat endpoint takes a single query * Rearranged configuration values (LLM, Deriver, Dialectic, History->Summary) [​](https://docs.honcho.dev/changelog/introduction#v2-0-5) v2.0.5 ### [​](https://docs.honcho.dev/changelog/introduction#fixed-21) Fixed * Groq API client to use the Async library [​](https://docs.honcho.dev/changelog/introduction#v2-0-4) v2.0.4 ### [​](https://docs.honcho.dev/changelog/introduction#fixed-22) Fixed * Migration/provision scripts did not have correct database connection arguments, causing timeouts [​](https://docs.honcho.dev/changelog/introduction#v2-0-3) v2.0.3 ### [​](https://docs.honcho.dev/changelog/introduction#fixed-23) Fixed * Bug that causes runtime error when Sentry flags are enabled [​](https://docs.honcho.dev/changelog/introduction#v2-0-2) v2.0.2 ### [​](https://docs.honcho.dev/changelog/introduction#fixed-24) Fixed * Database initialization was misconfigured and led to provision\_db script failing: switch to consistent working configuration with transaction pooler [​](https://docs.honcho.dev/changelog/introduction#v2-0-1) v2.0.1 ### [​](https://docs.honcho.dev/changelog/introduction#added-15) Added * Ergonomic SDKs for Python and TypeScript (uses Stainless underneath) * Deriver Queue Status endpoint * Complex arbitrary filters on workspace/session/peer/message * Message embedding table for full semantic search ### [​](https://docs.honcho.dev/changelog/introduction#changed-17) Changed * Overhauled documentation * BasedPyright typing for entire project * Resource filtering expanded to include logical operators ### [​](https://docs.honcho.dev/changelog/introduction#fixed-25) Fixed * Various bugs * Use new config arrangement everywhere * Remove hardcoded responses [​](https://docs.honcho.dev/changelog/introduction#v2-0-0) v2.0.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-16) Added * Ability to get a peer’s working representation * Metadata to all data primitives (Workspaces, Peers, Sessions, Messages) * Internal metadata to store Honcho’s state no longer exposed in API * Batch message operations and enhanced message querying with token and message count limits * Search and summary functionalities scoped by workspace, peer, and session * Session context retrieval with summaries and token allocatio * HNSW Index for Documents Table * Centralized Configuration via Environment Variables or config.toml file ### [​](https://docs.honcho.dev/changelog/introduction#changed-18) Changed * New architecture centered around the concept of a “peer” replaces the former “app”/“user”/“session” paradigm * Workspaces replace “apps” as top-level namespace * Peers replace “users” * Sessions no longer nested beneath peers and no longer limited to a single user-assistant model. A session exists independently of any one peer and peers can be added to and removed from sessions. * Dialectic API is now part of the Peer, not the Session * Dialectic API now allows queries to be scoped to a session or “targeted” to a fellow peer * Database schema migrated to adopt workspace/peer/session naming and structure * Authentication and JWT scopes updated to workspace/peer/session hierarchy * Queue processing now works on ‘work units’ instead of sessions * Message token counting updated with tiktoken integration and fallback heuristic * Queue and message processing updated to handle sender/target and task types for multi-peer scenarios ### [​](https://docs.honcho.dev/changelog/introduction#fixed-26) Fixed * Improved error handling and validation for batch message operations and metadata * Database Sessions to be more atomic to reduce idle in transaction time ### [​](https://docs.honcho.dev/changelog/introduction#removed-4) Removed * Metamessages removed in favor of metadata * Collections and Documents no longer exposed in the API, solely internal * Obsolete tests for apps, users, collections, documents, and metamessages * * * [​](https://docs.honcho.dev/changelog/introduction#v1-1-0) v1.1.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-17) Added * Normalize resources to remove joins and increase query performance * Query tracing for debugging ### [​](https://docs.honcho.dev/changelog/introduction#changed-19) Changed * `/list` endpoints to not require a request body * `metamessage_type` to `label` with backwards compatibility * Database Provisioning to rely on alembic * Database Session Manager to explicitly rollback transactions before closing the connection ### [​](https://docs.honcho.dev/changelog/introduction#fixed-27) Fixed * Alembic Migrations to include initial database migrations * Sentry Middleware to not report Honcho Exceptions [​](https://docs.honcho.dev/changelog/introduction#v1-0-0) v1.0.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-18) Added * JWT based API authentication * Configurable logging * Consolidated LLM Inference via `ModelClient` class * Dynamic logging configurable via environment variables ### [​](https://docs.honcho.dev/changelog/introduction#changed-20) Changed * Deriver & Dialectic API to use Hybrid Memory Architecture * Metamessages are not strictly tied to a message * Database provisioning is a separate script instead of happening on startup * Consolidated `session/chat` and `session/chat/stream` endpoints [​](https://docs.honcho.dev/changelog/introduction#previous-releases) Previous Releases ------------------------------------------------------------------------------------------ For a complete history of all releases, see our [GitHub Releases](https://github.com/plastic-labs/honcho/tags) page. [Python SDK](https://pypi.org/project/honcho-ai/) [​](https://docs.honcho.dev/changelog/introduction#v2-1-1-current) v2.1.1 (Current) ### [​](https://docs.honcho.dev/changelog/introduction#fixed-28) Fixed * Broadened HTTP retry logic to cover `httpx.NetworkError` and `httpx.RemoteProtocolError` in addition to `httpx.TimeoutException` and `httpx.ConnectError`, improving resilience against transient network failures [​](https://docs.honcho.dev/changelog/introduction#v2-1-0-2) v2.1.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-19) Added * `created_at` property on `Peer` and `Session` objects * `is_active` property on `Session` objects * `get_message(message_id)` method on `Session` (sync and async) to fetch a single message by ID * `page`, `size`, and `reverse` pagination parameters on all list methods ### [​](https://docs.honcho.dev/changelog/introduction#changed-21) Changed * **Breaking**: `peer()` and `session()` now always make a get-or-create API call — no more lazy initialization * Response configuration models now tolerate unknown fields from newer servers for forward compatibility ### [​](https://docs.honcho.dev/changelog/introduction#fixed-29) Fixed * Sync and async `Session.get_metadata()`, `get_configuration()`, and `refresh()` now refresh cached `created_at` and `is_active` values along with metadata and configuration * `honcho.__version__` now derives from package metadata, with a source-checkout fallback, so it stays aligned with released package versions [​](https://docs.honcho.dev/changelog/introduction#v2-0-2-2) v2.0.2 ### [​](https://docs.honcho.dev/changelog/introduction#changed-22) Changed * All input models now reject unknown fields via strict Pydantic validation (`extra="forbid"`). Previously, misspelled or extraneous fields were silently ignored. Now a `ValidationError` is raised with the unrecognized field name. [​](https://docs.honcho.dev/changelog/introduction#v2-0-1-2) v2.0.1 ### [​](https://docs.honcho.dev/changelog/introduction#added-20) Added * `set_peer_card` method ### [​](https://docs.honcho.dev/changelog/introduction#changed-23) Changed * `card` is now `get_card` with `card` kept for backwards compatibility and marked as deprecated [​](https://docs.honcho.dev/changelog/introduction#v2-0-0-2) v2.0.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-21) Added * `ConclusionScope` object for CRUD operations on conclusions (renamed from observations) * Representation configuration support ### [​](https://docs.honcho.dev/changelog/introduction#changed-24) Changed * Observations renamed to Conclusions across the SDK * Major SDK refactoring and cleanup * Simplified method signatures throughout * Representation endpoints now return `string` instead of old Representation object ### [​](https://docs.honcho.dev/changelog/introduction#removed-5) Removed * Standalone types module (now uses honcho-core types) * Representation object [​](https://docs.honcho.dev/changelog/introduction#v1-6-0) v1.6.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-22) Added * metadata and configuration fields to Workspace, Peer, Session, and Message objects * Session Clone methods * Peer level get\_context method * `ObservationScope` object to perform CRUD operations on observations * Representation object for WorkingRepresentations ### [​](https://docs.honcho.dev/changelog/introduction#changed-25) Changed * methods that take IDs, can all optionally take an object of the same type [​](https://docs.honcho.dev/changelog/introduction#v1-5-0) v1.5.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-23) Added * Delete workspace method ### [​](https://docs.honcho.dev/changelog/introduction#changed-26) Changed * message\_id of `Summary` model is a string nanoid * Get Context can return Peer Card & Peer Representation [​](https://docs.honcho.dev/changelog/introduction#v1-4-1) v1.4.1 ### [​](https://docs.honcho.dev/changelog/introduction#added-24) Added * Get Peer Card method * Update Message metadata method * Session level deriver status methods * Delete session message ### [​](https://docs.honcho.dev/changelog/introduction#fixed-30) Fixed * Dialectic Stream returns Iterators * Type warnings ### [​](https://docs.honcho.dev/changelog/introduction#changed-27) Changed * Pagination class to match core implementation [​](https://docs.honcho.dev/changelog/introduction#v1-4-0) v1.4.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-25) Added * getSummaries API returning structured summaries * Webhook support ### [​](https://docs.honcho.dev/changelog/introduction#changed-28) Changed * Messages can take an optional `created_at` value, defaulting to the current time (UTC ISO 8601) [​](https://docs.honcho.dev/changelog/introduction#v1-2-2) v1.2.2 ### [​](https://docs.honcho.dev/changelog/introduction#added-26) Added * Filter parameter to various endpoints [​](https://docs.honcho.dev/changelog/introduction#v1-2-1) v1.2.1 ### [​](https://docs.honcho.dev/changelog/introduction#fixed-31) Fixed * Honcho util import paths [​](https://docs.honcho.dev/changelog/introduction#v1-2-0) v1.2.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-27) Added * Get/poll deriver queue status endpoints added to workspace * Added endpoint to upload files as messages ### [​](https://docs.honcho.dev/changelog/introduction#removed-6) Removed * Removed peer messages in accordance with Honcho 2.1.0 ### [​](https://docs.honcho.dev/changelog/introduction#changed-29) Changed * Updated chat endpoint to use singular `query` in accordance with Honcho 2.1.0 [​](https://docs.honcho.dev/changelog/introduction#v1-1-0-2) v1.1.0 ### [​](https://docs.honcho.dev/changelog/introduction#fixed-32) Fixed * Properly handle AsyncClient [TypeScript SDK](https://www.npmjs.com/package/@honcho-ai/sdk) [​](https://docs.honcho.dev/changelog/introduction#v2-1-1-current-2) v2.1.1 (Current) ### [​](https://docs.honcho.dev/changelog/introduction#fixed-33) Fixed * Broadened fetch error retry logic to catch all `TypeError` network failures (connection resets, DNS errors, etc.) instead of only those with `'fetch'` in the message, improving resilience across runtimes (Node, Bun, browsers) [​](https://docs.honcho.dev/changelog/introduction#v2-1-0-3) v2.1.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-28) Added * `createdAt` property on `Peer` and `Session` wrapper objects * `isActive` property on `Session` wrapper objects * `getMessage(messageId)` method on `Session` to fetch a single message by ID * `Peer.representation()`, `Session.representation()`, and `Session.context()` now accept `Message` objects for `searchQuery` * `page`, `size`, and `reverse` pagination controls on all list methods ### [​](https://docs.honcho.dev/changelog/introduction#changed-30) Changed * **Breaking**: `searchQuery` removed from top-level `context()` options — use `representationOptions.searchQuery` instead: // Before (v2.0.x) await session.context({ searchQuery: "..." }); // After (v2.1.0) await session.context({ representationOptions: { searchQuery: "..." } }); * List methods (`peers()`, `sessions()`, `messages()`, `workspaces()`) support both the new options object and the legacy raw-filter form * Representation search options now accept strings and content-like objects, including `Message` instances, while rejecting whitespace-only or invalid runtime inputs * **Breaking**: `peer()` and `session()` now always make a get-or-create API call — no more lazy initialization. If you relied on constructing SDK objects without triggering a network request, note that every `peer()` and `session()` call now hits the API: // Before (v2.0.x) — no API call const session = honcho.session("my-session"); // After (v2.1.0) — makes a get-or-create API call const session = await honcho.session("my-session"); * Response configuration models now tolerate unknown fields from newer servers for forward compatibility * Moved `@types/node` from `dependencies` to `devDependencies` ### [​](https://docs.honcho.dev/changelog/introduction#fixed-34) Fixed * `uploadFile()` now rejects unsupported top-level binary/object inputs and only validates inputs the serializer can actually upload * `uploadFile()` now serializes message configuration using API field names, matching `addMessages()` * Session fetch methods now refresh cached `createdAt` and `isActive` values alongside metadata and configuration [​](https://docs.honcho.dev/changelog/introduction#v2-0-2-3) v2.0.2 ### [​](https://docs.honcho.dev/changelog/introduction#changed-31) Changed * Client constructor now rejects unknown options via `.strict()` Zod validation. Previously, misspelled options (e.g., `baseUrl` instead of `baseURL`) were silently ignored, causing the SDK to fall back to defaults. Now a `ZodError` is thrown with the unrecognized key name. * All input schemas now use `.strict()` validation to reject unknown fields. * `FileUploadSchema.configuration` now uses `MessageConfigurationSchema` instead of open record type. ### [​](https://docs.honcho.dev/changelog/introduction#fixed-35) Fixed * README example used `baseUrl` instead of `baseURL`. [​](https://docs.honcho.dev/changelog/introduction#v2-0-1-3) v2.0.1 ### [​](https://docs.honcho.dev/changelog/introduction#added-29) Added * `setPeerCard` method ### [​](https://docs.honcho.dev/changelog/introduction#changed-32) Changed * `card` is now `getCard` with `card` kept for backwards compatibility and marked as deprecated [​](https://docs.honcho.dev/changelog/introduction#v2-0-0-3) v2.0.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-30) Added * `ConclusionScope` object for CRUD operations on conclusions (renamed from observations) * Representation configuration support ### [​](https://docs.honcho.dev/changelog/introduction#changed-33) Changed * Observations renamed to Conclusions across the SDK * Major SDK refactoring and cleanup * Simplified method signatures throughout * Representation endpoints now return `string` instead of old Representation object ### [​](https://docs.honcho.dev/changelog/introduction#fixed-36) Fixed * Pagination `this` binding issue ### [​](https://docs.honcho.dev/changelog/introduction#removed-7) Removed * Representation object * Stainless “core” SDK — this SDK is now standalone [​](https://docs.honcho.dev/changelog/introduction#v1-6-0-2) v1.6.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-31) Added * metadata and configuration fields to Workspace, Peer, Session, and Message objects * Session Clone methods * Peer level get\_context method * `ObservationScope` object to perform CRUD operations on observations * Representation object for WorkingRepresentations ### [​](https://docs.honcho.dev/changelog/introduction#changed-34) Changed * methods that take IDs, can all optionally take an object of the same type [​](https://docs.honcho.dev/changelog/introduction#v1-5-0-2) v1.5.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-32) Added * Delete workspace method ### [​](https://docs.honcho.dev/changelog/introduction#changed-35) Changed * message\_id of `Summary` model is a string nanoid * Get Context can return Peer Card & Peer Representation [​](https://docs.honcho.dev/changelog/introduction#v1-4-1-2) v1.4.1 ### [​](https://docs.honcho.dev/changelog/introduction#added-33) Added * Get Peer Card method * Update Message metadata method * Session level deriver status methods * Delete session message ### [​](https://docs.honcho.dev/changelog/introduction#fixed-37) Fixed * Dialectic Stream returns Iterators * Type warnings ### [​](https://docs.honcho.dev/changelog/introduction#changed-36) Changed * Pagination class to match core implementation [​](https://docs.honcho.dev/changelog/introduction#v1-4-0-2) v1.4.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-34) Added * getSummaries API returning structured summaries * Webhook support ### [​](https://docs.honcho.dev/changelog/introduction#changed-37) Changed * Messages can take an optional `created_at` value, defaulting to the current time (UTC ISO 8601) [​](https://docs.honcho.dev/changelog/introduction#v1-2-1-2) v1.2.1 ### [​](https://docs.honcho.dev/changelog/introduction#added-35) Added * linting via Biome * Adding filter parameter to various endpoints ### [​](https://docs.honcho.dev/changelog/introduction#fixed-38) Fixed * Order of parameters in `getSessions` endpoint [​](https://docs.honcho.dev/changelog/introduction#v1-2-0-2) v1.2.0 ### [​](https://docs.honcho.dev/changelog/introduction#added-36) Added * Get/poll deriver queue status endpoints added to workspace * Added endpoint to upload files as messages ### [​](https://docs.honcho.dev/changelog/introduction#removed-8) Removed * Removed peer messages in accordance with Honcho 2.1.0 ### [​](https://docs.honcho.dev/changelog/introduction#changed-38) Changed * Updated chat endpoint to use singular `query` in accordance with Honcho 2.1.0 [​](https://docs.honcho.dev/changelog/introduction#v1-1-0-3) v1.1.0 ### [​](https://docs.honcho.dev/changelog/introduction#fixed-39) Fixed * Create default workspace on Honcho client instantiation * Simplified Honcho client import path [​](https://docs.honcho.dev/changelog/introduction#getting-help) Getting Help -------------------------------------------------------------------------------- If you encounter issues using the Honcho API or its SDKs: 1. Open an issue on [GitHub](https://github.com/plastic-labs/honcho/issues) 2. Join our [Discord community](http://discord.gg/honcho) for support [SDK and API Compatibility Guide](https://docs.honcho.dev/changelog/compatibility-guide) ⌘I --- # Architecture - Honcho [Skip to main content](https://docs.honcho.dev/v1/getting-started/architecture#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation Get Started Architecture [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) On this page * [Core Primitives](https://docs.honcho.dev/v1/getting-started/architecture#core-primitives) * [Apps](https://docs.honcho.dev/v1/getting-started/architecture#apps) * [Users](https://docs.honcho.dev/v1/getting-started/architecture#users) * [Sessions](https://docs.honcho.dev/v1/getting-started/architecture#sessions) * [Messages](https://docs.honcho.dev/v1/getting-started/architecture#messages) * [Metamessages](https://docs.honcho.dev/v1/getting-started/architecture#metamessages) * [Collections](https://docs.honcho.dev/v1/getting-started/architecture#collections) * [Documents](https://docs.honcho.dev/v1/getting-started/architecture#documents) * [Conclusion](https://docs.honcho.dev/v1/getting-started/architecture#conclusion) Honcho is a user context management system for AI-powered applications. The storage concepts are inspired by, but not a 1:1 mapping of, the OpenAI Assistants API. The insights concepts are inspired by cognitive science, philosophy, and machine learning. Honcho is open source. We believe trust and transparency are vital for developing AI technology. We’re also focused on using and supporting existing tools rather than developing from scratch. We focus on flexible, user-centric storage primitives to promote community exploration of novel memory frameworks and the usage of the [Dialectic API](https://blog.plasticlabs.ai/blog/Introducing-Honcho's-Dialectic-API) to support them. Language models are highly capable of modeling human psychology. By building a data management framework that is user-centric, we aim to address not only practical application development issues (like scaling, statefulness, etc.) but also kickstart exploration of the design space of what’s possible given access to rich user models. You can read more about Honcho’s origin, inspiration and philosophy on our [blog](https://blog.plasticlabs.ai/) . [​](https://docs.honcho.dev/v1/getting-started/architecture#core-primitives) Core Primitives ----------------------------------------------------------------------------------------------- Using Honcho has the following flow: 1. Initialize your `Honcho` instance and `App` 2. Create a `User` 3. Create a `Session` for a `User`. 4. Create a `Collection` for a `User` 5. Add `Message`s to a `User`’s `Session`. 6. Add `Metamessage`s to a `User` (optional links to `Session`, `Message`) 7. Add `Document`s to a `User`’s `Collection` ### [​](https://docs.honcho.dev/v1/getting-started/architecture#apps) Apps An `App` is the highest-level primitive in Honcho. It is the scope that all of your `Users` are bound to. ### [​](https://docs.honcho.dev/v1/getting-started/architecture#users) Users The `User` object is the main interface for managing a User’s context. With it you can interface with the `User`’s `Session`s and `Collections`s directly. ### [​](https://docs.honcho.dev/v1/getting-started/architecture#sessions) Sessions The `Session` object is useful for organizing your interactions with `User`s. Different `User`s can have different sessions enabling you to neatly segment user context. It also accepts a `location_id` parameter which can specifically denote _where_ users’ sessions are taking place. ### [​](https://docs.honcho.dev/v1/getting-started/architecture#messages) Messages Sessions are made up of `Message` objects. You can append them to sessions. This is pretty straightforward. ### [​](https://docs.honcho.dev/v1/getting-started/architecture#metamessages) Metamessages Success in LLM applications is dependent on elegant context management, so we provide a `Metamessage` object for flexible context storage and construction. Each `Metamessage` is tied to a `User` object via the required `user_id` argument. Keeping this separate from the core user-assistant message history ensures the insights service running ambiently is doing so on authentic ground truth We’ve found this particularly useful for storing intermediate inferences, constructing very specific chat histories, and more. Metamessages can optionally be attached to sessions and/or messages, so constructing historical context for inference is as easy as possible. ### [​](https://docs.honcho.dev/v1/getting-started/architecture#collections) Collections `Collections` are used to organize information about the `User`. These can be thought of as stores for more global data about the `User` that spans sessions while `Metamessages` are local to a session and the message they are linked to. ### [​](https://docs.honcho.dev/v1/getting-started/architecture#documents) Documents `Documents` are the individual facts that are stored in the `Collection`. They are stored as vector embeddings to allow for a RAG like interface. Using honcho a developer can query a collection of documents using methods like cosine similarity search [​](https://docs.honcho.dev/v1/getting-started/architecture#conclusion) Conclusion ------------------------------------------------------------------------------------- Too often we hear developers enjoying a certain framework for building LLM-powered applications only to see their codebase reach a level of complexity that hits the limits of said framework. It ultimately gets abandoned and developers implement their own solutions that without a doubt increase overhead and maintenance. Our goal with Honcho is to provide a simple and flexible storage framework accompanied by a smooth developer experience to ease pains building the cumbersome parts of LLM applications. We hope this will allow developers more freedom to explore exciting, yet-to-be-discovered areas! [Quickstart](https://docs.honcho.dev/v1/getting-started/quickstart) [Guidelines](https://docs.honcho.dev/v1/contributing/guidelines) ⌘I --- # Deploying Honcho - Honcho [Skip to main content](https://docs.honcho.dev/v1/contributing/deploying#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation Contributing Deploying Honcho [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) If you’re happy with how things are working locally, deploying your Honcho instance is a breeze with [Fly](https://fly.io/) . Follow the [Fly.io Docs](https://fly.io/docs/getting-started/) to setup your environment and the `flyctl`. A sample `fly.toml` is included for convenience in the repository. Note. The fly.toml does not include launching a Postgres database. This must be configured separately Once `flyctl` is set up use the the following commands to launch the application: cd honcho flyctl launch --no-deploy # Follow the prompts and edit as you see fit cat .env | flyctl secrets import # Load in your secrets flyctl deploy # Deploy with appropriate environment variables Then you should have a new URL to initialize your Honcho client with! Consider your user context managed 🪄.\` [Self-Hosting](https://docs.honcho.dev/v1/contributing/self-hosting) [License](https://docs.honcho.dev/v1/contributing/license) ⌘I --- # Spellbooks and Tutorials - Honcho [Skip to main content](https://docs.honcho.dev/v1/guides/overview#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation Getting Started Spellbooks and Tutorials [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) [Streaming Responses](https://docs.honcho.dev/v1/guides/streaming-response) ⌘I --- # 🫡 Welcome to Honcho - Honcho [Skip to main content](https://docs.honcho.dev/v1/getting-started/introduction#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation Get Started 🫡 Welcome to Honcho [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) [![Python package version](https://img.shields.io/pypi/v/honcho-ai?color=orange)](https://pypi.org/project/honcho-ai/) [![GitHub Stars](https://img.shields.io/github/stars/plastic-labs/honcho?logo=github)](https://github.com/plastic-labs/honcho) [![pip installs](https://static.pepy.tech/personalized-badge/honcho-ai?period=total&units=international_system&left_color=grey&right_color=blue&left_text=pip%20installs)](https://pepy.tech/project/honcho-ai) [![npm package version](https://img.shields.io/npm/v/honcho-ai.svg)](https://npmjs.org/package/honcho-ai) Honcho is an infrastructure layer that empowers AI agents with social cognition and deeper understanding of their users. The API is built on two core concepts: _Storage_ and _Insights_. The Storage API provides a flexible memory framework that can store both chat conversations and vector embeddings of user interactions. This forms the foundation for building more socially aware agents. The Insights layer analyzes these stored interactions to build rich user profiles, which can be queried through a natural language dialectic endpoint. This allows agents to develop a nuanced understanding of users’ preferences, behaviors, and needs over time. By handling the complex infrastructure needed for memory and user understanding, Honcho lets you focus on building amazing AI experiences. No more worrying about how to scale personalization - we’ve got you covered. To learn more about the project, check out our [blog post](https://blog.plasticlabs.ai/blog/A-Simple-Honcho-Primer) . Get started below! Quickstart ---------- Quickly set up a local environment to interface with the Honcho API Architecture ------------ Get an overview of the different primitives and structure of Honcho Honcho Primer ------------- Read our blog post that introduces Honcho, the motivations behind it, and what it will enable. [Quickstart](https://docs.honcho.dev/v1/getting-started/quickstart) ⌘I --- # Guidelines - Honcho [Skip to main content](https://docs.honcho.dev/v1/contributing/guidelines#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation Contributing Guidelines [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) This project is completely open source and welcomes any and all open source contributions. The workflow for contributing is to make a fork of the repository. You can claim an issue in the issues tab or start a new thread to indicate a feature or bug fix you are working on. Once you have finished your contribution make a PR , and it will be reviewed by a project manager. Feel free to join us in our [discord](http://discord.gg/honcho) to discuss your changes or get help. Your changes will undergo a period of testing and discussion before finally being entered into the `main` branch and being staged for release. For more details, check out our [contributing](https://github.com/plastic-labs/honcho/blob/main/CONTRIBUTING.md) document. [Architecture](https://docs.honcho.dev/v1/getting-started/architecture) [Self-Hosting](https://docs.honcho.dev/v1/contributing/self-hosting) ⌘I --- # Self-Hosting Honcho - Honcho [Skip to main content](https://docs.honcho.dev/v1/contributing/self-hosting#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation Contributing Self-Hosting Honcho [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) On this page * [Prerequisites and Dependencies](https://docs.honcho.dev/v1/contributing/self-hosting#prerequisites-and-dependencies) * [Setup](https://docs.honcho.dev/v1/contributing/self-hosting#setup) * [Docker](https://docs.honcho.dev/v1/contributing/self-hosting#docker) > This guide was made using a M1 Macbook Pro. For any compatibility issues on different platforms please raise an Issue. ### [​](https://docs.honcho.dev/v1/contributing/self-hosting#prerequisites-and-dependencies) Prerequisites and Dependencies Honcho is developed using [python](https://www.python.org/) and [uv](https://docs.astral.sh/uv/) . The minimum python version is `3.9` The minimum poetry version is `0.4.9` ### [​](https://docs.honcho.dev/v1/contributing/self-hosting#setup) Setup Once the dependencies are installed on the system run the following steps to get the local project setup. 1. Clone the repository git clone https://github.com/plastic-labs/honcho.git 2. Enter the repository and install the python dependencies We recommend using a virtual environment to isolate the dependencies for Honcho from other projects on the same system. `uv` will create a virtual environment when you sync your dependencies in the project. Putting this together: cd honcho uv sync This will create a virtual environment and install the dependencies for Honcho. The default virtual environment will be located at `honcho/.venv`. Activate the virtual environment via: source honcho/.venv/bin/activate 3. Set up a database Honcho utilized [Postgres](https://www.postgresql.org/) for its database with pgvector. An easy way to get started with a postgresdb is to create a project with [Supabase](https://supabase.com/) A `docker-compose` template is also available with a database configuration available. 4. Edit the environment variables. Honcho uses a `.env` file for managing runtime environment variables. A `.env.template` file is included for convenience. Several of the configurations are not required and are only necessary for additional logging, monitoring, and security. Below are the required configurations CONNECTION_URI= # Connection uri for a postgres database OPENAI_API_KEY= # API Key for OpenAI used for embedding documents ANTHROPIC_API_KEY= # API Key for Anthropic used for the deriver and dialectic API > Note that the `CONNECTION_URI` must have the prefix `postgresql+psycopg` to function properly. This is a requirement brought by `sqlalchemy` The template has the additional functionality disabled by default. To ensure that they are disabled you can verify the following environment variables are set to false. USE_AUTH=false SENTRY_ENABLED=false 5. Launch the API With the dependencies installed, a database setup and enabled with `pgvector`, and the environment variables setup you can now launch a local instance of Honcho. The following command will launch the storage API for Honcho fastapi dev src/main.py This is a development server that will reload whenever code is changed. When first launching the API with a connection the database it will provision the necessary tables for Honcho to operate. ### [​](https://docs.honcho.dev/v1/contributing/self-hosting#docker) Docker As mentioned earlier a `docker-compose` template is included for running Honcho. As an alternative to running Honcho locally it can also be run with the compose template. Copy the template and update the appropriate environment variables before launching the service. cd honcho cp docker-compose.yml.example docker-compose.yml [ update the file with openai key and other wanted environment variables ] docker compose up [Guidelines](https://docs.honcho.dev/v1/contributing/guidelines) [Deploying](https://docs.honcho.dev/v1/contributing/deploying) ⌘I --- # Honcho MCP - Honcho [Skip to main content](https://docs.honcho.dev/v1/guides/honcho-mcp#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation Application Interfaces Honcho MCP [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) On this page * [Project Instructions](https://docs.honcho.dev/v1/guides/honcho-mcp#project-instructions) You can let Claude use Honcho to manage its own memory in the native desktop app by using the Honcho MCP integration! Follow these steps: 1. Clone the `honcho-mcp` repo: git clone git@github.com:plastic-labs/honcho-mcp.git 2. Navigate into the `honcho-mcp` folder. cd honcho-mcp 3. Sync the virtual environment. This package uses [uv](https://docs.astral.sh/uv/) , [install](https://docs.astral.sh/uv/#installation) if you haven’t. uv sync 4. In Claude Desktop, go to the _top left Mac Toolbar_ Settings > Developer and click “Edit Config” 5. Add the following (and update paths!): { "mcpServers": { "Honcho": { "command": "/path/to/uv", "args": [\ "run",\ "--with",\ "mcp[cli]",\ "mcp",\ "run",\ "/path/to/honcho-mcp/main.py"\ ] } } } You probably will need to put the full path to the uv executable in the command field. You can get this by running `which uv` on MacOS/Linux or `where uv` on Windows. 6. Restart the Claude Desktop app. Upon relaunch it should start Honcho and the tools should be available! Just note that, by default, the MCP server is set up to use the Honcho Demo server, which only persists data for 7 days. If you’re using the hosted version of Honcho, copy the `.env.template` to a proper `.env` file and update the URL and API key variables accordingly. [​](https://docs.honcho.dev/v1/guides/honcho-mcp#project-instructions) Project Instructions ---------------------------------------------------------------------------------------------- Finally, Claude needs instructions on how to use Honcho. The Desktop app doesn’t allow you to add system prompts directly, but you can create a project and paste these [instructions](https://github.com/plastic-labs/honcho-mcp/blob/main/instructions.txt) into the “Project Instructions” field. Be sure to update the and variables in the instructions.txt file. Claude should then query for insights before responding and write your messages to storage! If you come up with more creative ways to get Claude to manage its own memory with Honcho, feel free to [let us know](https://discord.gg/honcho) or make a PR on this [repo](https://github.com/plastic-labs/honcho-mcp/tree/main) ! [Discord](https://docs.honcho.dev/v1/guides/discord) [Dialectic Endpoint](https://docs.honcho.dev/v1/guides/dialectic-endpoint) ⌘I --- # Dialectic Endpoint - Honcho [Skip to main content](https://docs.honcho.dev/v1/guides/dialectic-endpoint#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation Personal Memory Dialectic Endpoint [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) On this page * [Automatic Fact Derivation](https://docs.honcho.dev/v1/guides/dialectic-endpoint#automatic-fact-derivation) * [Dialectic Endpoint](https://docs.honcho.dev/v1/guides/dialectic-endpoint#dialectic-endpoint) * [Prerequisites](https://docs.honcho.dev/v1/guides/dialectic-endpoint#prerequisites) * [Static Dialectic Call](https://docs.honcho.dev/v1/guides/dialectic-endpoint#static-dialectic-call) * [Streaming Dialectic Call](https://docs.honcho.dev/v1/guides/dialectic-endpoint#streaming-dialectic-call) Honcho by default runs ambient inference on top of the `message` objects you store. Those messages serve as the ground truth upon which facts about the user are derived and stored. The **Dialectic Endpoint** is the natural language interface through which insights are synthesized from those facts. We believe [intellectual respect](https://blog.plasticlabs.ai/extrusions/Extrusion-02.24) for LLMs is paramount in building effective AI agents/apps. It follows that the LLM should know better than any human what would aid them in their generation task. Thus, the Dialectic endpoint exists for flexible agent-to-agent communication. [​](https://docs.honcho.dev/v1/guides/dialectic-endpoint#automatic-fact-derivation) Automatic Fact Derivation ---------------------------------------------------------------------------------------------------------------- On every message written to a session, an automatic callback is run that will reason about the conversation and store facts in a `collection` named `honcho`. This is a reserved `collection` specifically for the backend Honcho agent to interact with. [​](https://docs.honcho.dev/v1/guides/dialectic-endpoint#dialectic-endpoint) Dialectic Endpoint -------------------------------------------------------------------------------------------------- You can query the automatically derived facts in the `honcho` collection directly, or you can offload this task to our agent and use the Dialectic endpoint. This endpoint allows you to define logic enabling your agent to talk to our agent that automatically retrieves and synthesizes facts from the collection. This chat interface is exposed via the `chat` endpoint. It accepts a string or a list of strings. Below is some example code on how this works. [​](https://docs.honcho.dev/v1/guides/dialectic-endpoint#prerequisites) Prerequisites ---------------------------------------------------------------------------------------- Python NodeJS from honcho import Honcho honcho = Honcho() # Create or get an existing App app = honcho.apps.get_or_create(name="demo-app") # create or get user user = honcho.apps.users.get_or_create(app_id=app.id, name="demo-user") # create a new session session = honcho.apps.users.session.create(app_id=app.id, user_id=user.id) # (assuming some messages have been written to Honcho for the deriver to use) [​](https://docs.honcho.dev/v1/guides/dialectic-endpoint#static-dialectic-call) Static Dialectic Call -------------------------------------------------------------------------------------------------------- Python NodeJS query = "What is the user's favorite way of completing the task?" answer = honcho.apps.users.session.chat(app_id=app.id, user_id=user.id, session_id=session.id, queries=query) [​](https://docs.honcho.dev/v1/guides/dialectic-endpoint#streaming-dialectic-call) Streaming Dialectic Call -------------------------------------------------------------------------------------------------------------- Python NodeJS with honcho.apps.users.sessions.with_streaming_response.stream( app_id=app.id, user_id=user.id, session_id=session.id, queries="What do we know about the user", ) as response: print(response) for line in response.iter_text(): print(line) time.sleep(0.025) We’ve designed the Dialectic endpoint to be infinitely flexible. We wrote an incomplete list of ideas on how to use it on our blog [here](https://blog.plasticlabs.ai/blog/Introducing-Honcho's-Dialectic-API#how-it-works) . [Claude Desktop](https://docs.honcho.dev/v1/guides/honcho-mcp) ⌘I --- # Contributing Guidelines - Honcho [Skip to main content](https://docs.honcho.dev/v2/contributing/guidelines#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Contributing Contributing Guidelines [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [Getting Started](https://docs.honcho.dev/v2/contributing/guidelines#getting-started) * [Contribution Workflow](https://docs.honcho.dev/v2/contributing/guidelines#contribution-workflow) * [1\. Fork and Clone](https://docs.honcho.dev/v2/contributing/guidelines#1-fork-and-clone) * [2\. Create a Branch](https://docs.honcho.dev/v2/contributing/guidelines#2-create-a-branch) * [3\. Make Your Changes](https://docs.honcho.dev/v2/contributing/guidelines#3-make-your-changes) * [4\. Commit Your Changes](https://docs.honcho.dev/v2/contributing/guidelines#4-commit-your-changes) * [5\. Submit a Pull Request](https://docs.honcho.dev/v2/contributing/guidelines#5-submit-a-pull-request) * [Coding Standards](https://docs.honcho.dev/v2/contributing/guidelines#coding-standards) * [Python Code Style](https://docs.honcho.dev/v2/contributing/guidelines#python-code-style) * [Code Organization](https://docs.honcho.dev/v2/contributing/guidelines#code-organization) * [Testing](https://docs.honcho.dev/v2/contributing/guidelines#testing) * [Documentation](https://docs.honcho.dev/v2/contributing/guidelines#documentation) * [Review Process](https://docs.honcho.dev/v2/contributing/guidelines#review-process) * [Types of Contributions](https://docs.honcho.dev/v2/contributing/guidelines#types-of-contributions) * [Issue Reporting](https://docs.honcho.dev/v2/contributing/guidelines#issue-reporting) * [Questions and Support](https://docs.honcho.dev/v2/contributing/guidelines#questions-and-support) * [License](https://docs.honcho.dev/v2/contributing/guidelines#license) Thank you for your interest in contributing to Honcho! This guide outlines the process for contributing to the project and our development conventions. [​](https://docs.honcho.dev/v2/contributing/guidelines#getting-started) Getting Started ------------------------------------------------------------------------------------------ Before you start contributing, please: 1. **Set up your development environment** - Follow the [Local Development guide](https://github.com/plastic-labs/honcho/blob/main/CONTRIBUTING.md#local-development) in the Honcho repository to get Honcho running locally. 2. **Join our community** - Feel free to join us in our [Discord](http://discord.gg/honcho) to discuss your changes, get help, or ask questions. 3. **Review existing issues** - Check the [issues tab](https://github.com/plastic-labs/honcho/issues) to see what’s already being worked on or to find something to contribute to. [​](https://docs.honcho.dev/v2/contributing/guidelines#contribution-workflow) Contribution Workflow ------------------------------------------------------------------------------------------------------ ### [​](https://docs.honcho.dev/v2/contributing/guidelines#1-fork-and-clone) 1\. Fork and Clone 1. Fork the repository on GitHub 2. Clone your fork locally: git clone https://github.com/YOUR_USERNAME/honcho.git cd honcho 3. Add the upstream repository as a remote: git remote add upstream https://github.com/plastic-labs/honcho.git ### [​](https://docs.honcho.dev/v2/contributing/guidelines#2-create-a-branch) 2\. Create a Branch Create a new branch for your feature or bug fix: git checkout -b feature/your-feature-name # or git checkout -b fix/your-bug-fix-name **Branch naming conventions:** * `feature/description` - for new features * `fix/description` - for bug fixes * `docs/description` - for documentation updates * `refactor/description` - for code refactoring * `test/description` - for adding or updating tests ### [​](https://docs.honcho.dev/v2/contributing/guidelines#3-make-your-changes) 3\. Make Your Changes * Write clean, readable code that follows our coding standards (see below) * Add tests for new functionality * Update documentation as needed * Make sure your changes don’t break existing functionality ### [​](https://docs.honcho.dev/v2/contributing/guidelines#4-commit-your-changes) 4\. Commit Your Changes We follow conventional commit standards. Format your commit messages as: type(scope): description [optional body] [optional footer] **Types:** * `feat`: A new feature * `fix`: A bug fix * `docs`: Documentation only changes * `style`: Changes that do not affect the meaning of the code * `refactor`: A code change that neither fixes a bug nor adds a feature * `test`: Adding missing tests or correcting existing tests * `chore`: Changes to the build process or auxiliary tools **Examples:** git commit -m "feat(api): add new dialectic endpoint for user insights" git commit -m "fix(db): resolve connection pool timeout issue" git commit -m "docs(readme): update installation instructions" ### [​](https://docs.honcho.dev/v2/contributing/guidelines#5-submit-a-pull-request) 5\. Submit a Pull Request 1. Push your branch to your fork: git push origin your-branch-name 2. Create a pull request on GitHub from your branch to the `main` branch 3. Fill out the pull request template with: * A clear description of what changes you’ve made * The motivation for the changes * Any relevant issue numbers (use “Closes #123” to auto-close issues) * Screenshots or examples if applicable [​](https://docs.honcho.dev/v2/contributing/guidelines#coding-standards) Coding Standards -------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v2/contributing/guidelines#python-code-style) Python Code Style * Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guidelines * Use [Black](https://black.readthedocs.io/) for code formatting (we may add this to CI in the future) * Use type hints where possible * Write docstrings for functions and classes using Google style docstrings ### [​](https://docs.honcho.dev/v2/contributing/guidelines#code-organization) Code Organization * Keep functions focused and single-purpose * Use meaningful variable and function names * Add comments for complex logic * Follow existing patterns in the codebase ### [​](https://docs.honcho.dev/v2/contributing/guidelines#testing) Testing * Write unit tests for new functionality * Ensure existing tests pass before submitting * Use descriptive test names that explain what is being tested * Mock external dependencies appropriately ### [​](https://docs.honcho.dev/v2/contributing/guidelines#documentation) Documentation * Update relevant documentation for new features * Include examples in docstrings where helpful * Keep README and other docs up to date with changes [​](https://docs.honcho.dev/v2/contributing/guidelines#review-process) Review Process ---------------------------------------------------------------------------------------- 1. **Automated checks** - Your PR will run through automated checks including tests and linting 2. **Project maintainer review** - A project maintainer will review your code for: * Code quality and adherence to standards * Functionality and correctness * Test coverage * Documentation completeness 3. **Discussion and iteration** - You may be asked to make changes or clarifications 4. **Approval and merge** - Once approved, your PR will be merged into `main` [​](https://docs.honcho.dev/v2/contributing/guidelines#types-of-contributions) Types of Contributions -------------------------------------------------------------------------------------------------------- We welcome various types of contributions: * **Bug fixes** - Help us squash bugs and improve stability * **New features** - Add functionality that benefits the community * **Documentation** - Improve or expand our documentation * **Tests** - Increase test coverage and reliability * **Performance improvements** - Help make Honcho faster and more efficient * **Examples and tutorials** - Help other developers use Honcho [​](https://docs.honcho.dev/v2/contributing/guidelines#issue-reporting) Issue Reporting ------------------------------------------------------------------------------------------ When reporting bugs or requesting features: 1. Check if the issue already exists 2. Use the appropriate issue template 3. Provide clear reproduction steps for bugs 4. Include relevant environment information 5. Be specific about expected vs actual behavior [​](https://docs.honcho.dev/v2/contributing/guidelines#questions-and-support) Questions and Support ------------------------------------------------------------------------------------------------------ * **General questions** - Join our [Discord](http://discord.gg/honcho) * **Bug reports** - Use GitHub issues * **Feature requests** - Use GitHub issues with the feature request template * **Security issues** - Please email us privately rather than opening a public issue [​](https://docs.honcho.dev/v2/contributing/guidelines#license) License -------------------------------------------------------------------------- By contributing to Honcho, you agree that your contributions will be licensed under the same [AGPL-3.0 License](https://docs.honcho.dev/v2/contributing/license) that covers the project. Thank you for helping make Honcho better! 🫡 [Local Environment](https://docs.honcho.dev/v2/contributing/self-hosting) ⌘I --- # Spellbooks and Tutorials - Honcho [Skip to main content](https://docs.honcho.dev/v2/guides/overview#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Getting Started Spellbooks and Tutorials [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [Getting Started](https://docs.honcho.dev/v2/guides/overview#getting-started) * [Application Interfaces](https://docs.honcho.dev/v2/guides/overview#application-interfaces) Before you start a tutorial, follow [Quickstart](https://docs.honcho.dev/v2/documentation/introduction/quickstart) to get up and running with Honcho in your language of choice. AI development often feels like magic - you craft the right prompt and get exactly what you need. Our Spellbooks are practical guides that show you how to cast effective spells with Honcho. Whether you’re integrating Honcho into existing platforms, exploring advanced features, or getting up and running quickly, these guides provide concrete examples and implementation patterns. Each spellbook focuses on a specific use case with working code you can adapt to your needs. The goal is to get you from idea to working prototype as quickly as possible, then provide the depth you need to scale and customize. [​](https://docs.honcho.dev/v2/guides/overview#getting-started) Getting Started ---------------------------------------------------------------------------------- Quick integration guides to get up and running: MCP Integration --------------- Get Honcho running with a single prompt in Claude Code LangGraph --------- Add persistent memory and theory of mind to your LangGraph agents [​](https://docs.honcho.dev/v2/guides/overview#application-interfaces) Application Interfaces ------------------------------------------------------------------------------------------------ Ready-to-use integration patterns for popular platforms: Discord Bot ----------- Build a Discord bot that remembers users across conversations Telegram Bot ------------ Create a Telegram bot with persistent user understanding [Migrating from Mem0](https://docs.honcho.dev/v2/migrations/from-mem0) ⌘I --- # Discord Bots with Honcho - Honcho [Skip to main content](https://docs.honcho.dev/v1/guides/discord#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation Application Interfaces Discord Bots with Honcho [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) On this page * [Events](https://docs.honcho.dev/v1/guides/discord#events) * [Helper functions](https://docs.honcho.dev/v1/guides/discord#helper-functions) * [Slash Commands](https://docs.honcho.dev/v1/guides/discord#slash-commands) * [Recap](https://docs.honcho.dev/v1/guides/discord#recap) > Example code is available on [GitHub](https://github.com/plastic-labs/discord-python-starter) Any application interface that defines logic based on events and supports special commands can work easily with Honcho. Here’s how to use Honcho with **Discord** as an interface. If you’re not familiar with Discord bot application logic, the [py-cord](https://pycord.dev/) docs would be a good place to start. [​](https://docs.honcho.dev/v1/guides/discord#events) Events --------------------------------------------------------------- Most Discord bots have async functions that listen for specific events, the most common one being messages. We can use Honcho to store messages by user and session based on an interface’s event logic. Take the following function definition for example: @bot.event async def on_message(message): """Event that is run when a message is sent in a channel or DM that the bot has access to""" global last_message_id if message.author == bot.user: # ensure the bot does not reply to itself return is_dm = isinstance(message.channel, discord.DMChannel) is_reply_to_bot = ( message.reference and message.reference.resolved.author == bot.user ) is_mention = bot.user.mentioned_in(message) if is_dm or is_reply_to_bot or is_mention: # Remove the bot's mention from the message content if present input = message.content.replace(f"<@{bot.user.id}>", "").strip() # If the message is empty after removing the mention, ignore it if not input: return # Get a user object for the message author user_id = f"discord_{str(message.author.id)}" user = honcho.apps.users.get_or_create(name=user_id, app_id=app.id) # Use the channel ID as the location_id (for DMs, this will be unique to the user) location_id = str(message.channel.id) # Get or create a session for this user and location session, _ = get_session(user.id, location_id, create=True) # Get messages history_iter = honcho.apps.users.sessions.messages.list( app_id=app.id, session_id=session.id, user_id=user.id ) history = list(msg for msg in history_iter) # Add user message to session user_msg = honcho.apps.users.sessions.messages.create( app_id=app.id, user_id=user.id, session_id=session.id, content=input, is_user=True, ) last_message_id = user_msg.id async with message.channel.typing(): response = llm(input, history) if len(response) > 1500: # Split response into chunks at newlines, keeping under 1500 chars chunks = [] current_chunk = "" for line in response.splitlines(keepends=True): if len(current_chunk) + len(line) > 1500: chunks.append(current_chunk) current_chunk = line else: current_chunk += line if current_chunk: chunks.append(current_chunk) for chunk in chunks: await message.channel.send(chunk) else: await message.channel.send(response) # Add bot message to session honcho.apps.users.sessions.messages.create( app_id=app.id, user_id=user.id, session_id=session.id, content=response, is_user=False, ) Let’s break down what this code is doing… @bot.event async def on_message(message): if message.author == bot.user: return This is how you define an event function in `py-cord` that listens for messages and checks that the bot doesn’t respond to itself. is_dm = isinstance(message.channel, discord.DMChannel) is_reply_to_bot = ( message.reference and message.reference.resolved.author == bot.user ) is_mention = bot.user.mentioned_in(message) These lines check what kind of message is being sent in Discord, which is a useful condition to check before entering the reply logic. The code inside that if-statement is commented quite well, so we’ll just go over the relevant Honcho parts. # Get a user object for the message author user_id = f"discord_{str(message.author.id)}" user = honcho.apps.users.get_or_create(name=user_id, app_id=app.id) Here we’re getting or creating a user for an app that’s been defined at the top of the file. # Use the channel ID as the location_id (for DMs, this will be unique to the user) location_id = str(message.channel.id) # Get or create a session for this user and location session, _ = get_session(user.id, location_id, create=True) Here we’re using the discord channel ID as a unique `location_id` to attach as metadata to the session. Then we have a nice [helper function](https://github.com/plastic-labs/discord-python-starter/blob/main/src/bot.py#L85) to take care of some of the session querying logic—we’ll dive into that shortly. # Get messages history_iter = honcho.apps.users.sessions.messages.list( app_id=app.id, session_id=session.id, user_id=user.id ) history = list(msg for msg in history_iter) When you call the `list` method, it returns an iterable which you can quickly loop over to create a list of `Message` objects. Then, we make the call to the LLM using another neat [helper function](https://github.com/plastic-labs/discord-python-starter/blob/main/src/bot.py#L52) that we will cover. [​](https://docs.honcho.dev/v1/guides/discord#helper-functions) Helper functions ----------------------------------------------------------------------------------- The first helper function we create is called `get_session`. This simplifies a lot of our session-querying logic. def get_session(user_id, location_id, create=False): # Get an existing session for the user and location or optionally create a new one if none exists. # Returns a tuple of (session, is_new) where is_new indicates if a new session was created. # Query for *active* sessions with both user_id and location_id sessions_iter = honcho.apps.users.sessions.list( app_id=app.id, user_id=user_id, reverse=True, filters={"is_active": True} ) sessions = list(session for session in sessions_iter) # Find the right session for session in sessions: if session.metadata.get("location_id") == location_id: return session, False # If no session is found and create is True, create a new one if create: print("No active session found, creating new one") return honcho.apps.users.sessions.create( user_id=user_id, app_id=app.id, metadata={"location_id": location_id}, ), True return None, False You can see the `list` method on the sessions object similarly returns an iterable. This is a common pattern in Honcho—use list comprehension to create your new python list. Then loop through those session objects to find the appropriate `location_id` in the metadata, and if none are found then create a new session. You’ll also notice we list messages in `reverse=True` order—this means you will get the most recent ones first. We also support native filtering by active sessions and any other fields or user-defined metadata on the session object. The next helper function we create is called `llm`. This simplifies constructing the chat message object we’re going to send to the inference provider. def llm(prompt, previous_chats=None): messages = [] # Add system message with documentation context messages.append( { "role": "system", "content": f"You are a helpful assistant." } ) if previous_chats: messages.extend( [\ {"role": "user" if msg.is_user else "assistant", "content": msg.content}\ for msg in previous_chats\ ] ) messages.append({"role": "user", "content": prompt}) try: completion = openai.chat.completions.create( model=MODEL_NAME, messages=messages, ) return completion.choices[0].message.content except Exception as e: print(e) return f"Error: {e}" Note that `messages` is a list of dictionaries that are individually defined with key-value pairs for roles and content. We again use list comprehension to unpack historical message objects into the list that we send to the chat completions method. Honcho `Message` objects store role and content natively to make this context construction as simple as possible. If you’re interested in learning more about native Honcho objects, you can check out the [`models.py`](https://github.com/plastic-labs/honcho/blob/main/src/models.py) file. [​](https://docs.honcho.dev/v1/guides/discord#slash-commands) Slash Commands ------------------------------------------------------------------------------- Discord bots also offer slash command functionality. We can use Honcho to do interesting things via slash commands. Here’s a simple example: @bot.slash_command( name="restart", description="Reset all of your messaging history with Honcho in this channel.", ) async def restart(ctx): print(f"restarting conversation for {ctx.author.name}") async with ctx.typing(): user_name = f"discord_{str(ctx.author.id)}" user = honcho.apps.users.get_or_create(name=user_name, app_id=app.id) location_id = str(ctx.channel_id) # Get existing session session, _ = get_session(user.id, location_id, create=False) if session: # Delete the session honcho.apps.users.sessions.delete( app_id=app.id, user_id=user.id, session_id=session.id ) msg = "The conversation has been restarted." await ctx.respond(msg) This slash command restarts a conversation with a bot. In Honcho, the `delete` method marks a session’s `is_active` field to `False`. [​](https://docs.honcho.dev/v1/guides/discord#recap) Recap ------------------------------------------------------------- How you use Honcho is tightly coupled with the client you’re building in. Here, Discord serves as an example of an interactive chat interface. We’re just scratching the surface of things you can do with Honcho, but we learned some key patterns: * how to register users * how to work with iterables when listing sessions, messages * how to attach metadata to Honcho objects (like `location_id` on sessions) * how to sort and filter when calling list methods You are well on your way to becoming a context construction master! Stay tuned for more in-depth examples. If you want a challenge, try deciphering how we construct context in one of our apps, [Bloom](https://github.com/plastic-labs/tutor-gpt/blob/main/app/Chat.tsx) . [Streaming Responses](https://docs.honcho.dev/v1/guides/streaming-response) [Claude Desktop](https://docs.honcho.dev/v1/guides/honcho-mcp) ⌘I --- # License - Honcho [Skip to main content](https://docs.honcho.dev/v1/contributing/license#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation Contributing License [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) Honcho is licensed under the AGPL-3.0 License. This is copied below for convenience and also present in the [GitHub Repository](https://github.com/plastic-labs/honcho) GNU AFFERO GENERAL PUBLIC LICENSE Version 3, 19 November 2007 Copyright (C) 2007 Free Software Foundation, Inc. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The GNU Affero General Public License is a free, copyleft license for software and other kinds of works, specifically designed to ensure cooperation with the community in the case of network server software. The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, our General Public Licenses are intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things. Developers that use our General Public Licenses protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License which gives you legal permission to copy, distribute and/or modify the software. A secondary benefit of defending all users' freedom is that improvements made in alternate versions of the program, if they receive widespread use, become available for other developers to incorporate. Many developers of free software are heartened and encouraged by the resulting cooperation. However, in the case of software used on network servers, this result may fail to come about. The GNU General Public License permits making a modified version and letting the public access it on a server without ever releasing its source code to the public. The GNU Affero General Public License is designed specifically to ensure that, in such cases, the modified source code becomes available to the community. It requires the operator of a network server to provide the source code of the modified version running there to the users of that server. Therefore, public use of a modified version, on a publicly accessible server, gives the public access to the source code of the modified version. An older license, called the Affero General Public License and published by Affero, was designed to accomplish similar goals. This is a different license, not a version of the Affero GPL, but Affero has released a new version of the Affero GPL which permits relicensing under this license. The precise terms and conditions for copying, distribution and modification follow. TERMS AND CONDITIONS 0. Definitions. "This License" refers to version 3 of the GNU Affero General Public License. "Copyright" also means copyright-like laws that apply to other kinds of works, such as semiconductor masks. "The Program" refers to any copyrightable work licensed under this License. Each licensee is addressed as "you". "Licensees" and "recipients" may be individuals or organizations. To "modify" a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a "modified version" of the earlier work or a work "based on" the earlier work. A "covered work" means either the unmodified Program or a work based on the Program. To "propagate" a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well. To "convey" a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying. An interactive user interface displays "Appropriate Legal Notices" to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion. 1. Source Code. The "source code" for a work means the preferred form of the work for making modifications to it. "Object code" means any non-source form of a work. A "Standard Interface" means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language. The "System Libraries" of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A "Major Component", in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it. The "Corresponding Source" for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work. The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source. The Corresponding Source for a work in source code form is that same work. 2. Basic Permissions. All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law. You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you. Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary. 3. Protecting Users' Legal Rights From Anti-Circumvention Law. No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures. When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures. 4. Conveying Verbatim Copies. You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program. You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee. 5. Conveying Modified Source Versions. You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions: a) The work must carry prominent notices stating that you modified it, and giving a relevant date. b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to "keep intact all notices". c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it. d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so. A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an "aggregate" if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate. 6. Conveying Non-Source Forms. You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways: a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange. b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge. c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b. d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements. e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d. A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work. A "User Product" is either (1) a "consumer product", which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, "normally used" refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product. "Installation Information" for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made. If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM). The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network. Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying. 7. Additional Terms. "Additional permissions" are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions. When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission. Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms: a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or d) Limiting the use for publicity purposes of names of licensors or authors of the material; or e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors. All other non-permissive additional terms are considered "further restrictions" within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying. If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms. Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way. 8. Termination. You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11). However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation. Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice. Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10. 9. Acceptance Not Required for Having Copies. You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so. 10. Automatic Licensing of Downstream Recipients. Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License. An "entity transaction" is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts. You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it. 11. Patents. A "contributor" is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's "contributor version". A contributor's "essential patent claims" are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, "control" includes the right to grant patent sublicenses in a manner consistent with the requirements of this License. Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version. In the following three paragraphs, a "patent license" is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To "grant" such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party. If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. "Knowingly relying" means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid. If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it. A patent license is "discriminatory" if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007. Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law. 12. No Surrender of Others' Freedom. If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program. 13. Remote Network Interaction; Use with the GNU General Public License. Notwithstanding any other provision of this License, if you modify the Program, your modified version must prominently offer all users interacting with it remotely through a computer network (if your version supports such interaction) an opportunity to receive the Corresponding Source of your version by providing access to the Corresponding Source from a network server at no charge, through some standard or customary means of facilitating copying of software. This Corresponding Source shall include the Corresponding Source for any work covered by version 3 of the GNU General Public License that is incorporated pursuant to the following paragraph. Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the work with which it is combined will remain governed by version 3 of the GNU General Public License. 14. Revised Versions of this License. The Free Software Foundation may publish revised and/or new versions of the GNU Affero General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU Affero General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU Affero General Public License, you may choose any version ever published by the Free Software Foundation. If the Program specifies that a proxy can decide which future versions of the GNU Affero General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program. Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version. 15. Disclaimer of Warranty. THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 16. Limitation of Liability. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 17. Interpretation of Sections 15 and 16. If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee. END OF TERMS AND CONDITIONS How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program. If not, see . Also add information on how to contact you by electronic and paper mail. If your software can interact with users remotely through a computer network, you should also make sure that it provides a way for users to get its source. For example, if your program is a web application, its interface could display a "Source" link that leads users to an archive of the code. There are many ways you could offer source, and different solutions will be better for different programs; see section 13 for the specific requirements. You should also get your employer (if you work as a programmer) or school, if any, to sign a "copyright disclaimer" for the program, if necessary. For more information on this, and how to apply and follow the GNU AGPL, see . [Deploying](https://docs.honcho.dev/v1/contributing/deploying) ⌘I --- # Model Context Protocol (MCP) - Honcho [Skip to main content](https://docs.honcho.dev/v2/integrations/mcp#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Integrations Model Context Protocol (MCP) [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) You can let Claude use Honcho to manage its own memory in the native desktop app by using the Honcho MCP integration! Follow these steps: 1. Go to [https://app.honcho.dev](https://app.honcho.dev/) and get an API key. Then go to Claude Desktop and navigate to custom MCP servers. If you don’t have node installed you will need to do that. Claude Desktop or Claude Code can help! 2. Add Honcho to your Claude desktop config. You must provide a username for Honcho to refer to you as — preferably what you want Claude to actually call you. { "mcpServers": { "honcho": { "command": "npx", "args": [\ "mcp-remote",\ "https://mcp.honcho.dev",\ "--header",\ "Authorization:${AUTH_HEADER}",\ "--header",\ "X-Honcho-User-Name:${USER_NAME}"\ ], "env": { "AUTH_HEADER": "Bearer ", "USER_NAME": "" } } } } You may customize your assistant name and/or workspace ID. Both are optional. { "mcpServers": { "honcho": { "command": "npx", "args": [\ "mcp-remote",\ "https://mcp.honcho.dev",\ "--header",\ "Authorization:${AUTH_HEADER}",\ "--header",\ "X-Honcho-User-Name:${USER_NAME}",\ "--header",\ "X-Honcho-Assistant-Name:${ASSISTANT_NAME}",\ "--header",\ "X-Honcho-Workspace-ID:${WORKSPACE_ID}"\ ], "env": { "AUTH_HEADER": "Bearer ", "USER_NAME": "", "ASSISTANT_NAME": "", "WORKSPACE_ID": "" } } } } 3. Restart the Claude Desktop app. Upon relaunch, it should start Honcho and the tools should be available! 4. Finally, Claude needs instructions on how to use Honcho. The Desktop app doesn’t allow you to add system prompts directly, but you can create a project and paste these [instructions](https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md) into the “Project Instructions” field. Claude should then query for insights before responding and write your messages to storage! If you come up with more creative ways to get Claude to manage its own memory with Honcho, feel free to [let us know](https://discord.gg/honcho) or make a PR on this [repo](https://github.com/plastic-labs/honcho/tree/main/mcp) ! [LangGraph](https://docs.honcho.dev/v2/integrations/langgraph) [Discord Bot](https://docs.honcho.dev/v2/guides/discord) ⌘I --- # Contributing Guidelines - Honcho [Skip to main content](https://docs.honcho.dev/v3/contributing/guidelines#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Contributing Contributing Guidelines [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Getting Started](https://docs.honcho.dev/v3/contributing/guidelines#getting-started) * [Contribution Workflow](https://docs.honcho.dev/v3/contributing/guidelines#contribution-workflow) * [1\. Fork and Clone](https://docs.honcho.dev/v3/contributing/guidelines#1-fork-and-clone) * [2\. Create a Branch](https://docs.honcho.dev/v3/contributing/guidelines#2-create-a-branch) * [3\. Make Your Changes](https://docs.honcho.dev/v3/contributing/guidelines#3-make-your-changes) * [4\. Commit Your Changes](https://docs.honcho.dev/v3/contributing/guidelines#4-commit-your-changes) * [5\. Submit a Pull Request](https://docs.honcho.dev/v3/contributing/guidelines#5-submit-a-pull-request) * [Coding Standards](https://docs.honcho.dev/v3/contributing/guidelines#coding-standards) * [Python Code Style](https://docs.honcho.dev/v3/contributing/guidelines#python-code-style) * [Code Organization](https://docs.honcho.dev/v3/contributing/guidelines#code-organization) * [Testing](https://docs.honcho.dev/v3/contributing/guidelines#testing) * [Documentation](https://docs.honcho.dev/v3/contributing/guidelines#documentation) * [Review Process](https://docs.honcho.dev/v3/contributing/guidelines#review-process) * [Types of Contributions](https://docs.honcho.dev/v3/contributing/guidelines#types-of-contributions) * [Issue Reporting](https://docs.honcho.dev/v3/contributing/guidelines#issue-reporting) * [Questions and Support](https://docs.honcho.dev/v3/contributing/guidelines#questions-and-support) * [License](https://docs.honcho.dev/v3/contributing/guidelines#license) Thank you for your interest in contributing to Honcho! This guide outlines the process for contributing to the project and our development conventions. [​](https://docs.honcho.dev/v3/contributing/guidelines#getting-started) Getting Started ------------------------------------------------------------------------------------------ Before you start contributing, please: 1. **Set up your development environment** - Follow the [Local Development guide](https://github.com/plastic-labs/honcho/blob/main/CONTRIBUTING.md#local-development) in the Honcho repository to get Honcho running locally. 2. **Join our community** - Feel free to join us in our [Discord](http://discord.gg/honcho) to discuss your changes, get help, or ask questions. 3. **Review existing issues** - Check the [issues tab](https://github.com/plastic-labs/honcho/issues) to see what’s already being worked on or to find something to contribute to. [​](https://docs.honcho.dev/v3/contributing/guidelines#contribution-workflow) Contribution Workflow ------------------------------------------------------------------------------------------------------ ### [​](https://docs.honcho.dev/v3/contributing/guidelines#1-fork-and-clone) 1\. Fork and Clone 1. Fork the repository on GitHub 2. Clone your fork locally: git clone https://github.com/YOUR_USERNAME/honcho.git cd honcho 3. Add the upstream repository as a remote: git remote add upstream https://github.com/plastic-labs/honcho.git ### [​](https://docs.honcho.dev/v3/contributing/guidelines#2-create-a-branch) 2\. Create a Branch Create a new branch for your feature or bug fix: git checkout -b feature/your-feature-name # or git checkout -b fix/your-bug-fix-name **Branch naming conventions:** * `feature/description` - for new features * `fix/description` - for bug fixes * `docs/description` - for documentation updates * `refactor/description` - for code refactoring * `test/description` - for adding or updating tests ### [​](https://docs.honcho.dev/v3/contributing/guidelines#3-make-your-changes) 3\. Make Your Changes * Write clean, readable code that follows our coding standards (see below) * Add tests for new functionality * Update documentation as needed * Make sure your changes don’t break existing functionality ### [​](https://docs.honcho.dev/v3/contributing/guidelines#4-commit-your-changes) 4\. Commit Your Changes We follow conventional commit standards. Format your commit messages as: type(scope): description [optional body] [optional footer] **Types:** * `feat`: A new feature * `fix`: A bug fix * `docs`: Documentation only changes * `style`: Changes that do not affect the meaning of the code * `refactor`: A code change that neither fixes a bug nor adds a feature * `test`: Adding missing tests or correcting existing tests * `chore`: Changes to the build process or auxiliary tools **Examples:** git commit -m "feat(api): add new dialectic endpoint for user insights" git commit -m "fix(db): resolve connection pool timeout issue" git commit -m "docs(readme): update installation instructions" ### [​](https://docs.honcho.dev/v3/contributing/guidelines#5-submit-a-pull-request) 5\. Submit a Pull Request 1. Push your branch to your fork: git push origin your-branch-name 2. Create a pull request on GitHub from your branch to the `main` branch 3. Fill out the pull request template with: * A clear description of what changes you’ve made * The motivation for the changes * Any relevant issue numbers (use “Closes #123” to auto-close issues) * Screenshots or examples if applicable [​](https://docs.honcho.dev/v3/contributing/guidelines#coding-standards) Coding Standards -------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v3/contributing/guidelines#python-code-style) Python Code Style * Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guidelines * Use [Black](https://black.readthedocs.io/) for code formatting (we may add this to CI in the future) * Use type hints where possible * Write docstrings for functions and classes using Google style docstrings ### [​](https://docs.honcho.dev/v3/contributing/guidelines#code-organization) Code Organization * Keep functions focused and single-purpose * Use meaningful variable and function names * Add comments for complex logic * Follow existing patterns in the codebase ### [​](https://docs.honcho.dev/v3/contributing/guidelines#testing) Testing * Write unit tests for new functionality * Ensure existing tests pass before submitting * Use descriptive test names that explain what is being tested * Mock external dependencies appropriately ### [​](https://docs.honcho.dev/v3/contributing/guidelines#documentation) Documentation * Update relevant documentation for new features * Include examples in docstrings where helpful * Keep README and other docs up to date with changes [​](https://docs.honcho.dev/v3/contributing/guidelines#review-process) Review Process ---------------------------------------------------------------------------------------- 1. **Automated checks** - Your PR will run through automated checks including tests and linting 2. **Project maintainer review** - A project maintainer will review your code for: * Code quality and adherence to standards * Functionality and correctness * Test coverage * Documentation completeness 3. **Discussion and iteration** - You may be asked to make changes or clarifications 4. **Approval and merge** - Once approved, your PR will be merged into `main` [​](https://docs.honcho.dev/v3/contributing/guidelines#types-of-contributions) Types of Contributions -------------------------------------------------------------------------------------------------------- We welcome various types of contributions: * **Bug fixes** - Help us squash bugs and improve stability * **New features** - Add functionality that benefits the community * **Documentation** - Improve or expand our documentation * **Tests** - Increase test coverage and reliability * **Performance improvements** - Help make Honcho faster and more efficient * **Examples and tutorials** - Help other developers use Honcho [​](https://docs.honcho.dev/v3/contributing/guidelines#issue-reporting) Issue Reporting ------------------------------------------------------------------------------------------ When reporting bugs or requesting features: 1. Check if the issue already exists 2. Use the appropriate issue template 3. Provide clear reproduction steps for bugs 4. Include relevant environment information 5. Be specific about expected vs actual behavior [​](https://docs.honcho.dev/v3/contributing/guidelines#questions-and-support) Questions and Support ------------------------------------------------------------------------------------------------------ * **General questions** - Join our [Discord](http://discord.gg/honcho) * **Bug reports** - Use GitHub issues * **Feature requests** - Use GitHub issues with the feature request template * **Security issues** - Please email us privately rather than opening a public issue [​](https://docs.honcho.dev/v3/contributing/guidelines#license) License -------------------------------------------------------------------------- By contributing to Honcho, you agree that your contributions will be licensed under the same [AGPL-3.0 License](https://docs.honcho.dev/v3/contributing/license) that covers the project. Thank you for helping make Honcho better! 🫡 [Troubleshooting](https://docs.honcho.dev/v3/contributing/troubleshooting) [License](https://docs.honcho.dev/v3/contributing/license) ⌘I --- # Streaming Responses - Honcho [Skip to main content](https://docs.honcho.dev/v1/guides/streaming-response#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation Getting Started Streaming Responses [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) On this page * [Streaming Responses with Honcho](https://docs.honcho.dev/v1/guides/streaming-response#streaming-responses-with-honcho) * [When to Use Streaming](https://docs.honcho.dev/v1/guides/streaming-response#when-to-use-streaming) * [Streaming with the Dialectic Endpoint](https://docs.honcho.dev/v1/guides/streaming-response#streaming-with-the-dialectic-endpoint) * [Prerequisites](https://docs.honcho.dev/v1/guides/streaming-response#prerequisites) * [Streaming from the Dialectic Endpoint](https://docs.honcho.dev/v1/guides/streaming-response#streaming-from-the-dialectic-endpoint) * [Working with Streaming Data](https://docs.honcho.dev/v1/guides/streaming-response#working-with-streaming-data) * [Example: Restaurant Recommendation Chat](https://docs.honcho.dev/v1/guides/streaming-response#example-restaurant-recommendation-chat) * [Performance Considerations](https://docs.honcho.dev/v1/guides/streaming-response#performance-considerations) [​](https://docs.honcho.dev/v1/guides/streaming-response#streaming-responses-with-honcho) Streaming Responses with Honcho ============================================================================================================================ When working with AI-generated content, streaming the response as it’s generated can significantly improve the user experience. Honcho provides streaming functionality in its SDKs that allows your application to display content as it’s being generated, rather than waiting for the complete response. [​](https://docs.honcho.dev/v1/guides/streaming-response#when-to-use-streaming) When to Use Streaming -------------------------------------------------------------------------------------------------------- Streaming is particularly useful for: * Real-time chat interfaces * Long-form content generation * Applications where perceived speed is important * Interactive agent experiences * Reducing time-to-first-word in user interactions [​](https://docs.honcho.dev/v1/guides/streaming-response#streaming-with-the-dialectic-endpoint) Streaming with the Dialectic Endpoint ---------------------------------------------------------------------------------------------------------------------------------------- One of the primary use cases for streaming in Honcho is with the Dialectic endpoint. This allows you to stream the AI’s reasoning about a user in real-time. ### [​](https://docs.honcho.dev/v1/guides/streaming-response#prerequisites) Prerequisites Python NodeJS from honcho import Honcho honcho = Honcho() # Create or get an existing App app = honcho.apps.get_or_create(name="demo-app") # Create or get user user = honcho.apps.users.get_or_create(app_id=app.id, name="demo-user") # Create a new session session = honcho.apps.users.sessions.create(app_id=app.id, user_id=user.id) # Store some messages for context (optional) honcho.apps.users.sessions.messages.create( app_id=app.id, user_id=user.id, session_id=session.id, content="Hello, I'm testing the streaming functionality", is_user=True ) [​](https://docs.honcho.dev/v1/guides/streaming-response#streaming-from-the-dialectic-endpoint) Streaming from the Dialectic Endpoint ---------------------------------------------------------------------------------------------------------------------------------------- Python NodeJS import time # Basic streaming example with honcho.apps.users.sessions.with_streaming_response.stream( app_id=app.id, user_id=user.id, session_id=session.id, queries="What can you tell me about this user?", ) as response: for chunk in response.iter_text(): print(chunk, end="", flush=True) # Print each chunk as it arrives time.sleep(0.01) # Optional delay for demonstration [​](https://docs.honcho.dev/v1/guides/streaming-response#working-with-streaming-data) Working with Streaming Data -------------------------------------------------------------------------------------------------------------------- When working with streaming responses, consider these patterns: 1. **Progressive Rendering** - Update your UI as chunks arrive instead of waiting for the full response 2. **Buffered Processing** - Accumulate chunks until a logical break (like a sentence or paragraph) 3. **Token Counting** - Monitor token usage in real-time for applications with token limits 4. **Error Handling** - Implement appropriate error handling for interrupted streams [​](https://docs.honcho.dev/v1/guides/streaming-response#example-restaurant-recommendation-chat) Example: Restaurant Recommendation Chat ------------------------------------------------------------------------------------------------------------------------------------------- Python NodeJS import asyncio from honcho import Honcho async def restaurant_recommendation_chat(): honcho = Honcho() app = await honcho.apps.get_or_create(name="food-app") user = await honcho.apps.users.get_or_create(app_id=app.id, name="food-lover") session = await honcho.apps.users.sessions.create(app_id=app.id, user_id=user.id) # Store multiple user messages about food preferences user_messages = [\ "I absolutely love spicy Thai food, especially curries with coconut milk.",\ "Italian cuisine is another favorite - fresh pasta and wood-fired pizza are my weakness!",\ "I try to eat vegetarian most of the time, but occasionally enjoy seafood.",\ "I can't handle overly sweet desserts, but love something with dark chocolate."\ ] # Store the user's messages in the session for message in user_messages: await honcho.apps.users.sessions.messages.create( app_id=app.id, user_id=user.id, session_id=session.id, content=message, is_user=True ) print(f"User: {message}") # Ask for restaurant recommendations based on preferences print("\nRequesting restaurant recommendations...") print("Assistant: ", end="", flush=True) full_response = "" # Stream the response with honcho.apps.users.sessions.with_streaming_response.stream( app_id=app.id, user_id=user.id, session_id=session.id, queries="Based on this user's food preferences, recommend 3 restaurants they might enjoy in the Lower East Side." ) as response: for chunk in response.iter_text(): print(chunk, end="", flush=True) full_response += chunk await asyncio.sleep(0.01) # Store the assistant's complete response await honcho.apps.users.sessions.messages.create( app_id=app.id, user_id=user.id, session_id=session.id, content=full_response, is_user=False ) # Run the async function if __name__ == "__main__": asyncio.run(restaurant_recommendation_chat()) [​](https://docs.honcho.dev/v1/guides/streaming-response#performance-considerations) Performance Considerations ------------------------------------------------------------------------------------------------------------------ When implementing streaming: * Consider connection stability for mobile or unreliable networks * Implement appropriate timeouts for stream operations * Be mindful of memory usage when accumulating large responses * Use appropriate error handling for network interruptions Streaming responses provide a more interactive and engaging user experience. By implementing streaming in your Honcho applications, you can create more responsive AI-powered features that feel natural and immediate to your users. [Overview](https://docs.honcho.dev/v1/guides/overview) [Discord](https://docs.honcho.dev/v1/guides/discord) ⌘I --- # Quickstart - Honcho [Skip to main content](https://docs.honcho.dev/v1/getting-started/quickstart#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation Get Started Quickstart [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) To make things easy, there’s an instance of Honcho up and running on a demo server at [https://demo.honcho.dev](https://demo.honcho.dev/docs) . The python package defaults to this instance, so let’s dive into how to get up and running! Begin with the demo server, then seamlessly transition to the production environment once you receive an invite code—simply add your API key and everything should function immediately.Sign-up for an invite code [here](https://plasticlabs.typeform.com/honchoinvite) Install the Honcho client SDK with the following commands: Python NodeJS pip install honcho-ai First, import the `Client` from the package: Python NodeJS from honcho import Honcho honcho = Honcho( # This is the default and can be omitted api_key=os.environ.get("HONCHO_AUTH_TOKEN"), # defaults to "local". environment="demo", ) Next, we want to register an application with the Honcho client: Python NodeJS app = honcho.apps.get_or_create( name="string", ) This will create an application with the above name if it does not already exist or retrieve it if it does. After we have our application initialized, we can make a user with the following: Python NodeJS user = honcho.apps.users.create(app_id=app.id, name="User") Now let’s create a session for that application. Honcho is a user context management system, so you can create sessions for users. Thus, a `user_id` is required. Python NodeJS session = honcho.apps.users.sessions.create(user.id, app.id) Let’s add a user message and an AI message to that session: Python NodeJS honcho.apps.users.sessions.messages.create(session.id, app.id, user.id, content="Test", is_user=True) You can also easily query Honcho to get the session objects for that user with the following: Python NodeJS async for session in honcho.apps.users.list(app.id, user.id): doSomethingWith(session) This is a super simple overview of how to get up and running with the Honcho SDK. We covered the basic methods for reading and writing from the hosted storage service. Next, we’ll cover alternative forms of hosting Honcho. For a more detailed look at the SDK check out the SDK reference [here](https://docs.honcho.dev/v1/api-reference) . [Overview](https://docs.honcho.dev/v1/getting-started/introduction) [Architecture](https://docs.honcho.dev/v1/getting-started/architecture) ⌘I --- # Create App - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/apps/create-app#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation apps Create App [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const app = await client.apps.create({ name: 'x' }); console.log(app.id); } main(); 200 422 { "id": "", "name": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } POST http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const app = await client.apps.create({ name: 'x' }); console.log(app.id); } main(); 200 422 { "id": "", "name": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/create-app#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Body application/json App creation parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/create-app#body-name) name string required Required string length: `1 - 100` [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/create-app#body-metadata) metadata Metadata · object #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/create-app#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/create-app#response-name) name string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/create-app#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/create-app#response-metadata) metadata Metadata · object [Get App By Name](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-app-by-name) [Get Or Create App](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-or-create-app) ⌘I --- # License - Honcho [Skip to main content](https://docs.honcho.dev/v2/contributing/license#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Contributing License [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) Honcho is licensed under the AGPL-3.0 License. This is copied below for convenience and also present in the [GitHub Repository](https://github.com/plastic-labs/honcho) GNU AFFERO GENERAL PUBLIC LICENSE Version 3, 19 November 2007 Copyright (C) 2007 Free Software Foundation, Inc. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The GNU Affero General Public License is a free, copyleft license for software and other kinds of works, specifically designed to ensure cooperation with the community in the case of network server software. The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, our General Public Licenses are intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things. Developers that use our General Public Licenses protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License which gives you legal permission to copy, distribute and/or modify the software. A secondary benefit of defending all users' freedom is that improvements made in alternate versions of the program, if they receive widespread use, become available for other developers to incorporate. Many developers of free software are heartened and encouraged by the resulting cooperation. However, in the case of software used on network servers, this result may fail to come about. The GNU General Public License permits making a modified version and letting the public access it on a server without ever releasing its source code to the public. The GNU Affero General Public License is designed specifically to ensure that, in such cases, the modified source code becomes available to the community. It requires the operator of a network server to provide the source code of the modified version running there to the users of that server. Therefore, public use of a modified version, on a publicly accessible server, gives the public access to the source code of the modified version. An older license, called the Affero General Public License and published by Affero, was designed to accomplish similar goals. This is a different license, not a version of the Affero GPL, but Affero has released a new version of the Affero GPL which permits relicensing under this license. The precise terms and conditions for copying, distribution and modification follow. TERMS AND CONDITIONS 0. Definitions. "This License" refers to version 3 of the GNU Affero General Public License. "Copyright" also means copyright-like laws that apply to other kinds of works, such as semiconductor masks. "The Program" refers to any copyrightable work licensed under this License. Each licensee is addressed as "you". "Licensees" and "recipients" may be individuals or organizations. To "modify" a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a "modified version" of the earlier work or a work "based on" the earlier work. A "covered work" means either the unmodified Program or a work based on the Program. To "propagate" a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well. To "convey" a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying. An interactive user interface displays "Appropriate Legal Notices" to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion. 1. Source Code. The "source code" for a work means the preferred form of the work for making modifications to it. "Object code" means any non-source form of a work. A "Standard Interface" means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language. The "System Libraries" of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A "Major Component", in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it. The "Corresponding Source" for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work. The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source. The Corresponding Source for a work in source code form is that same work. 2. Basic Permissions. All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law. You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you. Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary. 3. Protecting Users' Legal Rights From Anti-Circumvention Law. No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures. When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures. 4. Conveying Verbatim Copies. You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program. You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee. 5. Conveying Modified Source Versions. You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions: a) The work must carry prominent notices stating that you modified it, and giving a relevant date. b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to "keep intact all notices". c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it. d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so. A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an "aggregate" if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate. 6. Conveying Non-Source Forms. You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways: a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange. b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge. c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b. d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements. e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d. A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work. A "User Product" is either (1) a "consumer product", which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, "normally used" refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product. "Installation Information" for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made. If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM). The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network. Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying. 7. Additional Terms. "Additional permissions" are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions. When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission. Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms: a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or d) Limiting the use for publicity purposes of names of licensors or authors of the material; or e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors. All other non-permissive additional terms are considered "further restrictions" within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying. If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms. Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way. 8. Termination. You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11). However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation. Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice. Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10. 9. Acceptance Not Required for Having Copies. You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so. 10. Automatic Licensing of Downstream Recipients. Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License. An "entity transaction" is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts. You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it. 11. Patents. A "contributor" is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's "contributor version". A contributor's "essential patent claims" are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, "control" includes the right to grant patent sublicenses in a manner consistent with the requirements of this License. Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version. In the following three paragraphs, a "patent license" is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To "grant" such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party. If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. "Knowingly relying" means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid. If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it. A patent license is "discriminatory" if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007. Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law. 12. No Surrender of Others' Freedom. If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program. 13. Remote Network Interaction; Use with the GNU General Public License. Notwithstanding any other provision of this License, if you modify the Program, your modified version must prominently offer all users interacting with it remotely through a computer network (if your version supports such interaction) an opportunity to receive the Corresponding Source of your version by providing access to the Corresponding Source from a network server at no charge, through some standard or customary means of facilitating copying of software. This Corresponding Source shall include the Corresponding Source for any work covered by version 3 of the GNU General Public License that is incorporated pursuant to the following paragraph. Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the work with which it is combined will remain governed by version 3 of the GNU General Public License. 14. Revised Versions of this License. The Free Software Foundation may publish revised and/or new versions of the GNU Affero General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU Affero General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU Affero General Public License, you may choose any version ever published by the Free Software Foundation. If the Program specifies that a proxy can decide which future versions of the GNU Affero General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program. Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version. 15. Disclaimer of Warranty. THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 16. Limitation of Liability. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 17. Interpretation of Sections 15 and 16. If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee. END OF TERMS AND CONDITIONS How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program. If not, see . Also add information on how to contact you by electronic and paper mail. If your software can interact with users remotely through a computer network, you should also make sure that it provides a way for users to get its source. For example, if your program is a web application, its interface could display a "Source" link that leads users to an archive of the code. There are many ways you could offer source, and different solutions will be better for different programs; see section 13 for the specific requirements. You should also get your employer (if you work as a programmer) or school, if any, to sign a "copyright disclaimer" for the program, if necessary. For more information on this, and how to apply and follow the GNU AGPL, see . [Configuration Guide](https://docs.honcho.dev/v2/contributing/configuration) ⌘I --- # Troubleshooting - Honcho [Skip to main content](https://docs.honcho.dev/v3/contributing/troubleshooting#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Self-Hosting Troubleshooting [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Startup Failures](https://docs.honcho.dev/v3/contributing/troubleshooting#startup-failures) * [Server won’t start: “Missing client for …”](https://docs.honcho.dev/v3/contributing/troubleshooting#server-won%E2%80%99t-start-%E2%80%9Cmissing-client-for-%E2%80%A6%E2%80%9D) * [Server won’t start: “JWT\_SECRET must be set”](https://docs.honcho.dev/v3/contributing/troubleshooting#server-won%E2%80%99t-start-%E2%80%9Cjwt_secret-must-be-set%E2%80%9D) * [Runtime Errors](https://docs.honcho.dev/v3/contributing/troubleshooting#runtime-errors) * [API returns “An unexpected error occurred” on every request](https://docs.honcho.dev/v3/contributing/troubleshooting#api-returns-%E2%80%9Can-unexpected-error-occurred%E2%80%9D-on-every-request) * [Health check passes but API calls fail](https://docs.honcho.dev/v3/contributing/troubleshooting#health-check-passes-but-api-calls-fail) * [Deriver not processing messages](https://docs.honcho.dev/v3/contributing/troubleshooting#deriver-not-processing-messages) * [Alternative Provider Issues](https://docs.honcho.dev/v3/contributing/troubleshooting#alternative-provider-issues) * [OpenRouter / custom provider not working](https://docs.honcho.dev/v3/contributing/troubleshooting#openrouter-%2F-custom-provider-not-working) * [vLLM / Ollama not responding](https://docs.honcho.dev/v3/contributing/troubleshooting#vllm-%2F-ollama-not-responding) * [Thinking budget errors with non-Anthropic providers](https://docs.honcho.dev/v3/contributing/troubleshooting#thinking-budget-errors-with-non-anthropic-providers) * [Database Issues](https://docs.honcho.dev/v3/contributing/troubleshooting#database-issues) * [Connection string format](https://docs.honcho.dev/v3/contributing/troubleshooting#connection-string-format) * [Checking migration status](https://docs.honcho.dev/v3/contributing/troubleshooting#checking-migration-status) * [Cache & Redis](https://docs.honcho.dev/v3/contributing/troubleshooting#cache-%26-redis) * [Redis is optional](https://docs.honcho.dev/v3/contributing/troubleshooting#redis-is-optional) * [Redis connection issues](https://docs.honcho.dev/v3/contributing/troubleshooting#redis-connection-issues) * [Docker Issues](https://docs.honcho.dev/v3/contributing/troubleshooting#docker-issues) * [Docker build fails with permission errors](https://docs.honcho.dev/v3/contributing/troubleshooting#docker-build-fails-with-permission-errors) * [Containers start but API fails](https://docs.honcho.dev/v3/contributing/troubleshooting#containers-start-but-api-fails) * [Port conflicts](https://docs.honcho.dev/v3/contributing/troubleshooting#port-conflicts) * [Rebuilding after code changes](https://docs.honcho.dev/v3/contributing/troubleshooting#rebuilding-after-code-changes) * [Getting Help](https://docs.honcho.dev/v3/contributing/troubleshooting#getting-help) This page covers common issues you may encounter when self-hosting Honcho, what causes them, and how to fix them. [​](https://docs.honcho.dev/v3/contributing/troubleshooting#startup-failures) Startup Failures ------------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v3/contributing/troubleshooting#server-won%E2%80%99t-start-%E2%80%9Cmissing-client-for-%E2%80%A6%E2%80%9D) Server won’t start: “Missing client for …” ValueError: Missing client for Deriver: google **Cause:** The server validates at startup that all configured LLM providers have API keys. If a provider is referenced in your configuration but the corresponding API key isn’t set, the server refuses to start. **Fix:** Set the API keys for your configured providers. With default configuration, you need: LLM_GEMINI_API_KEY=... # Used by deriver, summary, dialectic minimal/low LLM_ANTHROPIC_API_KEY=... # Used by dialectic medium/high/max, dream LLM_OPENAI_API_KEY=... # Used by embeddings (when EMBED_MESSAGES=true) See the [LLM Setup](https://docs.honcho.dev/v3/contributing/self-hosting#llm-setup) section for provider configuration. You can change which providers are used in your `.env` or `config.toml` (see [Configuration Guide](https://docs.honcho.dev/v3/contributing/configuration#llm-configuration) ). ### [​](https://docs.honcho.dev/v3/contributing/troubleshooting#server-won%E2%80%99t-start-%E2%80%9Cjwt_secret-must-be-set%E2%80%9D) Server won’t start: “JWT\_SECRET must be set” ValueError: JWT_SECRET must be set if USE_AUTH is true **Cause:** You enabled authentication (`AUTH_USE_AUTH=true`) but didn’t provide a JWT secret. **Fix:** Generate a secret and set it: python scripts/generate_jwt_secret.py # Then set the output as: AUTH_JWT_SECRET= Or disable authentication for local development: `AUTH_USE_AUTH=false` [​](https://docs.honcho.dev/v3/contributing/troubleshooting#runtime-errors) Runtime Errors --------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v3/contributing/troubleshooting#api-returns-%E2%80%9Can-unexpected-error-occurred%E2%80%9D-on-every-request) API returns “An unexpected error occurred” on every request **Cause:** This is almost always a database issue. The health endpoint (`/health`) will return `{"status": "ok"}` even when the database is unreachable because it doesn’t check the database connection. The actual error appears in the server logs. **Common causes and fixes:** 1. **Database is unreachable** — Check that PostgreSQL is running and the `DB_CONNECTION_URI` is correct 2. **Migrations haven’t been run** — The server starts successfully without tables, but every API call will fail. Run: uv run alembic upgrade head In Docker: docker compose exec api uv run alembic upgrade head 3. **pgvector extension not installed** — The `vector` extension must be enabled in your database: CREATE EXTENSION IF NOT EXISTS vector; **How to diagnose:** Check the server logs for the actual error. Look for: * `sqlalchemy.exc.OperationalError` — database connection issue * `sqlalchemy.exc.ProgrammingError` with “relation does not exist” — migrations not run * `psycopg.OperationalError` — connection refused or authentication failed ### [​](https://docs.honcho.dev/v3/contributing/troubleshooting#health-check-passes-but-api-calls-fail) Health check passes but API calls fail The `/health` endpoint is a lightweight check that confirms the server process is running. It does **not** verify: * Database connectivity * That migrations have been run * That LLM providers are reachable To verify full functionality, try creating a workspace: curl -X POST http://localhost:8000/v3/workspaces \ -H "Content-Type: application/json" \ -d '{"name": "test"}' If this succeeds, your database connection and migrations are working. ### [​](https://docs.honcho.dev/v3/contributing/troubleshooting#deriver-not-processing-messages) Deriver not processing messages Messages are stored but no observations, summaries, or representations are being generated. **Common causes:** 1. **Deriver isn’t running** — In manual setup, the deriver is a separate process: uv run python -m src.deriver In Docker, it starts automatically via `docker compose up`. 2. **Deriver can’t reach the database** — Check deriver logs for connection errors. The deriver uses the same `DB_CONNECTION_URI` as the API server. 3. **Missing LLM API key for deriver provider** — By default the deriver uses Google Gemini (`LLM_GEMINI_API_KEY`). Check deriver logs for API errors. 4. **Processing backlog** — With `DERIVER_WORKERS=1` (default), high message volume can cause a backlog. Increase workers: DERIVER_WORKERS=4 5. **Representation Batch Max** — By default the deriver is set to buffer its operations until there are enough tokens for a given representation in a session. This is set via the `REPRESENTATION_BATCH_MAX_TOKENS` environment variable. If you aren’t seeing tasks continue it may be that the batch size is set too high or enough data hasn’t flowed into to the session yet. See [token batching](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning#token-batching) for more details [​](https://docs.honcho.dev/v3/contributing/troubleshooting#alternative-provider-issues) Alternative Provider Issues ----------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v3/contributing/troubleshooting#openrouter-/-custom-provider-not-working) OpenRouter / custom provider not working If calls to an OpenAI-compatible proxy fail: 1. **Verify the endpoint and key are set.** Use `transport = "openai"` with a base URL override: LLM_OPENAI_API_KEY=sk-or-v1-... DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1 2. **Check model names match the provider’s format.** OpenRouter uses `vendor/model` format (e.g., `anthropic/claude-haiku-4-5`), not the raw model ID. 3. **Ensure your model supports tool calling.** The deriver, dialectic, and dream agents require tool use. Check the provider’s model page for tool calling support. 4. **Check server logs for the actual error.** API errors from the upstream provider will appear in Honcho’s logs with the HTTP status code and message body. ### [​](https://docs.honcho.dev/v3/contributing/troubleshooting#vllm-/-ollama-not-responding) vLLM / Ollama not responding 1. **Verify the model server is running** and accessible from the Honcho process (or container): curl http://localhost:8000/v1/models # vLLM curl http://localhost:11434/v1/models # Ollama 2. **In Docker**, `localhost` inside a container doesn’t reach the host. Use `host.docker.internal` (macOS/Windows) or the host’s network IP: DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL=http://host.docker.internal:8000/v1 3. **Structured output failures** — vLLM’s structured output support is limited to certain response formats. If you see JSON parsing errors, check the deriver/dream logs for the raw response. ### [​](https://docs.honcho.dev/v3/contributing/troubleshooting#thinking-budget-errors-with-non-anthropic-providers) Thinking budget errors with non-Anthropic providers If you see errors like `thinking budget not supported`, `invalid parameter`, or silent failures where agents produce no output, one of your per-component `*_MODEL_CONFIG__THINKING_BUDGET_TOKENS` overrides is likely set to a value > 0 with a provider that doesn’t support Anthropic-style extended thinking. The built-in defaults do not set thinking budgets, so this only applies if you added those overrides yourself. **Fix:** Set `*_MODEL_CONFIG__THINKING_BUDGET_TOKENS=0` for every component when using models that don’t support thinking: DERIVER_MODEL_CONFIG__THINKING_BUDGET_TOKENS=0 SUMMARY_MODEL_CONFIG__THINKING_BUDGET_TOKENS=0 DREAM_DEDUCTION_MODEL_CONFIG__THINKING_BUDGET_TOKENS=0 DREAM_INDUCTION_MODEL_CONFIG__THINKING_BUDGET_TOKENS=0 DIALECTIC_LEVELS__minimal__MODEL_CONFIG__THINKING_BUDGET_TOKENS=0 DIALECTIC_LEVELS__low__MODEL_CONFIG__THINKING_BUDGET_TOKENS=0 DIALECTIC_LEVELS__medium__MODEL_CONFIG__THINKING_BUDGET_TOKENS=0 DIALECTIC_LEVELS__high__MODEL_CONFIG__THINKING_BUDGET_TOKENS=0 DIALECTIC_LEVELS__max__MODEL_CONFIG__THINKING_BUDGET_TOKENS=0 For OpenAI reasoning models, use `*_MODEL_CONFIG__THINKING_EFFORT` instead of `*_MODEL_CONFIG__THINKING_BUDGET_TOKENS`. [​](https://docs.honcho.dev/v3/contributing/troubleshooting#database-issues) Database Issues ----------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v3/contributing/troubleshooting#connection-string-format) Connection string format The connection URI **must** use the `postgresql+psycopg` prefix: # Correct DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@localhost:5432/postgres # Wrong - will fail DB_CONNECTION_URI=postgresql://postgres:postgres@localhost:5432/postgres DB_CONNECTION_URI=postgres://postgres:postgres@localhost:5432/postgres ### [​](https://docs.honcho.dev/v3/contributing/troubleshooting#checking-migration-status) Checking migration status # See current migration version uv run alembic current # See migration history uv run alembic history # Upgrade to latest uv run alembic upgrade head [​](https://docs.honcho.dev/v3/contributing/troubleshooting#cache-&-redis) Cache & Redis ------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v3/contributing/troubleshooting#redis-is-optional) Redis is optional Redis is used for caching when `CACHE_ENABLED=true` (default: `false`). If Redis is unreachable, Honcho **gracefully falls back to in-memory caching** and logs a warning. This means: * The server and deriver will still start and function normally * Performance may be reduced under high load without Redis * You do not need Redis for local development or testing ### [​](https://docs.honcho.dev/v3/contributing/troubleshooting#redis-connection-issues) Redis connection issues If you see Redis connection warnings in logs but `CACHE_ENABLED=false`, they can be safely ignored. If you want caching: # Start Redis via Docker docker run -d -p 6379:6379 redis:latest # Configure Honcho CACHE_ENABLED=true CACHE_URL=redis://localhost:6379/0 [​](https://docs.honcho.dev/v3/contributing/troubleshooting#docker-issues) Docker Issues ------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v3/contributing/troubleshooting#docker-build-fails-with-permission-errors) Docker build fails with permission errors The Honcho Dockerfile uses BuildKit mount syntax and creates a non-root `app` user. Common build failures: **1\. BuildKit not enabled** The Dockerfile uses `RUN --mount=type=cache` which requires Docker BuildKit. If you see syntax errors during build: # Ensure BuildKit is enabled DOCKER_BUILDKIT=1 docker compose build Or add to your Docker daemon config (`/etc/docker/daemon.json`): { "features": { "buildkit": true } } **2\. Permission denied during build or at runtime (Linux)** On Linux, AppArmor or SELinux can block Docker build operations and volume mounts. Symptoms include permission denied errors during `COPY`, `RUN`, or when the container tries to access mounted volumes. # Check if AppArmor is blocking Docker sudo aa-status | grep docker # Temporarily test without AppArmor (for diagnosis only) docker compose down sudo aa-remove-unknown docker compose up -d For SELinux, add `:z` to volume mounts in `docker-compose.yml`: volumes: - .:/app:z **3\. Volume mount UID mismatch** The Dockerfile creates a non-root `app` user, but `docker-compose.yml.example` mounts `.:/app` which overlays the container filesystem with host-owned files. The `app` user inside the container may not have permission to read them. If you see permission errors at runtime (not build time), you can either: * Run without the source mount (remove `- .:/app` from volumes — the image already contains the code) * Or fix ownership: `sudo chown -R 100:101 .` (matches the `app` user inside the container) ### [​](https://docs.honcho.dev/v3/contributing/troubleshooting#containers-start-but-api-fails) Containers start but API fails 1. Check container status: `docker compose ps` 2. Check API logs: `docker compose logs api` 3. Check database logs: `docker compose logs database` 4. Ensure migrations ran: `docker compose exec api uv run alembic upgrade head` ### [​](https://docs.honcho.dev/v3/contributing/troubleshooting#port-conflicts) Port conflicts If port 8000 is already in use: # Check what's using the port lsof -i :8000 # Or change the port mapping in docker-compose.yml ports: - "8001:8000" # Map to a different host port ### [​](https://docs.honcho.dev/v3/contributing/troubleshooting#rebuilding-after-code-changes) Rebuilding after code changes docker compose build --no-cache docker compose up -d [​](https://docs.honcho.dev/v3/contributing/troubleshooting#getting-help) Getting Help ----------------------------------------------------------------------------------------- If your issue isn’t covered here: * **Check the logs** — most issues are diagnosed from server or deriver logs * **GitHub Issues** — [Report bugs](https://github.com/plastic-labs/honcho/issues) * **Discord** — [Join our community](https://discord.gg/plasticlabs) * **Configuration** — See the [Configuration Guide](https://docs.honcho.dev/v3/contributing/configuration) for all available settings [Configuration Guide](https://docs.honcho.dev/v3/contributing/configuration) [Contributing Guidelines](https://docs.honcho.dev/v3/contributing/guidelines) ⌘I --- # Discord Bots with Honcho - Honcho [Skip to main content](https://docs.honcho.dev/v2/guides/discord#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Application Interfaces Discord Bots with Honcho [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [Events](https://docs.honcho.dev/v2/guides/discord#events) * [Helper Functions](https://docs.honcho.dev/v2/guides/discord#helper-functions) * [Message Validation](https://docs.honcho.dev/v2/guides/discord#message-validation) * [Message Sanitization](https://docs.honcho.dev/v2/guides/discord#message-sanitization) * [Peer ID Generation](https://docs.honcho.dev/v2/guides/discord#peer-id-generation) * [LLM Integration](https://docs.honcho.dev/v2/guides/discord#llm-integration) * [Message Sending](https://docs.honcho.dev/v2/guides/discord#message-sending) * [Honcho Integration](https://docs.honcho.dev/v2/guides/discord#honcho-integration) * [Slash Commands](https://docs.honcho.dev/v2/guides/discord#slash-commands) * [Setup and Configuration](https://docs.honcho.dev/v2/guides/discord#setup-and-configuration) * [Recap](https://docs.honcho.dev/v2/guides/discord#recap) > Example code is available on [GitHub](https://github.com/plastic-labs/discord-python-starter) Any application interface that defines logic based on events and supports special commands can work easily with Honcho. Here’s how to use Honcho with **Discord** as an interface. If you’re not familiar with Discord bot application logic, the [py-cord](https://pycord.dev/) docs would be a good place to start. [​](https://docs.honcho.dev/v2/guides/discord#events) Events --------------------------------------------------------------- Most Discord bots have async functions that listen for specific events, the most common one being messages. We can use Honcho to store messages by user and session based on an interface’s event logic. Take the following function definition for example: @bot.event async def on_message(message): """ Receive a message from Discord and respond with a message from our LLM assistant. """ if not validate_message(message): return input = sanitize_message(message) # If the message is empty after sanitizing, ignore it if not input: return peer = honcho_client.peer(id=get_peer_id_from_discord(message)) session = honcho_client.session(id=str(message.channel.id)) async with message.channel.typing(): response = llm(session, input) await send_discord_message(message, response) # Save both the user's message and the bot's response to the session session.add_messages( [\ peer.message(input),\ assistant.message(response),\ ] ) Let’s break down what this code is doing… @bot.event async def on_message(message): if not validate_message(message): return This is how you define an event function in `py-cord` that listens for messages. We use a helper function `validate_message()` to check if the message should be processed. [​](https://docs.honcho.dev/v2/guides/discord#helper-functions) Helper Functions ----------------------------------------------------------------------------------- The code uses several helper functions to keep the main logic clean and readable. Let’s examine each one: ### [​](https://docs.honcho.dev/v2/guides/discord#message-validation) Message Validation def validate_message(message) -> bool: """ Determine if the message is valid for the bot to respond to. Return True if it is, False otherwise. Currently, the bot will only respond to messages that tag it with an @mention in a public channel and are not from the bot itself. """ if message.author == bot.user: # ensure the bot does not reply to itself return False if isinstance(message.channel, discord.DMChannel): return False if not bot.user.mentioned_in(message): return False return True This function centralizes all the logic for determining whether the bot should respond to a message. It checks that: * The message isn’t from the bot itself * The message isn’t in a DM channel * The bot is mentioned in the message ### [​](https://docs.honcho.dev/v2/guides/discord#message-sanitization) Message Sanitization def sanitize_message(message) -> str | None: """Remove the bot's mention from the message content if present""" content = message.content.replace(f"<@{bot.user.id}>", "").strip() if not content: return None return content This helper removes the bot’s mention from the message content, leaving just the actual user input. ### [​](https://docs.honcho.dev/v2/guides/discord#peer-id-generation) Peer ID Generation def get_peer_id_from_discord(message): """Get a Honcho peer ID for the message author""" return f"discord_{str(message.author.id)}" This creates a unique peer identifier for each Discord user by prefixing their Discord ID. ### [​](https://docs.honcho.dev/v2/guides/discord#llm-integration) LLM Integration def llm(session, prompt) -> str: """ Call the LLM with the given prompt and chat history. You should expand this function with custom logic, prompts, etc. """ messages: list[dict[str, object]] = session.get_context().to_openai( assistant=assistant ) messages.append({"role": "user", "content": prompt}) try: completion = openai.chat.completions.create( model=MODEL_NAME, messages=messages, ) return completion.choices[0].message.content except Exception as e: print(e) return f"Error: {e}" This function handles the LLM interaction. It uses Honcho’s built-in `to_openai()` method to automatically convert the session context into the format expected by OpenAI’s chat completions API. ### [​](https://docs.honcho.dev/v2/guides/discord#message-sending) Message Sending async def send_discord_message(message, response_content: str): """Send a message to the Discord channel""" if len(response_content) > 1500: # Split response into chunks at newlines, keeping under 1500 chars chunks = [] current_chunk = "" for line in response_content.splitlines(keepends=True): if len(current_chunk) + len(line) > 1500: chunks.append(current_chunk) current_chunk = line else: current_chunk += line if current_chunk: chunks.append(current_chunk) for chunk in chunks: await message.channel.send(chunk) else: await message.channel.send(response_content) This function handles sending messages to Discord, automatically splitting long responses into multiple messages to stay within Discord’s character limits. [​](https://docs.honcho.dev/v2/guides/discord#honcho-integration) Honcho Integration --------------------------------------------------------------------------------------- The new Honcho peer/session API makes integration much simpler: peer = honcho_client.peer(id=get_peer_id_from_discord(message)) session = honcho_client.session(id=str(message.channel.id)) Here we create a peer object for the user and a session object using the Discord channel ID. This automatically handles user and session management. # Save both the user's message and the bot's response to the session session.add_messages( [\ peer.message(input),\ assistant.message(response),\ ] ) After generating the response, we save both the user’s input and the bot’s response to the session using the `add_messages()` method. The `peer.message()` creates a message from the user, while `assistant.message()` creates a message from the assistant. [​](https://docs.honcho.dev/v2/guides/discord#slash-commands) Slash Commands ------------------------------------------------------------------------------- Discord bots also offer slash command functionality. Here’s an example using Honcho’s dialectic feature: @bot.slash_command( name="dialectic", description="Query the Honcho Dialectic endpoint.", ) async def dialectic(ctx, query: str): await ctx.defer() try: peer = honcho_client.peer(id=get_peer_id_from_discord(ctx)) session = honcho_client.session(id=str(ctx.channel.id)) response = peer.chat( query=query, session_id=session.id, ) if response: await ctx.followup.send(response) else: await ctx.followup.send( f"I don't know anything about {ctx.author.name} because we haven't talked yet!" ) except Exception as e: logger.error(f"Error calling Dialectic API: {e}") await ctx.followup.send( f"Sorry, there was an error processing your request: {str(e)}" ) This slash command uses Honcho’s dialectic functionality to answer questions about the user based on their conversation history. [​](https://docs.honcho.dev/v2/guides/discord#setup-and-configuration) Setup and Configuration ------------------------------------------------------------------------------------------------- The bot requires several environment variables and setup: honcho_client = Honcho() assistant = honcho_client.peer(id="assistant", config={"observe_me": False}) openai = OpenAI(base_url="https://openrouter.ai/api/v1", api_key=MODEL_API_KEY) * `honcho_client`: The main Honcho client * `assistant`: A peer representing the bot/assistant * `openai`: OpenAI client configured to use OpenRouter [​](https://docs.honcho.dev/v2/guides/discord#recap) Recap ------------------------------------------------------------- The new Honcho peer/session API makes Discord bot integration much simpler and more intuitive. Key patterns we learned: * **Peer/Session Model**: Users are represented as peers, conversations as sessions * **Automatic Context Management**: `session.get_context().to_openai()` automatically formats chat history * **Message Storage**: `session.add_messages()` stores both user and assistant messages * **Dialectic Queries**: `peer.chat()` enables querying conversation history * **Helper Functions**: Clean code organization with focused helper functions This approach provides a clean, maintainable structure for building Discord bots with conversational memory and context management. [MCP](https://docs.honcho.dev/v2/integrations/mcp) [n8n](https://docs.honcho.dev/v2/guides/n8n) ⌘I --- # Local Environment Setup - Honcho [Skip to main content](https://docs.honcho.dev/v2/contributing/self-hosting#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Contributing Local Environment Setup [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [Overview](https://docs.honcho.dev/v2/contributing/self-hosting#overview) * [Prerequisites](https://docs.honcho.dev/v2/contributing/self-hosting#prerequisites) * [Required Software](https://docs.honcho.dev/v2/contributing/self-hosting#required-software) * [Database Options](https://docs.honcho.dev/v2/contributing/self-hosting#database-options) * [Docker Setup (Recommended)](https://docs.honcho.dev/v2/contributing/self-hosting#docker-setup-recommended) * [1\. Clone the Repository](https://docs.honcho.dev/v2/contributing/self-hosting#1-clone-the-repository) * [2\. Set Up Environment Variables](https://docs.honcho.dev/v2/contributing/self-hosting#2-set-up-environment-variables) * [3\. Start the Services](https://docs.honcho.dev/v2/contributing/self-hosting#3-start-the-services) * [4\. Verify It’s Working](https://docs.honcho.dev/v2/contributing/self-hosting#4-verify-it%E2%80%99s-working) * [Manual Setup](https://docs.honcho.dev/v2/contributing/self-hosting#manual-setup) * [1\. Clone and Install Dependencies](https://docs.honcho.dev/v2/contributing/self-hosting#1-clone-and-install-dependencies) * [2\. Set Up PostgreSQL](https://docs.honcho.dev/v2/contributing/self-hosting#2-set-up-postgresql) * [Option A: Local PostgreSQL Installation](https://docs.honcho.dev/v2/contributing/self-hosting#option-a-local-postgresql-installation) * [Option B: Docker PostgreSQL](https://docs.honcho.dev/v2/contributing/self-hosting#option-b-docker-postgresql) * [3\. Enable Extensions](https://docs.honcho.dev/v2/contributing/self-hosting#3-enable-extensions) * [4\. Configure Environment](https://docs.honcho.dev/v2/contributing/self-hosting#4-configure-environment) * [5\. Run Database Migrations](https://docs.honcho.dev/v2/contributing/self-hosting#5-run-database-migrations) * [6\. Start the Server](https://docs.honcho.dev/v2/contributing/self-hosting#6-start-the-server) * [Cloud Database Setup](https://docs.honcho.dev/v2/contributing/self-hosting#cloud-database-setup) * [Supabase (Recommended)](https://docs.honcho.dev/v2/contributing/self-hosting#supabase-recommended) * [Railway](https://docs.honcho.dev/v2/contributing/self-hosting#railway) * [Verify Your Setup](https://docs.honcho.dev/v2/contributing/self-hosting#verify-your-setup) * [1\. Health Check](https://docs.honcho.dev/v2/contributing/self-hosting#1-health-check) * [2\. API Documentation](https://docs.honcho.dev/v2/contributing/self-hosting#2-api-documentation) * [3\. Test with SDK](https://docs.honcho.dev/v2/contributing/self-hosting#3-test-with-sdk) * [Connect Your Application](https://docs.honcho.dev/v2/contributing/self-hosting#connect-your-application) * [Update SDK Configuration](https://docs.honcho.dev/v2/contributing/self-hosting#update-sdk-configuration) * [Next Steps](https://docs.honcho.dev/v2/contributing/self-hosting#next-steps) * [Troubleshooting](https://docs.honcho.dev/v2/contributing/self-hosting#troubleshooting) * [Common Issues](https://docs.honcho.dev/v2/contributing/self-hosting#common-issues) * [Getting Help](https://docs.honcho.dev/v2/contributing/self-hosting#getting-help) * [Production Considerations](https://docs.honcho.dev/v2/contributing/self-hosting#production-considerations) This guide helps you set up a local environment to run Honcho for development, testing, or self-hosting. [​](https://docs.honcho.dev/v2/contributing/self-hosting#overview) Overview ------------------------------------------------------------------------------ By the end of this guide, you’ll have: * A local Honcho server running on your machine * A PostgreSQL database with pgvector extension * Basic configuration to connect your applications * A working environment for development or testing [​](https://docs.honcho.dev/v2/contributing/self-hosting#prerequisites) Prerequisites ---------------------------------------------------------------------------------------- Before you begin, ensure you have the following installed: ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#required-software) Required Software * **uv** - Python package manager: `pip install uv` (manages Python installations automatically) * **Git** - [Download from git-scm.com](https://git-scm.com/downloads) * **Docker** (optional) - [Download from docker.com](https://www.docker.com/products/docker-desktop/) ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#database-options) Database Options You’ll need a PostgreSQL database with the pgvector extension. Choose one: * **Local PostgreSQL** - Install locally or use Docker * **Supabase** - Free cloud PostgreSQL with pgvector * **Railway** - Simple cloud PostgreSQL hosting * **Your own PostgreSQL server** [​](https://docs.honcho.dev/v2/contributing/self-hosting#docker-setup-recommended) Docker Setup (Recommended) ---------------------------------------------------------------------------------------------------------------- The easiest way to get started is using Docker Compose, which handles both the database and Honcho server. ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#1-clone-the-repository) 1\. Clone the Repository git clone https://github.com/plastic-labs/honcho.git cd honcho ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#2-set-up-environment-variables) 2\. Set Up Environment Variables Copy the example environment file and configure it: cp .env.template .env Edit `.env` and set your API keys (if using LLM features): # Optional API keys (required for LLM features) OPENAI_API_KEY=your-openai-api-key ANTHROPIC_API_KEY=your-anthropic-api-key # Database will be created automatically by Docker DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@database:5432/postgres # Disable auth for local development AUTH_USE_AUTH=false ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#3-start-the-services) 3\. Start the Services # Copy the example docker-compose file cp docker-compose.yml.example docker-compose.yml # Start PostgreSQL and Honcho docker compose up -d ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#4-verify-it%E2%80%99s-working) 4\. Verify It’s Working Check that both services are running: docker compose ps Test the Honcho API: curl http://localhost:8000/health You should see a response indicating the service is healthy. [​](https://docs.honcho.dev/v2/contributing/self-hosting#manual-setup) Manual Setup -------------------------------------------------------------------------------------- For more control over your environment, you can set up everything manually. ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#1-clone-and-install-dependencies) 1\. Clone and Install Dependencies git clone https://github.com/plastic-labs/honcho.git cd honcho # Install dependencies using uv (this will also set up Python if needed) uv sync # Activate the virtual environment source .venv/bin/activate # On Windows: .venv\Scripts\activate ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#2-set-up-postgresql) 2\. Set Up PostgreSQL #### [​](https://docs.honcho.dev/v2/contributing/self-hosting#option-a-local-postgresql-installation) Option A: Local PostgreSQL Installation Install PostgreSQL and pgvector on your system: **macOS (using Homebrew):** brew install postgresql brew install pgvector **Ubuntu/Debian:** sudo apt update sudo apt install postgresql postgresql-contrib # Install pgvector extension (see pgvector docs for your version) **Windows:** Download from [postgresql.org](https://www.postgresql.org/download/windows/) #### [​](https://docs.honcho.dev/v2/contributing/self-hosting#option-b-docker-postgresql) Option B: Docker PostgreSQL docker run --name honcho-db \ -e POSTGRES_USER=postgres \ -e POSTGRES_PASSWORD=postgres \ -p 5432:5432 \ -d pgvector/pgvector:pg15 ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#3-enable-extensions) 3\. Enable Extensions Connect to PostgreSQL and enable pgvector: # Connect to PostgreSQL psql -U postgres # Enable extensions on the default database CREATE EXTENSION IF NOT EXISTS vector; CREATE EXTENSION IF NOT EXISTS pg_trgm; \q ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#4-configure-environment) 4\. Configure Environment Create a `.env` file with your settings: cp .env.template .env Edit `.env` with your configuration: # Database connection DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@localhost:5432/postgres # Optional API keys (required for LLM features) OPENAI_API_KEY=your-openai-api-key ANTHROPIC_API_KEY=your-anthropic-api-key # Development settings AUTH_USE_AUTH=false LOG_LEVEL=DEBUG ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#5-run-database-migrations) 5\. Run Database Migrations # Run migrations to create tables uv run alembic upgrade head ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#6-start-the-server) 6\. Start the Server # Start the development server fastapi dev src/main.py The server will be available at `http://localhost:8000`. [​](https://docs.honcho.dev/v2/contributing/self-hosting#cloud-database-setup) Cloud Database Setup ------------------------------------------------------------------------------------------------------ If you prefer to use a managed PostgreSQL service: ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#supabase-recommended) Supabase (Recommended) 1. **Create a Supabase project** at [supabase.com](https://supabase.com/) 2. **Enable pgvector extension** in the SQL editor: CREATE EXTENSION IF NOT EXISTS vector; CREATE EXTENSION IF NOT EXISTS pg_trgm; 3. **Get your connection string** from Settings > Database 4. **Update your `.env` file** with the connection string ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#railway) Railway 1. **Create a Railway project** at [railway.app](https://railway.app/) 2. **Add a PostgreSQL service** 3. **Enable pgvector** in the PostgreSQL console 4. **Get your connection string** from the service variables 5. **Update your `.env` file** [​](https://docs.honcho.dev/v2/contributing/self-hosting#verify-your-setup) Verify Your Setup ------------------------------------------------------------------------------------------------ Once your Honcho server is running, verify everything is working: ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#1-health-check) 1\. Health Check curl http://localhost:8000/health ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#2-api-documentation) 2\. API Documentation Visit `http://localhost:8000/docs` to see the interactive API documentation. ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#3-test-with-sdk) 3\. Test with SDK Create a simple test script: from honcho import Honcho # Connect to your local instance client = Honcho(base_url="http://localhost:8000") # Create a test peer peer = client.peer("test-user") print(f"Created peer: {peer.id}") [​](https://docs.honcho.dev/v2/contributing/self-hosting#connect-your-application) Connect Your Application -------------------------------------------------------------------------------------------------------------- Now that Honcho is running locally, you can connect your applications: ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#update-sdk-configuration) Update SDK Configuration # Python SDK from honcho import Honcho client = Honcho( base_url="http://localhost:8000", # Your local instance api_key="your-api-key" # If auth is enabled ) // TypeScript SDK import { Honcho } from '@honcho-ai/sdk'; const client = new Honcho({ baseUrl: 'http://localhost:8000', // Your local instance apiKey: 'your-api-key' // If auth is enabled }); ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#next-steps) Next Steps * **Explore the API**: Check out the [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) * **Try the SDKs**: See our [guides](https://docs.honcho.dev/v2/guides) for examples * **Configure Honcho**: Visit the [Configuration Guide](https://docs.honcho.dev/v2/contributing/configuration) for detailed settings * **Join the community**: [Discord](https://discord.gg/honcho) [​](https://docs.honcho.dev/v2/contributing/self-hosting#troubleshooting) Troubleshooting -------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#common-issues) Common Issues **Database Connection Errors** * Ensure PostgreSQL is running * Verify the connection string format: `postgresql+psycopg://...` * Check that pgvector extension is installed **API Key Issues** * Verify your OpenAI and Anthropic API keys are valid * Check that the keys have sufficient credits/quota **Port Already in Use** * Pass a different port to FastAPI or stop other services using port 8000 **Docker Issues** * Ensure Docker is running * Check container logs: `docker compose logs` * Restart containers: `docker compose down && docker compose up -d` **Migration Errors** * Ensure the database exists and pgvector is enabled * Check database permissions * Run migrations manually: `uv run alembic upgrade head` ### [​](https://docs.honcho.dev/v2/contributing/self-hosting#getting-help) Getting Help * **GitHub Issues**: [Report bugs](https://github.com/plastic-labs/honcho/issues) * **Discord**: [Join our community](https://discord.gg/honcho) * **Documentation**: Check the [Configuration Guide](https://docs.honcho.dev/v2/contributing/configuration) for detailed settings [​](https://docs.honcho.dev/v2/contributing/self-hosting#production-considerations) Production Considerations ---------------------------------------------------------------------------------------------------------------- When self-hosting for production, consider: * **Security**: Enable authentication, use HTTPS, secure your database * **Scaling**: Use connection pooling, consider load balancing * **Monitoring**: Set up logging, error tracking, health checks * **Backups**: Regular database backups, disaster recovery plan * **Updates**: Keep Honcho and dependencies updated [Contributing Guidelines](https://docs.honcho.dev/v2/contributing/guidelines) [Configuration Guide](https://docs.honcho.dev/v2/contributing/configuration) ⌘I --- # License - Honcho [Skip to main content](https://docs.honcho.dev/v3/contributing/license#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Contributing License [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) Honcho is licensed under the AGPL-3.0 License. This is copied below for convenience and also present in the [GitHub Repository](https://github.com/plastic-labs/honcho) GNU AFFERO GENERAL PUBLIC LICENSE Version 3, 19 November 2007 Copyright (C) 2007 Free Software Foundation, Inc. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The GNU Affero General Public License is a free, copyleft license for software and other kinds of works, specifically designed to ensure cooperation with the community in the case of network server software. The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, our General Public Licenses are intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things. Developers that use our General Public Licenses protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License which gives you legal permission to copy, distribute and/or modify the software. A secondary benefit of defending all users' freedom is that improvements made in alternate versions of the program, if they receive widespread use, become available for other developers to incorporate. Many developers of free software are heartened and encouraged by the resulting cooperation. However, in the case of software used on network servers, this result may fail to come about. The GNU General Public License permits making a modified version and letting the public access it on a server without ever releasing its source code to the public. The GNU Affero General Public License is designed specifically to ensure that, in such cases, the modified source code becomes available to the community. It requires the operator of a network server to provide the source code of the modified version running there to the users of that server. Therefore, public use of a modified version, on a publicly accessible server, gives the public access to the source code of the modified version. An older license, called the Affero General Public License and published by Affero, was designed to accomplish similar goals. This is a different license, not a version of the Affero GPL, but Affero has released a new version of the Affero GPL which permits relicensing under this license. The precise terms and conditions for copying, distribution and modification follow. TERMS AND CONDITIONS 0. Definitions. "This License" refers to version 3 of the GNU Affero General Public License. "Copyright" also means copyright-like laws that apply to other kinds of works, such as semiconductor masks. "The Program" refers to any copyrightable work licensed under this License. Each licensee is addressed as "you". "Licensees" and "recipients" may be individuals or organizations. To "modify" a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a "modified version" of the earlier work or a work "based on" the earlier work. A "covered work" means either the unmodified Program or a work based on the Program. To "propagate" a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well. To "convey" a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying. An interactive user interface displays "Appropriate Legal Notices" to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion. 1. Source Code. The "source code" for a work means the preferred form of the work for making modifications to it. "Object code" means any non-source form of a work. A "Standard Interface" means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language. The "System Libraries" of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A "Major Component", in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it. The "Corresponding Source" for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work. The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source. The Corresponding Source for a work in source code form is that same work. 2. Basic Permissions. All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law. You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you. Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary. 3. Protecting Users' Legal Rights From Anti-Circumvention Law. No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures. When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures. 4. Conveying Verbatim Copies. You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program. You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee. 5. Conveying Modified Source Versions. You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions: a) The work must carry prominent notices stating that you modified it, and giving a relevant date. b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to "keep intact all notices". c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it. d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so. A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an "aggregate" if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate. 6. Conveying Non-Source Forms. You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways: a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange. b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge. c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b. d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements. e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d. A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work. A "User Product" is either (1) a "consumer product", which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, "normally used" refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product. "Installation Information" for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made. If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM). The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network. Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying. 7. Additional Terms. "Additional permissions" are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions. When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission. Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms: a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or d) Limiting the use for publicity purposes of names of licensors or authors of the material; or e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors. All other non-permissive additional terms are considered "further restrictions" within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying. If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms. Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way. 8. Termination. You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11). However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation. Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice. Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10. 9. Acceptance Not Required for Having Copies. You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so. 10. Automatic Licensing of Downstream Recipients. Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License. An "entity transaction" is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts. You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it. 11. Patents. A "contributor" is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's "contributor version". A contributor's "essential patent claims" are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, "control" includes the right to grant patent sublicenses in a manner consistent with the requirements of this License. Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version. In the following three paragraphs, a "patent license" is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To "grant" such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party. If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. "Knowingly relying" means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid. If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it. A patent license is "discriminatory" if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007. Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law. 12. No Surrender of Others' Freedom. If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program. 13. Remote Network Interaction; Use with the GNU General Public License. Notwithstanding any other provision of this License, if you modify the Program, your modified version must prominently offer all users interacting with it remotely through a computer network (if your version supports such interaction) an opportunity to receive the Corresponding Source of your version by providing access to the Corresponding Source from a network server at no charge, through some standard or customary means of facilitating copying of software. This Corresponding Source shall include the Corresponding Source for any work covered by version 3 of the GNU General Public License that is incorporated pursuant to the following paragraph. Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the work with which it is combined will remain governed by version 3 of the GNU General Public License. 14. Revised Versions of this License. The Free Software Foundation may publish revised and/or new versions of the GNU Affero General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU Affero General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU Affero General Public License, you may choose any version ever published by the Free Software Foundation. If the Program specifies that a proxy can decide which future versions of the GNU Affero General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program. Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version. 15. Disclaimer of Warranty. THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 16. Limitation of Liability. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 17. Interpretation of Sections 15 and 16. If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee. END OF TERMS AND CONDITIONS How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program. If not, see . Also add information on how to contact you by electronic and paper mail. If your software can interact with users remotely through a computer network, you should also make sure that it provides a way for users to get its source. For example, if your program is a web application, its interface could display a "Source" link that leads users to an archive of the code. There are many ways you could offer source, and different solutions will be better for different programs; see section 13 for the specific requirements. You should also get your employer (if you work as a programmer) or school, if any, to sign a "copyright disclaimer" for the program, if necessary. For more information on this, and how to apply and follow the GNU AGPL, see . [Contributing Guidelines](https://docs.honcho.dev/v3/contributing/guidelines) ⌘I --- # CrewAI - Honcho [Skip to main content](https://docs.honcho.dev/v2/integrations/crewai#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Integrations CrewAI [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [What We’re Building](https://docs.honcho.dev/v2/integrations/crewai#what-we%E2%80%99re-building) * [Setup](https://docs.honcho.dev/v2/integrations/crewai#setup) * [CrewAI Honcho Storage](https://docs.honcho.dev/v2/integrations/crewai#crewai-honcho-storage) * [Search with Filters](https://docs.honcho.dev/v2/integrations/crewai#search-with-filters) * [CrewAI Tool Integration](https://docs.honcho.dev/v2/integrations/crewai#crewai-tool-integration) * [Tool-Based vs Automatic Memory](https://docs.honcho.dev/v2/integrations/crewai#tool-based-vs-automatic-memory) * [Next Steps](https://docs.honcho.dev/v2/integrations/crewai#next-steps) * [Related Resources](https://docs.honcho.dev/v2/integrations/crewai#related-resources) Integrate Honcho with CrewAI to build AI agents that maintain memory across sessions. This guide shows you how to use Honcho’s memory layer with CrewAI’s agent orchestration framework. The full code is available on [GitHub](https://github.com/plastic-labs/honcho/tree/main/examples/crewai) with examples in [Python](https://github.com/plastic-labs/honcho/tree/main/examples/crewai/python/examples) [​](https://docs.honcho.dev/v2/integrations/crewai#what-we%E2%80%99re-building) What We’re Building ------------------------------------------------------------------------------------------------------ We’ll create AI agents that remember and reason over past conversations. Here’s how the pieces fit together: * **CrewAI** orchestrates agent behavior and task execution * **Honcho** stores messages and retrieves relevant context The key benefit: CrewAI automatically retrieves relevant conversation history from Honcho without you needing to manually manage context, token limits, or message formatting. This tutorial demonstrates single-agent setup to show how Honcho integrates with CrewAI. For production applications, you can extend this to multi-agent crews with shared or individual memory using Honcho’s `peer` system. [​](https://docs.honcho.dev/v2/integrations/crewai#setup) Setup ------------------------------------------------------------------ Install required packages: Python (uv) Python (pip) uv add honcho-crewai crewai python-dotenv Use any LLM provider for your Crew. Create a `.env` file with your API keys: OPENAI_API_KEY=your_openai_key This tutorial uses the Honcho demo server at [https://demo.honcho.dev](https://demo.honcho.dev/) which runs a small instance of Honcho on the latest version. For production, get your Honcho API key at [app.honcho.dev](https://app.honcho.dev/) . For local development, use `environment="local"`. [​](https://docs.honcho.dev/v2/integrations/crewai#crewai-honcho-storage) CrewAI Honcho Storage -------------------------------------------------------------------------------------------------- The `honcho_crewai` package provides `HonchoStorage`, a storage provider that implements CrewAI’s `Storage` interface using Honcho’s session-based memory. Before proceeding, it’s important to understand Honcho’s core concepts (`Peers` and `Sessions`). Review the [Honcho Architecture](https://docs.honcho.dev/v2/documentation/core-concepts/architecture) to familiarize yourself with these primitives. `HonchoStorage` implements CrewAI’s `Storage` interface using Honcho’s `peer` and `session` primitives. storage = HonchoStorage( user_id="demo-user", # Required: Honcho `peer` ID for the user session_id=None, # Optional: Specific `session` ID (auto-generated UUID if None) honcho_client=None, # Optional: Pre-configured Honcho client instance ) The `HonchoStorage` class implements three key methods: * **`save()`** - Stores messages in Honcho’s `session`, associating them with the appropriate `peer` (user or assistant) * **`search()`** - Performs semantic vector search using `session.search()` to find messages most relevant to the query. Supports optional `filters` parameter for fine-grained scoping. * **`reset()`** - Creates a new `session` to start fresh conversations CrewAI automatically calls these methods when agents need to store or retrieve memory, creating a seamless integration. ### [​](https://docs.honcho.dev/v2/integrations/crewai#search-with-filters) Search with Filters The `search()` method supports an optional `filters` parameter for fine-grained scoping of search results: # Search with peer_id filter (only messages from a specific peer) results = storage.search("query", filters={"peer_id": "user123"}) # Search with metadata filter results = storage.search("query", filters={"metadata": {"priority": "high"}}) # Search with time range filter results = storage.search("query", filters={"created_at": {"gte": "2024-01-01"}}) # Complex filter with logical operators results = storage.search("query", filters={ "AND": [\ {"peer_id": "user123"},\ {"metadata": {"topic": "python"}}\ ] }) For the full filter syntax including logical operators (AND, OR, NOT), comparison operators, and metadata filtering, see the [Using Filters](https://docs.honcho.dev/v2/documentation/core-concepts/features/using-filters) documentation. For comprehensive details about CrewAI’s memory system, see the [official CrewAI Memory documentation](https://docs.crewai.com/en/concepts/memory) . Let’s create a basic example showing how CrewAI agents use Honcho’s memory automatically: Python from dotenv import load_dotenv from crewai import Agent, Task, Crew, Process from crewai.memory.external.external_memory import ExternalMemory from honcho_crewai import HonchoStorage load_dotenv() storage = HonchoStorage(user_id="simple-demo-user") external_memory = ExternalMemory(storage=storage) messages = [\ ("user", "I'm learning Python programming"),\ ("assistant", "Great! Python is an excellent language to learn."),\ ("user", "I'm particularly interested in web development"),\ ] for role, message in messages: external_memory.save(message, metadata={"agent": role}) agent = Agent( role="Programming Mentor", goal="Help users learn programming by remembering their interests and progress", backstory=( "You are a patient programming mentor who remembers what students " "have told you about their learning journey and interests." ), verbose=True, allow_delegation=False ) task = Task( description=( "Based on what you know about the user's interests, " "suggest a simple web development project they could build to practice Python." ), expected_output="A specific project suggestion with brief explanation", agent=agent ) crew = Crew( agents=[agent], tasks=[task], process=Process.sequential, external_memory=external_memory, verbose=True ) result = crew.kickoff() print(result.raw) [​](https://docs.honcho.dev/v2/integrations/crewai#crewai-tool-integration) CrewAI Tool Integration ------------------------------------------------------------------------------------------------------ Honcho provides specialized tools that give CrewAI agents explicit control over memory retrieval: * **`HonchoGetContextTool`** - Retrieves comprehensive conversation history with token limits. Use for tasks needing broad conversation understanding. * **`HonchoDialecticTool`** - Queries representations about `peer`s. Use for understanding user preferences and characteristics without full message history. * **`HonchoSearchTool`** - Performs semantic search for specific information. Supports optional `filters` parameter for fine-grained scoping. Use for targeted queries like “what did the user say about budget?” Agents can use multiple tools in sequence: search for topics, query dialectic for preferences, then get full context for generation. Here’s an example demonstrating all three tools: Python from dotenv import load_dotenv from crewai import Agent, Task, Crew, Process from honcho import Honcho from honcho_crewai import ( HonchoGetContextTool, HonchoDialecticTool, HonchoSearchTool, ) load_dotenv() honcho = Honcho() user_id = "demo-user-45" session_id = "tools-demo-session" user = honcho.peer(user_id) session = honcho.session(session_id) messages = [\ "I'm planning a trip to Japan in March",\ "I love trying authentic local cuisine, especially ramen and sushi",\ "My budget is around $3000 for a 10-day trip",\ "I'm interested in visiting both Tokyo and Kyoto",\ "I prefer staying in traditional ryokans over hotels",\ ] for msg in messages: session.add_messages([user.message(msg)]) context_tool = HonchoGetContextTool( honcho=honcho, session_id=session_id, peer_id=user_id ) dialectic_tool = HonchoDialecticTool( honcho=honcho, session_id=session_id, peer_id=user_id ) search_tool = HonchoSearchTool(honcho=honcho, session_id=session_id) # Note: The search tool supports optional filters for fine-grained scoping # Agents can use filters like {"peer_id": "user123"} or {"metadata": {"priority": "high"}} travel_agent = Agent( role="Travel Planning Specialist", goal="Create personalized travel recommendations using memory tools", backstory=( "You are an expert travel planner with access to conversation memory tools. " "Use the tools to understand the user's preferences before making recommendations." ), tools=[context_tool, dialectic_tool, search_tool], verbose=True, allow_delegation=False ) task = Task( description=( "Create a personalized 3-day Tokyo itinerary. " "Use the memory tools to understand:\n" " • Food preferences (use search_tool for 'cuisine' or 'food')\n" " • Travel style and budget (use dialectic_tool to query user knowledge)\n" " • Recent context (use context_tool to get conversation history)\n" "Then create a detailed plan matching their interests." ), expected_output=( "A 3-day Tokyo itinerary with:\n" " • Daily activities matching user interests\n" " • Restaurant recommendations\n" " • Accommodation suggestions\n" " • Budget considerations" ), agent=travel_agent ) crew = Crew( agents=[travel_agent], tasks=[task], process=Process.sequential, verbose=True ) crew.kickoff() [​](https://docs.honcho.dev/v2/integrations/crewai#tool-based-vs-automatic-memory) Tool-Based vs Automatic Memory -------------------------------------------------------------------------------------------------------------------- **Use `HonchoStorage`** for automatic memory - CrewAI handles everything transparently. Best for simple conversational flows. **Use Honcho Tools** for strategic control - agents decide when and how to query memory. Best for multi-step reasoning, when different query types are needed, or multi-agent systems. You can combine both: automatic memory for baseline context, tools for specific queries. See the [hybrid memory example](https://github.com/plastic-labs/honcho/blob/main/examples/crewai/python/examples/hybrid_memory_example.py) for a complete implementation. **Multi-Agent Memory:** Use Honcho tools with different `peer_id` values to give each agent distinct memory and identity. [​](https://docs.honcho.dev/v2/integrations/crewai#next-steps) Next Steps ---------------------------------------------------------------------------- Now that you have a working CrewAI integration with Honcho, you can: * **Create specialized agents** with domain-specific memory and context * **Use CrewAI’s advanced features** like hierarchical processes, tool delegation, and conditional task execution * **Leverage logical reasoning** via the Dialectic API for deep `peer` understanding * **Implement custom tools** to give agents explicit control over memory retrieval [​](https://docs.honcho.dev/v2/integrations/crewai#related-resources) Related Resources ------------------------------------------------------------------------------------------ Honcho Architecture ------------------- Understand Honcho’s peer-based model and core primitives Get Context ----------- Learn about retrieving and formatting conversation context Dialectic API ------------- Query `peer` representations for deeper understanding LangGraph Integration --------------------- Build stateful agents with LangGraph and Honcho [Migrating from Mem0](https://docs.honcho.dev/v2/migrations/from-mem0) [LangGraph](https://docs.honcho.dev/v2/integrations/langgraph) ⌘I --- # Architecture & Intuition - Honcho [Skip to main content](https://docs.honcho.dev/v3/documentation/core-concepts/architecture#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Core Concepts Architecture & Intuition [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Data Model](https://docs.honcho.dev/v3/documentation/core-concepts/architecture#data-model) * [Workspaces](https://docs.honcho.dev/v3/documentation/core-concepts/architecture#workspaces) * [Peers](https://docs.honcho.dev/v3/documentation/core-concepts/architecture#peers) * [Sessions](https://docs.honcho.dev/v3/documentation/core-concepts/architecture#sessions) * [Messages](https://docs.honcho.dev/v3/documentation/core-concepts/architecture#messages) * [Data Flow](https://docs.honcho.dev/v3/documentation/core-concepts/architecture#data-flow) * [Configuration & Extensibility](https://docs.honcho.dev/v3/documentation/core-concepts/architecture#configuration-%26-extensibility) * [Design Principles](https://docs.honcho.dev/v3/documentation/core-concepts/architecture#design-principles) * [Next Steps](https://docs.honcho.dev/v3/documentation/core-concepts/architecture#next-steps) Honcho is memory infrastructure that continuously [_reasons_](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning) about data to build rich representations of peers (users, agents, or any entity) over time. This document explains the data model, system components, and how data flows through Honcho. [​](https://docs.honcho.dev/v3/documentation/core-concepts/architecture#data-model) Data Model ------------------------------------------------------------------------------------------------- Honcho has a hierarchical data model centered around the entities below. * A Workspace has Peers & Sessions * A Peer can be in multiple Sessions and can send Messages in a Session * A Session can have many Peers and stores Messages sent by its Peers ### [​](https://docs.honcho.dev/v3/documentation/core-concepts/architecture#workspaces) Workspaces Workspaces are the top-level containers in Honcho. They provide complete isolation between different applications or environments, essentially serving as a namespace to keep different workloads separate. You might use separate workspaces for development, staging, and production environments, or to isolate different product lines. They also enable multi-tenant SaaS applications where each customer gets their own isolated workspace with complete data separation. Authentication is scoped to the workspace level, and configuration settings can be applied workspace-wide to control behavior across all peers and sessions within that workspace. * * * ### [​](https://docs.honcho.dev/v3/documentation/core-concepts/architecture#peers) Peers Peers are the most important entity in Honcho—everything revolves around building and maintaining their [_representations_](https://docs.honcho.dev/v3/documentation/core-concepts/representation) . A peer represents any individual user, agent, or entity in a workspace. Treating humans and agents the same way lets you build arbitrary combinations for multi-agent or group chat scenarios. Each peer has a unique identifier within a workspace and is a container for reasoning across all their sessions. This cross-session context means conclusions drawn about a peer in one session can inform interactions in completely different sessions. Peers can be configured to control whether Honcho reasons about them. You can use peers for any entity that persists over time—individual users in chatbot applications, AI agents interacting with users or other agents, customer profiles in support systems, student profiles in educational platforms, or even NPCs in role-playing games. * * * ### [​](https://docs.honcho.dev/v3/documentation/core-concepts/architecture#sessions) Sessions Sessions represent interaction threads or contexts between peers. A session can involve multiple peers and provides temporal boundaries for when a set of interactions starts and ends. This lets you scope context and memory to specific interactions while still maintaining longer-term peer representations that span sessions. Use sessions to scope things like support tickets, meeting transcripts, learning sessions, or conversations. You can also use single-peer sessions as a way to import external data—create a session with just one peer and structure emails, documents, or files as messages to enrich that peer’s representation. Session-level configuration gives you fine-grained control over perspective-taking behavior. You can configure whether a peer should form representations of other peers in the session, and whether other peers should form representations of them. * * * ### [​](https://docs.honcho.dev/v3/documentation/core-concepts/architecture#messages) Messages Messages are the fundamental units of interaction within sessions. While they typically represent back-and-forth communication between peers, you can also use messages to ingest any information that provides context—emails, documents, files, user actions, system notifications, or rich media content. Every message is attributed to a specific peer and ordered chronologically within its session. When messages are created, they trigger automatic background reasoning that updates peer representations. Messages support rich metadata and structured data through JSONB fields, making them flexible enough to capture whatever information matters for your use case. [​](https://docs.honcho.dev/v3/documentation/core-concepts/architecture#data-flow) Data Flow ----------------------------------------------------------------------------------------------- Understanding how data moves through Honcho helps clarify the architecture. When you create messages, they’re immediately written to PostgreSQL and reasoning tasks are added to background queues. Background workers then generate logic, summaries, and new insights to improve representations. These conclusions and insights get stored in vector collections for retrieval. This async approach ensures fast writes while still providing rich reasoning capabilities. When you need context from Honcho, you query through the “Chat” endpoint or “Get Context” endpoint. Honcho retrieves relevant conclusions from vector storage along with recent messages, then assembles everything into coherent context ready to inject into agent prompts. ![Honcho Architecture](https://mintcdn.com/plasticlabs/Pwe1D9IEDkAtnMKn/images/architecture.png?w=2500&fit=max&auto=format&n=Pwe1D9IEDkAtnMKn&q=85&s=e38a2ac3a99c0dad537c899558f97910) The diagram above shows how agents write messages to Honcho, which triggers reasoning that updates peer representations. Agents can then query representations to get additional context for their next response. Black arrows represent read/write of regular data (messages, storage), while red arrows represent read/write of reasoned-over data (logic, peer representations). [​](https://docs.honcho.dev/v3/documentation/core-concepts/architecture#configuration-&-extensibility) Configuration & Extensibility --------------------------------------------------------------------------------------------------------------------------------------- Honcho is designed to be flexible. Settings cascade hierarchically from workspace to peer to session, so you can set defaults at the workspace level and override them for specific peers or sessions. Feature flags let you enable or disable reasoning modes, perspective tracking, and other capabilities. You can bring your own LLM provider—OpenAI, Anthropic, or custom endpoints—and metadata fields let you extend any primitive with custom JSON data. Batch operations let you create up to 100 messages in a single API call for efficient bulk ingestion. [​](https://docs.honcho.dev/v3/documentation/core-concepts/architecture#design-principles) Design Principles --------------------------------------------------------------------------------------------------------------- Honcho’s architecture follows a few core principles. Everything revolves around building representations of peers (peer-centric). Memory isn’t just storage—it’s continual learning (reasoning-first). Long-lived operations happen in the background so they don’t block user interactions (async by default). The system works with any LLM provider (provider-agnostic) and is built for isolation and scalability from the ground up (multi-tenant). Users and agents are both represented as peers, which enables flexible scenarios you couldn’t easily model with a traditional user-assistant paradigm (unified paradigm). [​](https://docs.honcho.dev/v3/documentation/core-concepts/architecture#next-steps) Next Steps ------------------------------------------------------------------------------------------------- Get an API Key -------------- Sign up for the Honcho platform and start building Quickstart ---------- Get started with your first integration Reasoning --------- Learn how Honcho reasons about messages to build memory Peer Representations -------------------- Understand what peer representations are and how they work [Agentic Development](https://docs.honcho.dev/v3/documentation/introduction/vibecoding) [Reasoning](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning) ⌘I --- # Honcho Reasoning - Honcho [Skip to main content](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Core Concepts Honcho Reasoning [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Why Reasoning?](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning#why-reasoning) * [Formal Logic Framework](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning#formal-logic-framework) * [How It Works](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning#how-it-works) * [Token Batching](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning#token-batching) * [Balances & Design Choices](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning#balances-%26-design-choices) * [Next Steps](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning#next-steps) Honcho is a memory system that _reasons_. You can read more on the philosophy behind the approach [here](https://blog.plasticlabs.ai/blog/Memory-as-Reasoning) , but practically speaking, the system runs inference on data in the background to produce the highest quality context for simulating statefulness. This document explains why reasoning is necessary and how Honcho implements it. If you’d like to experience this methodology first-hand, try out [Honcho Chat](https://honcho.chat/) —an interface to your personal memory. Read more [here](https://blog.plasticlabs.ai/blog/Introducing-Honcho-Chat) ! [​](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning#why-reasoning) Why Reasoning? ----------------------------------------------------------------------------------------------------- Traditional RAG systems treat memory as static storage—they retrieve what was explicitly said when semantically similar queries appear. Other solutions take an opinion for you on what’s important to store, whether through structured facts in databases or predefined knowledge graphs. Honcho takes a different approach: we extract all latent information by reasoning about everything, so it’s there when you need it. Our job is to produce the most robust reasoning possible—it’s your job as a developer to decide what’s relevant for your use case. We extract this latent information through formal logic. Formal logical reasoning is AI-native—LLMs perform the rigorous, compute-intensive thinking that humans struggle with, instantly and consistently. This unlocks insights that are only accessible by _rigorously thinking_ about your data, generating new understanding that goes beyond simple recall. [​](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning#formal-logic-framework) Formal Logic Framework ---------------------------------------------------------------------------------------------------------------------- Honcho’s memory system is powered by custom models trained to perform formal logical reasoning. The system extracts what was explicitly stated, draws certain conclusions from those, identifies patterns across multiple conclusions, and infers the simplest explanations for behavior. Why formal logic specifically? LLMs are uniquely well-suited for this reasoning task—it’s well-represented in the pretraining data. LLMs can maintain consistent reasoning across thousands of conclusions without cognitive fatigue or belief resistance—which is extremely hard for humans to do reliably. The outputs are also composable, meaning logical conclusions can be stored, retrieved, and combined programmatically for dynamic context assembly. Here’s an example of a data structure the reasoning models generate: { "explicit": [\ {\ "content": "premise 1"\ },\ ...\ {\ "content": "premise n"\ }\ ], "deductive": [\ {\ "premises": [\ "premise 1",\ ...\ "premise n"\ ],\ "conclusion": "conclusion 1"\ },\ ...\ ] } The explicit reasoning model ([Neuromancer XR](https://blog.plasticlabs.ai/research/Introducing-Neuromancer-XR) ) outputs its “thinking” followed by things that were explicitly stated, which serve as premises to scaffold deductive conclusions. It’s on top of this reasoning foundation that further reasoning is scaffolded. Currently that includes peer cards (key biographical information about the peer), consolidation (identifying redundant or contradictory information), induction (pattern recognition across multiple messages), and abduction (inferring the simplest explanations for observed behavior). The reasoning that Honcho does is something we’re constantly iterating and improving on. Our goal is simple—provide the richest, most relevant context in the fastest, cheapest way possible in order to simulate statefulness in whatever setting you need. [​](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning#how-it-works) How It Works -------------------------------------------------------------------------------------------------- When you write messages to Honcho, they’re stored immediately and enqueued for background processing. Reasoning asynchronously ensures fast writes while still providing rich reasoning capabilities. Messages are stored immediately without blocking, and session-based queues maintain chronological consistency so reasoning tasks affecting the same peer representation are always processed in order. The reasoning outputs—conclusions, summaries, peer cards—are stored as part of peer representations, indexed in vector collections for retrieval. ![Diagram for reasoning in Honcho](https://mintcdn.com/plasticlabs/Pwe1D9IEDkAtnMKn/images/reasoning.png?w=2500&fit=max&auto=format&n=Pwe1D9IEDkAtnMKn&q=85&s=06c197a777fc9ea8908cf378a2141e25) The diagram above shows how agents write messages to Honcho, which triggers reasoning that updates peer representations. Agents can then query representations to get additional context for their next response. ### [​](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning#token-batching) Token Batching Rather than running inference on every individual message, Honcho accumulates messages in the queue and processes them as a batch once the total token count of pending messages for a given peer representation crosses a threshold—roughly **1,000 tokens** at the current batch size. This keeps ingestion costs down, since Honcho charges based on reasoning passes, and ensures each pass has a meaningful amount of context to work with. At ~1,000 tokens the batch comfortably fits in the context window of any modern LLM, so no content is lost. If a user sends several short messages in a row (e.g., “yes”, “ok”, “sounds good”), those messages sit in the queue until enough content has accumulated. Once the threshold is met, the full batch is processed together in a single reasoning call. This batching only applies to **representation** tasks (conclusion extraction). Summary and dream tasks have their own scheduling logic and are not subject to the token threshold. [​](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning#balances-&-design-choices) Balances & Design Choices ---------------------------------------------------------------------------------------------------------------------------- Off-the-shelf LLMs can perform formal logical reasoning, but they aren’t optimized for it. Honcho uses custom models trained specifically for logical rigor (following formal reasoning rules rather than plausible-sounding text), structured output (consistent JSON schema with premises and conclusions), and efficiency (smaller, faster models tuned for this specific task). This allows Honcho to reason more reliably and at lower cost than general-purpose frontier LLMs. The approach balances quality with practical constraints. Custom models are smaller and cheaper to run, scaffolded conclusions are more token-efficient than raw conversation history, and we batch where appropriate to optimize update frequency. Honcho’s reasoning capabilities are actively being improved. Current areas of development include enhanced inductive and abductive reasoning, multi-hop and temporal reasoning, and expanded file types and modalities. The system is designed to be extensible—new reasoning capabilities can be added without breaking existing functionality. If you find that the data you’re uploading to Honcho isn’t being reasoned over to your liking, we’d love to improve it for you and ingest your data for free—reach out via [Discord](https://discord.gg/honcho) or [email](mailto:support@plasticlabs.ai) ! [​](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning#next-steps) Next Steps ---------------------------------------------------------------------------------------------- Without exhaustive reasoning, you’re stuck with surface-level retrieval or someone else’s opinion on what matters. You can’t effectively simulate statefulness if you’re not reasoning about everything in the present—coherence plummets, trust falls, and users churn. Don’t leave key information on the table. Use Honcho to give your agents the context they need to reconstruct the past as comprehensively as possible and maintain coherence—for your use case. Get an API Key -------------- Sign up for the Honcho platform and start building Quickstart ---------- Get started with your first integration Architecture ------------ See how reasoning fits into Honcho’s overall architecture Peer Representations -------------------- Learn how reasoning produces peer representations [Architecture](https://docs.honcho.dev/v3/documentation/core-concepts/architecture) [Representations](https://docs.honcho.dev/v3/documentation/core-concepts/representation) ⌘I --- # Migrating from Mem0 - Honcho [Skip to main content](https://docs.honcho.dev/v2/migrations/from-mem0#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Migrations Migrating from Mem0 [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [Why Honcho?](https://docs.honcho.dev/v2/migrations/from-mem0#why-honcho) * [Quick Migration](https://docs.honcho.dev/v2/migrations/from-mem0#quick-migration) * [Step-by-Step Migration](https://docs.honcho.dev/v2/migrations/from-mem0#step-by-step-migration) * [1\. Export User Messages](https://docs.honcho.dev/v2/migrations/from-mem0#1-export-user-messages) * [2\. Install the Honcho SDK](https://docs.honcho.dev/v2/migrations/from-mem0#2-install-the-honcho-sdk) * [3\. Initialize the Honcho Client](https://docs.honcho.dev/v2/migrations/from-mem0#3-initialize-the-honcho-client) * [4\. Import Your Data](https://docs.honcho.dev/v2/migrations/from-mem0#4-import-your-data) * [5\. Update Your Application Code](https://docs.honcho.dev/v2/migrations/from-mem0#5-update-your-application-code) * [API Comparison](https://docs.honcho.dev/v2/migrations/from-mem0#api-comparison) * [Core Operations](https://docs.honcho.dev/v2/migrations/from-mem0#core-operations) * [Honcho-Only Capabilities](https://docs.honcho.dev/v2/migrations/from-mem0#honcho-only-capabilities) * [Next Steps](https://docs.honcho.dev/v2/migrations/from-mem0#next-steps) Interested in transferring your data from Mem0 to Honcho? This guide covers why to switch, how to migrate your data, and differences between the two products. [​](https://docs.honcho.dev/v2/migrations/from-mem0#why-honcho) Why Honcho? ------------------------------------------------------------------------------ Mem0 & Honcho both store your data. Only Honcho reasons about it. [Read more about our approach](https://blog.plasticlabs.ai/blog/Memory-as-Reasoning) . **Compounding Insights** - Honcho extracts insights that build on each other over time. The more your users interact, the richer and more accurate their profiles become. **Superior Performance** - Higher accuracy on memory retrieval benchmarks with faster inference times (more details soon!). **Competitive Pricing** - Mem0 charges for retrieval, not ingestion. Meaning you pay to access your own data. Honcho offers straightforward pricing with a generous free tier. **Advanced Multi-Peer Sessions** - Honcho offers configurable observation settings (who builds memories about whom), representation-based queries between participants, and first-class peer objects. We would love to support the transfer and cost—just [book a call!](https://cal.com/team/plasticlabs/migration-to-honcho) [​](https://docs.honcho.dev/v2/migrations/from-mem0#quick-migration) Quick Migration --------------------------------------------------------------------------------------- For the best results, we recommend importing your raw messages directly into Honcho. This gives Honcho the full context to build rich, accurate representations and enables features like session summaries. However, if you’d like to get started quickly, you can migrate your existing Mem0 memories directly as **observations**. Get your API key at [app.honcho.dev/api-keys](https://app.honcho.dev/api-keys) . New accounts start with $100 credits. Python TypeScript # pip install mem0ai honcho-ai from mem0 import MemoryClient from honcho import Honcho # Export from Mem0 mem0 = MemoryClient(api_key="your-mem0-api-key") memories = mem0.get_all(filters={"user_id": "user123"}, page_size=100) # Initialize Honcho honcho = Honcho(api_key="your-honcho-api-key") user = honcho.peer("user123") session = honcho.session("imported") session.add_peers([user]) # Import memories directly as observations observations = [] for memory in memories['results']: content = memory.get("memory") or memory.get("messages", [{}])[0].get("content", "") if content: observations.append({"content": content, "session_id": "imported"}) # Batch create observations (up to 100 at a time) if observations: user.observations.create(observations) print(f"Migrated {len(observations)} memories as observations!") That’s it! The user’s Mem0 memories are now searchable in Honcho as observations. For richer representations with deductive reasoning and session summaries, consider importing your raw messages as described in the [Step-by-Step Migration](https://docs.honcho.dev/v2/migrations/from-mem0#step-by-step-migration) section. For more details on replacing Mem0 API calls with Honcho equivalents go to [API Comparison](https://docs.honcho.dev/v2/migrations/from-mem0#api-comparison) . [​](https://docs.honcho.dev/v2/migrations/from-mem0#step-by-step-migration) Step-by-Step Migration ----------------------------------------------------------------------------------------------------- Prefer a more detailed walkthrough? Follow these steps: ### [​](https://docs.honcho.dev/v2/migrations/from-mem0#1-export-user-messages) 1\. Export User Messages Importing raw user messages gives Honcho the full conversational context to build the most accurate representations. We recommend using a data structure that preserves the session and peer structure. If you need any help with this transfer or have any questions, please reach out at [hello@plasticlabs.ai](mailto:hello@plasticlabs.ai) or [book a call!](https://cal.com/team/plasticlabs/migration-to-honcho) Alternatively, if you want to import the Mem0 memories, follow the example above and find more info in Mem0’s [export API documentation](https://docs.mem0.ai/cookbooks/essentials/exporting-memories) . ### [​](https://docs.honcho.dev/v2/migrations/from-mem0#2-install-the-honcho-sdk) 2\. Install the Honcho SDK Python (uv) Python (pip) TypeScript (npm) TypeScript (yarn) TypeScript (pnpm) uv add honcho-ai ### [​](https://docs.honcho.dev/v2/migrations/from-mem0#3-initialize-the-honcho-client) 3\. Initialize the Honcho Client Get your API key at [app.honcho.dev/api-keys](https://app.honcho.dev/api-keys) . New accounts start with $100 credits. Python TypeScript from honcho import Honcho honcho = Honcho( api_key="your-api-key" ) ### [​](https://docs.honcho.dev/v2/migrations/from-mem0#4-import-your-data) 4\. Import Your Data This is a possible implementation using raw user messages. Adapt the data structure to match your exported format. Python TypeScript # Example data structure (preserving message history with timestamps): exported_data = { "session-1": { "user123": [\ {"content": "I prefer dark mode", "timestamp": "2024-01-15T10:30:00Z"},\ {"content": "My name is Alex", "timestamp": "2024-01-15T10:31:00Z"},\ ], "user456": [\ {"content": "I work in finance", "timestamp": "2024-01-15T11:00:00Z"},\ {"content": "I like concise responses", "timestamp": "2024-01-15T11:02:00Z"},\ ], }, "session-2": { "user123": [\ {"content": "Meeting notes from last week...", "timestamp": "2024-01-16T09:00:00Z"},\ ], } } # Import into Honcho for session_name, users in exported_data.items(): session = honcho.session(session_name) for user_id, messages in users.items(): peer = honcho.peer(user_id) session.add_peers([peer]) # Sort by timestamp to preserve message order sorted_messages = sorted(messages, key=lambda m: m["timestamp"]) session.add_messages([peer.message(m["content"]) for m in sorted_messages]) ### [​](https://docs.honcho.dev/v2/migrations/from-mem0#5-update-your-application-code) 5\. Update Your Application Code Reference the [API Comparison](https://docs.honcho.dev/v2/migrations/from-mem0#api-comparison) to replace your Mem0 API calls with the Honcho equivalents. [​](https://docs.honcho.dev/v2/migrations/from-mem0#api-comparison) API Comparison ------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v2/migrations/from-mem0#core-operations) Core Operations | Operation | Mem0 | Honcho | Notes | | --- | --- | --- | --- | | **Initialize** | `MemoryClient(api_key=...)` | `Honcho(api_key=...)` | | | **Identity** | `user_id` string param | `peer = honcho.peer("id")` | Peers can be users or AI agents | | **Add messages** | `client.add(messages, user_id=...)` | `session.add_messages([peer.message(...)])` | Session-scoped, triggers reasoning | | **Add observations** | | `peer.observations.create([...])` | Direct observation or “memory” import, no processing | | **Search** | `client.search(query, filters={"user_id": ...})` | `peer.search(query)` or `peer.observations.query(...)` | Scoped to peer or session | | **List all** | `client.get_all(filters={"user_id": ...})` | `session.get_messages()` or `peer.observations.list()` | Messages or observations | | **Update** | `client.update(memory_id, data=...)` | `honcho.update_message(message, metadata=...)` | Metadata updates only | | **Delete** | `client.delete(memory_id)` | `peer.observations.delete(id)` or `session.delete()` | Observation or session-level | ### [​](https://docs.honcho.dev/v2/migrations/from-mem0#honcho-only-capabilities) Honcho-Only Capabilities Mem0 requires manual assembly of context from `search()` results. Honcho’s `session.get_context()` returns a ready-to-use `SessionContext` object with built-in token limits, auto-included summaries, and format helpers (`.to_openai()`, `.to_anthropic()`). Get Context ----------- Learn more about token-optimized context retrieval Mem0’s `search()` returns basic vector, semantic, or raw memory matches. Honcho’s `peer.chat()` enables your agent to _reason_ about what it knows—returning synthesized natural language insights with streaming support and scoped queries. Dialectic Endpoint ------------------ Learn more about inference-powered queries Additional features with **no Mem0 equivalent**: | Honcho Method | Description | Use Case | | --- | --- | --- | | `peer.card()` | Stable biographical facts (name, preferences, background) | User profiles, personalization | | `session.working_rep(peer)` | Cached psychological analysis (mental state, intentions) | Real-time adaptation | | `session.get_summaries()` | Auto-generated short/long session summaries | Conversation continuity | | `SessionPeerConfig` | Configure observation settings (who learns about whom) | Privacy controls, role-based learning | [​](https://docs.honcho.dev/v2/migrations/from-mem0#next-steps) Next Steps ----------------------------------------------------------------------------- Architecture ------------ Understand peers and sessions Dialectic API ------------- Inference responses Guides ------ Integration examples Questions? Join our [Discord](https://discord.gg/honcho) or open an issue on [GitHub](https://github.com/plastic-labs/honcho/issues) . [Overview](https://docs.honcho.dev/v2/guides/overview) [CrewAI](https://docs.honcho.dev/v2/integrations/crewai) ⌘I --- # Telegram Bots with Honcho - Honcho [Skip to main content](https://docs.honcho.dev/v2/guides/telegram#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Application Interfaces Telegram Bots with Honcho [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [Message Handling](https://docs.honcho.dev/v2/guides/telegram#message-handling) * [Helper Functions](https://docs.honcho.dev/v2/guides/telegram#helper-functions) * [Message Validation](https://docs.honcho.dev/v2/guides/telegram#message-validation) * [Message Sanitization](https://docs.honcho.dev/v2/guides/telegram#message-sanitization) * [Peer ID Generation](https://docs.honcho.dev/v2/guides/telegram#peer-id-generation) * [LLM Integration](https://docs.honcho.dev/v2/guides/telegram#llm-integration) * [Message Sending](https://docs.honcho.dev/v2/guides/telegram#message-sending) * [Honcho Integration](https://docs.honcho.dev/v2/guides/telegram#honcho-integration) * [Commands](https://docs.honcho.dev/v2/guides/telegram#commands) * [Setup and Configuration](https://docs.honcho.dev/v2/guides/telegram#setup-and-configuration) * [Application Setup](https://docs.honcho.dev/v2/guides/telegram#application-setup) * [Environment Variables](https://docs.honcho.dev/v2/guides/telegram#environment-variables) * [Chat Types and Behavior](https://docs.honcho.dev/v2/guides/telegram#chat-types-and-behavior) * [Private Chats](https://docs.honcho.dev/v2/guides/telegram#private-chats) * [Group Chats](https://docs.honcho.dev/v2/guides/telegram#group-chats) * [Recap](https://docs.honcho.dev/v2/guides/telegram#recap) > Example code is available on [GitHub](https://github.com/plastic-labs/telegram-python-starter) Any application interface that defines logic based on events and supports special commands can work easily with Honcho. Here’s how to use Honcho with **Telegram** as an interface. If you’re not familiar with Telegram bot development, the [python-telegram-bot](https://docs.python-telegram-bot.org/en/stable/) docs would be a good place to start. [​](https://docs.honcho.dev/v2/guides/telegram#message-handling) Message Handling ------------------------------------------------------------------------------------ Most Telegram bots have async functions that handle incoming messages. We can use Honcho to store messages by user and session based on the chat context. Take the following function definition for example: async def handle_message(update: Update, context: ContextTypes.DEFAULT_TYPE): """ Receive a message from Telegram and respond with a message from our LLM assistant. """ if not validate_message(update, context): return message_text = update.effective_message.text input_text = sanitize_message(message_text, context.bot.username) # If the message is empty after sanitizing, ignore it if not input_text: return peer = honcho_client.peer(id=get_peer_id_from_telegram(update)) session = honcho_client.session(id=str(update.effective_chat.id)) # Send typing indicator await context.bot.send_chat_action( chat_id=update.effective_chat.id, action="typing" ) response = llm(session, input_text) await send_telegram_message(update, context, response) # Save both the user's message and the bot's response to the session session.add_messages( [\ peer.message(input_text),\ assistant.message(response),\ ] ) Let’s break down what this code is doing… async def handle_message(update: Update, context: ContextTypes.DEFAULT_TYPE): if not validate_message(update, context): return This is how you define a message handler in `python-telegram-bot` that processes incoming messages. We use a helper function `validate_message()` to check if the message should be processed. [​](https://docs.honcho.dev/v2/guides/telegram#helper-functions) Helper Functions ------------------------------------------------------------------------------------ The code uses several helper functions to keep the main logic clean and readable. Let’s examine each one: ### [​](https://docs.honcho.dev/v2/guides/telegram#message-validation) Message Validation def validate_message(update: Update, context: ContextTypes.DEFAULT_TYPE) -> bool: """ Determine if the message is valid for the bot to respond to. Return True if it is, False otherwise. The bot will respond to: - Direct messages (private chats) - Group messages that mention the bot or reply to it - Messages that are not from the bot itself """ message = update.effective_message if not message or not message.text: return False # Don't respond to our own messages if message.from_user.id == context.bot.id: return False # Always respond in private chats if update.effective_chat.type == "private": return True # In groups, only respond if mentioned or replied to if ( message.reply_to_message and message.reply_to_message.from_user.id == context.bot.id ): return True # Check if bot is mentioned if message.entities: for entity in message.entities: if entity.type == "mention": username = message.text[entity.offset : entity.offset + entity.length] if username == f"@{context.bot.username}": return True return False This function centralizes all the logic for determining whether the bot should respond to a message. It handles different chat types: * **Private chats**: Always respond * **Group chats**: Only respond when mentioned or when replying to the bot’s messages * **Bot prevention**: Never respond to the bot’s own messages ### [​](https://docs.honcho.dev/v2/guides/telegram#message-sanitization) Message Sanitization def sanitize_message(message_text: str, bot_username: str) -> str | None: """Remove the bot's mention from the message content if present""" content = message_text.replace(f"@{bot_username}", "").strip() if not content: return None return content This helper removes the bot’s mention from the message content, leaving just the actual user input. ### [​](https://docs.honcho.dev/v2/guides/telegram#peer-id-generation) Peer ID Generation def get_peer_id_from_telegram(update: Update) -> str: """Get a Honcho peer ID for the message author""" return f"telegram_{update.effective_user.id}" This creates a unique peer identifier for each Telegram user by prefixing their Telegram user ID. ### [​](https://docs.honcho.dev/v2/guides/telegram#llm-integration) LLM Integration def llm(session, prompt) -> str: """ Call the LLM with the given prompt and chat history. You should expand this function with custom logic, prompts, etc. """ messages: list[dict[str, object]] = session.get_context().to_openai( assistant=assistant ) messages.append({"role": "user", "content": prompt}) try: completion = openai.chat.completions.create( model=MODEL_NAME, messages=messages, ) return completion.choices[0].message.content except Exception as e: logger.error(f"LLM error: {e}") return f"Error: {e}" This function handles the LLM interaction. It uses Honcho’s built-in `to_openai()` method to automatically convert the session context into the format expected by OpenAI’s chat completions API. ### [​](https://docs.honcho.dev/v2/guides/telegram#message-sending) Message Sending async def send_telegram_message( update: Update, context: ContextTypes.DEFAULT_TYPE, response_content: str ): """Send a message to the Telegram chat, splitting if necessary""" # Telegram has a 4096 character limit, but we'll use 4000 to be safe max_length = 4000 if len(response_content) <= max_length: await update.effective_message.reply_text(response_content) else: # Split response into chunks at newlines, keeping under max_length chars chunks = [] current_chunk = "" for line in response_content.splitlines(keepends=True): if len(current_chunk) + len(line) > max_length: if current_chunk: chunks.append(current_chunk) current_chunk = line else: current_chunk += line if current_chunk: chunks.append(current_chunk) for chunk in chunks: await update.effective_message.reply_text(chunk) This function handles sending messages to Telegram, automatically splitting long responses into multiple messages to stay within Telegram’s 4096 character limit. It also includes a typing indicator to show the bot is processing. [​](https://docs.honcho.dev/v2/guides/telegram#honcho-integration) Honcho Integration ---------------------------------------------------------------------------------------- The new Honcho peer/session API makes integration much simpler: peer = honcho_client.peer(id=get_peer_id_from_telegram(update)) session = honcho_client.session(id=str(update.effective_chat.id)) Here we create a peer object for the user and a session object using the Telegram chat ID. This automatically handles user and session management across both private chats and group conversations. # Save both the user's message and the bot's response to the session session.add_messages( [\ peer.message(input_text),\ assistant.message(response),\ ] ) After generating the response, we save both the user’s input and the bot’s response to the session using the `add_messages()` method. The `peer.message()` creates a message from the user, while `assistant.message()` creates a message from the assistant. [​](https://docs.honcho.dev/v2/guides/telegram#commands) Commands -------------------------------------------------------------------- Telegram bots support slash commands natively. Here’s how to implement the `/dialectic` command using Honcho’s dialectic feature: async def dialectic_command(update: Update, context: ContextTypes.DEFAULT_TYPE): """ Handle the /dialectic command to query the Honcho Dialectic endpoint. """ if not context.args: await update.message.reply_text( "Please provide a query. Usage: /dialectic " ) return query = " ".join(context.args) try: peer = honcho_client.peer(id=get_peer_id_from_telegram(update)) session = honcho_client.session(id=str(update.effective_chat.id)) response = peer.chat( query=query, session_id=session.id, ) if response: await send_telegram_message(update, context, response) else: await update.message.reply_text( f"I don't know anything about {update.effective_user.first_name} because we haven't talked yet!" ) except Exception as e: logger.error(f"Error calling Dialectic API: {e}") await update.message.reply_text( f"Sorry, there was an error processing your request: {str(e)}" ) You can also add a `/start` command for user onboarding: async def start_command(update: Update, context: ContextTypes.DEFAULT_TYPE): """Handle the /start command""" await update.message.reply_text( "Hello! I'm your AI assistant. You can:\n" "• Chat with me directly in private messages\n" "• Mention me (@username) in groups to get my attention\n" "• Use /dialectic to search our conversation history\n\n" "Let's start chatting!" ) [​](https://docs.honcho.dev/v2/guides/telegram#setup-and-configuration) Setup and Configuration -------------------------------------------------------------------------------------------------- The bot requires several environment variables and setup: honcho_client = Honcho() assistant = honcho_client.peer(id="assistant", config={"observe_me": False}) openai = OpenAI(base_url="https://openrouter.ai/api/v1", api_key=MODEL_API_KEY) * `honcho_client`: The main Honcho client * `assistant`: A peer representing the bot/assistant * `openai`: OpenAI client configured to use OpenRouter ### [​](https://docs.honcho.dev/v2/guides/telegram#application-setup) Application Setup Register your handlers with the Telegram application: def main(): """Start the bot""" if not BOT_TOKEN: logger.error("BOT_TOKEN not found in environment variables") return # Create the Application application = Application.builder().token(BOT_TOKEN).build() # Add handlers application.add_handler(CommandHandler("start", start_command)) application.add_handler(CommandHandler("dialectic", dialectic_command)) application.add_handler( MessageHandler(filters.TEXT & ~filters.COMMAND, handle_message) ) # Start the bot logger.info("Starting Telegram bot...") application.run_polling(allowed_updates=Update.ALL_TYPES) [​](https://docs.honcho.dev/v2/guides/telegram#environment-variables) Environment Variables ---------------------------------------------------------------------------------------------- Your bot needs these environment variables: # Your Telegram bot token from BotFather BOT_TOKEN= # AI model to use (see OpenRouter for available models) MODEL_NAME= # Your OpenRouter API key MODEL_API_KEY= [​](https://docs.honcho.dev/v2/guides/telegram#chat-types-and-behavior) Chat Types and Behavior -------------------------------------------------------------------------------------------------- The bot handles different Telegram chat types intelligently: ### [​](https://docs.honcho.dev/v2/guides/telegram#private-chats) Private Chats * **Behavior**: Responds to all messages * **Session ID**: Uses the private chat ID * **Memory**: Maintains conversation history per user ### [​](https://docs.honcho.dev/v2/guides/telegram#group-chats) Group Chats * **Behavior**: Only responds when mentioned or replied to * **Session ID**: Uses the group chat ID (shared across all members) * **Memory**: Maintains group conversation context [​](https://docs.honcho.dev/v2/guides/telegram#recap) Recap -------------------------------------------------------------- The new Honcho peer/session API makes Telegram bot integration much simpler and more intuitive. Key patterns we learned: * **Peer/Session Model**: Users are represented as peers, conversations as sessions * **Chat Type Handling**: Different validation logic for private vs group chats * **Automatic Context Management**: `session.get_context().to_openai()` automatically formats chat history * **Message Storage**: `session.add_messages()` stores both user and assistant messages * **Dialectic Queries**: `peer.chat()` enables querying conversation history * **Command System**: Native Telegram command support with `/start` and `/dialectic` * **Message Splitting**: Automatic handling of Telegram’s character limits * **Helper Functions**: Clean code organization with focused helper functions This approach provides a clean, maintainable structure for building Telegram bots with conversational memory and context management across both private conversations and group chats. [n8n](https://docs.honcho.dev/v2/guides/n8n) ⌘I --- # Honcho Overview - Honcho [Skip to main content](https://docs.honcho.dev/v3/documentation/introduction/overview#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Introduction Honcho Overview [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Why Use Honcho?](https://docs.honcho.dev/v3/documentation/introduction/overview#why-use-honcho) * [How Honcho Works](https://docs.honcho.dev/v3/documentation/introduction/overview#how-honcho-works) * [Why Reasoning?](https://docs.honcho.dev/v3/documentation/introduction/overview#why-reasoning) * [Get Started](https://docs.honcho.dev/v3/documentation/introduction/overview#get-started) Honcho is an open source memory library with a managed service for building stateful agents. Use it with any model, framework, or architecture. It enables agents to build and maintain state about any entity—users, agents, groups, ideas, and more. And because it’s a continual learning system, it understands entities that change over time. Using Honcho as your memory system will earn your agents higher retention, more trust, and help you build data moats to out-compete incumbents. Honcho has defined the Pareto Frontier of Agent Memory. Watch the [video](https://x.com/honchodotdev/status/2002090546521911703?s=20) , check out our [evals page](https://evals.honcho.dev/) , and read the [blog post](https://blog.plasticlabs.ai/research/Benchmarking-Honcho) for more detail. Get an API Key -------------- Sign up and start building with Honcho Quickstart ---------- Build your first stateful agent in minutes [​](https://docs.honcho.dev/v3/documentation/introduction/overview#why-use-honcho) Why Use Honcho? ----------------------------------------------------------------------------------------------------- Honcho streamlines the agent building process by offering elegant, flexible primitives for managing context. It also reasons over that context to give developers access to far richer insights only accessible through reasoning. Take the following scenario: * You find a use case for LLMs and build an agent around it * It works well initially but can’t maintain context across sessions * You spend weeks engineering a RAG solution that seems to help * Then the cycle begins… * Users report the agent forgetting things, contradicting itself, or losing context mid-session * You build evals to quantify the problem * You re-engineer your entire RAG pipeline with better chunking, embeddings, retrieval strategies * The problems shift but don’t disappear * Repeat Eventually you realize the issue isn’t engineering—-it’s that you’re not extracting all the latent information from your data. You need to reason exhaustively, handle contradictions, track patterns over time, and maintain coherent state. In other words, you’d need to build Honcho. Break free from this cycle. Honcho is a general solution to context engineering, memory, and statefulness. [​](https://docs.honcho.dev/v3/documentation/introduction/overview#how-honcho-works) How Honcho Works -------------------------------------------------------------------------------------------------------- Honcho is a memory system that reasons. Read more on the approach [here](https://blog.plasticlabs.ai/blog/Memory-as-Reasoning) . Honcho has four storage primitives that work together: * **Workspaces** - Top-level containers that isolate different applications or environments * **Peers** - Any entity that persists but changes over time (users, agents, objects, and more) * **Sessions** - Interaction threads between peers with temporal boundaries * **Messages** - Units of data that trigger reasoning (conversations, events, activity, documents, and more) When you write messages to Honcho, they’re stored and processed in the background. Custom reasoning models perform formal logical [_reasoning_](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning) to generate conclusions about each peer. These conclusions are stored as [_representations_](https://docs.honcho.dev/v3/documentation/core-concepts/representation) that you can query to provide rich context for your agents. ![Honcho Architecture](https://mintcdn.com/plasticlabs/Pwe1D9IEDkAtnMKn/images/architecture.png?w=2500&fit=max&auto=format&n=Pwe1D9IEDkAtnMKn&q=85&s=e38a2ac3a99c0dad537c899558f97910) The diagram above shows the flow: agents write messages to Honcho, which triggers reasoning that updates what’s stored in representations. Developers (or agents) can then query to get additional context for their next response. [​](https://docs.honcho.dev/v3/documentation/introduction/overview#why-reasoning) Why Reasoning? --------------------------------------------------------------------------------------------------- Traditional RAG systems retrieve what was explicitly said, but they miss what matters most—the insights only accessible by _rigorously thinking_ about your data. Without reasoning, you’re leaving latent information on the table. Static retrieval can’t surface implicit connections, struggles when new information contradicts old data, and fails when you need to make predictions under uncertainty. Honcho uses formal logic to extract all that latent information. This reasoning is AI-native—it performs the rigorous, compute-intensive thinking that humans struggle with, instantly and consistently. The result is memory that goes beyond simple RAG recall to provide exhaustive context for statefulness. [​](https://docs.honcho.dev/v3/documentation/introduction/overview#get-started) Get Started ---------------------------------------------------------------------------------------------- Honcho gives you maximum control over your agent’s context and memory. The data model is flexible and composable, the reasoning backend is powerful yet cost-effective, and everything is built to give developers levers to manage token usage, latency, and reasoning depth. We’re just scratching the surface. Dive into the quickstart to see Honcho in action, explore the architecture to understand how it all fits together, or jump straight to building. Welcome to Honcho. We’re excited to have you at the frontier of AI with us 🫡. Get an API Key -------------- Sign up for the Honcho platform and get your API key Quickstart ---------- Build your first stateful agent in minutes Architecture ------------ Deep dive into how Honcho’s primitives fit together Reasoning --------- Learn how Honcho reasons about data to build memory [Quickstart](https://docs.honcho.dev/v3/documentation/introduction/quickstart) ⌘I --- # Storing Data - Honcho [Skip to main content](https://docs.honcho.dev/v3/documentation/features/storing-data#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Features Storing Data [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Chat Bots](https://docs.honcho.dev/v3/documentation/features/storing-data#chat-bots) The most basic building block of Honcho’s data model is the `Message` object. A `Message` is sent by a `Peer` and saved in a `Session` Python TypeScript from honcho import Honcho honcho = Honcho() peer = honcho.peer("sample-peer") session = honcho.session("sample-session") message = peer.message("Hello, world!") session.add_messages([message]) Once a `Message` is saved in Honcho, it will kick off a background task that looks at the new data to generate insights about the `Peer` that sent the `Message` This is the default behavior of Honcho and can be turned off by [configuring the Peer or Session](https://docs.honcho.dev/v3/documentation/features/advanced/reasoning-configuration) This pattern of having a Peer, Session, and Messages is highly flexible and works for many different use cases and agent setups. Some use cases may only need a single Peer, but many Sessions. Others will only use a single `Session` for their entire app. These are flexible components that work in any situation. [​](https://docs.honcho.dev/v3/documentation/features/storing-data#chat-bots) Chat Bots ------------------------------------------------------------------------------------------ A common use case for Honcho to is to build a chatbot like ChatGPT or Claude. In this case you can simply * Make a `Peer` for the User * Make a `Peer` for the AI Then you can make a `Session` for each thread of conversation and save `Messages` from the user and assistant in each turn of conversation [Design Patterns](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns) [Get Context](https://docs.honcho.dev/v3/documentation/features/get-context) ⌘I --- # Get App By Name - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-app-by-name#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation apps Get App By Name [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const app = await client.apps.getByName('name'); console.log(app.id); } main(); 200 422 { "id": "", "name": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } GET http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / name / {name} Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const app = await client.apps.getByName('name'); console.log(app.id); } main(); 200 422 { "id": "", "name": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-app-by-name#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-app-by-name#parameter-name) name string required Name of the app to retrieve #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-app-by-name#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-app-by-name#response-name) name string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-app-by-name#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-app-by-name#response-metadata) metadata Metadata · object [Update App](https://docs.honcho.dev/v1/api-reference/endpoint/apps/update-app) [Create App](https://docs.honcho.dev/v1/api-reference/endpoint/apps/create-app) ⌘I --- # Get All Apps - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-all-apps#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation apps Get All Apps [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { // Automatically fetches more pages as needed. for await (const app of client.apps.list()) { console.log(app.id); } } main(); 200 422 { "items": [\ {\ "id": "",\ "name": "",\ "created_at": "2023-11-07T05:31:56Z",\ "metadata": {}\ }\ ], "total": 1, "page": 2, "size": 2, "pages": 1 } POST http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / list Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { // Automatically fetches more pages as needed. for await (const app of client.apps.list()) { console.log(app.id); } } main(); 200 422 { "items": [\ {\ "id": "",\ "name": "",\ "created_at": "2023-11-07T05:31:56Z",\ "metadata": {}\ }\ ], "total": 1, "page": 2, "size": 2, "pages": 1 } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-all-apps#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Query Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-all-apps#parameter-one-of-0) reverse boolean | null default:false Whether to reverse the order of results [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-all-apps#parameter-page) page integer default:1 Page number Required range: `x >= 1` [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-all-apps#parameter-size) size integer default:50 Page size Required range: `1 <= x <= 100` #### Body application/json Filtering and pagination options for the apps list [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-all-apps#body-one-of-0-filter-one-of-0) filter Filter · object #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-all-apps#response-items) items App · object\[\] required Show child attributes [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-all-apps#response-total) total integer required Required range: `x >= 0` [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-all-apps#response-page) page integer required Required range: `x >= 1` [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-all-apps#response-size) size integer required Required range: `x >= 1` [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-all-apps#response-pages) pages integer Required range: `x >= 0` [Get App](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-app) [Update App](https://docs.honcho.dev/v1/api-reference/endpoint/apps/update-app) ⌘I --- # Get App - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-app#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation apps Get App [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const app = await client.apps.get(); console.log(app.id); } main(); 200 422 { "id": "", "name": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } GET http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const app = await client.apps.get(); console.log(app.id); } main(); 200 422 { "id": "", "name": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-app#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Query Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-app#parameter-one-of-0) app\_id string | null App ID to retrieve. If not provided, uses JWT #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-app#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-app#response-name) name string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-app#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-app#response-metadata) metadata Metadata · object [Introduction](https://docs.honcho.dev/v1/api-reference/introduction) [Get All Apps](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-all-apps) ⌘I --- # Configuration Guide - Honcho [Skip to main content](https://docs.honcho.dev/v2/contributing/configuration#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Contributing Configuration Guide [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [Recommended Configuration Approaches](https://docs.honcho.dev/v2/contributing/configuration#recommended-configuration-approaches) * [Option 1: Environment Variables Only (Production)](https://docs.honcho.dev/v2/contributing/configuration#option-1-environment-variables-only-production) * [Option 2: config.toml (Development/Simple Deployments)](https://docs.honcho.dev/v2/contributing/configuration#option-2-config-toml-development%2Fsimple-deployments) * [Option 3: Hybrid Approach](https://docs.honcho.dev/v2/contributing/configuration#option-3-hybrid-approach) * [Option 4: .env Only (Local Development)](https://docs.honcho.dev/v2/contributing/configuration#option-4-env-only-local-development) * [Configuration Methods](https://docs.honcho.dev/v2/contributing/configuration#configuration-methods) * [Using config.toml](https://docs.honcho.dev/v2/contributing/configuration#using-config-toml) * [Using Environment Variables](https://docs.honcho.dev/v2/contributing/configuration#using-environment-variables) * [Configuration Priority](https://docs.honcho.dev/v2/contributing/configuration#configuration-priority) * [Example](https://docs.honcho.dev/v2/contributing/configuration#example) * [Core Configuration](https://docs.honcho.dev/v2/contributing/configuration#core-configuration) * [Application Settings](https://docs.honcho.dev/v2/contributing/configuration#application-settings) * [Database Configuration](https://docs.honcho.dev/v2/contributing/configuration#database-configuration) * [Authentication Configuration](https://docs.honcho.dev/v2/contributing/configuration#authentication-configuration) * [Cache Configuration](https://docs.honcho.dev/v2/contributing/configuration#cache-configuration) * [LLM Provider Configuration](https://docs.honcho.dev/v2/contributing/configuration#llm-provider-configuration) * [API Keys](https://docs.honcho.dev/v2/contributing/configuration#api-keys) * [General LLM Settings](https://docs.honcho.dev/v2/contributing/configuration#general-llm-settings) * [Feature-Specific Model Configuration](https://docs.honcho.dev/v2/contributing/configuration#feature-specific-model-configuration) * [Default Provider Usage](https://docs.honcho.dev/v2/contributing/configuration#default-provider-usage) * [Additional Features Configuration](https://docs.honcho.dev/v2/contributing/configuration#additional-features-configuration) * [Dream Processing](https://docs.honcho.dev/v2/contributing/configuration#dream-processing) * [Webhook Configuration](https://docs.honcho.dev/v2/contributing/configuration#webhook-configuration) * [Metrics Collection](https://docs.honcho.dev/v2/contributing/configuration#metrics-collection) * [Monitoring Configuration](https://docs.honcho.dev/v2/contributing/configuration#monitoring-configuration) * [Sentry Error Tracking](https://docs.honcho.dev/v2/contributing/configuration#sentry-error-tracking) * [Environment-Specific Examples](https://docs.honcho.dev/v2/contributing/configuration#environment-specific-examples) * [Development Configuration](https://docs.honcho.dev/v2/contributing/configuration#development-configuration) * [Production Configuration](https://docs.honcho.dev/v2/contributing/configuration#production-configuration) * [Migration Management](https://docs.honcho.dev/v2/contributing/configuration#migration-management) * [Troubleshooting](https://docs.honcho.dev/v2/contributing/configuration#troubleshooting) Honcho uses a flexible configuration system that supports both TOML files and environment variables. Configuration values are loaded in the following priority order (highest to lowest): 1. Environment variables (always take precedence) 2. `.env` file (for local development) 3. `config.toml` file (base configuration) 4. Default values [​](https://docs.honcho.dev/v2/contributing/configuration#recommended-configuration-approaches) Recommended Configuration Approaches --------------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v2/contributing/configuration#option-1-environment-variables-only-production) Option 1: Environment Variables Only (Production) * Use environment variables for all configuration * No config files needed * Ideal for containerized deployments (Docker, Kubernetes) * Secrets managed by your deployment platform ### [​](https://docs.honcho.dev/v2/contributing/configuration#option-2-config-toml-development/simple-deployments) Option 2: config.toml (Development/Simple Deployments) * Use config.toml for base configuration * Override sensitive values with environment variables * Good for development and simple deployments ### [​](https://docs.honcho.dev/v2/contributing/configuration#option-3-hybrid-approach) Option 3: Hybrid Approach * Use config.toml for non-sensitive base settings * Use .env file for sensitive values (API keys, secrets) * Good for development teams ### [​](https://docs.honcho.dev/v2/contributing/configuration#option-4-env-only-local-development) Option 4: .env Only (Local Development) * Use .env file for all configuration * Simple for local development * Never commit .env files to version control [​](https://docs.honcho.dev/v2/contributing/configuration#configuration-methods) Configuration Methods --------------------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v2/contributing/configuration#using-config-toml) Using config.toml Copy the example configuration file to get started: cp config.toml.example config.toml Then modify the values as needed. The TOML file is organized into sections: * `[app]` - Application-level settings (log level, session limits, embedding settings, Langfuse integration, local metrics collection) * `[db]` - Database connection and pool settings (connection URI, pool size, timeouts, connection recycling) * `[auth]` - Authentication configuration (enable/disable auth, JWT secret) * `[cache]` - Redis cache configuration (enable/disable caching, Redis URL, TTL settings, lock configuration for cache stampede prevention) * `[llm]` - LLM provider API keys (Anthropic, OpenAI, Gemini, Groq, OpenAI-compatible endpoints) and general LLM settings * `[dialectic]` - Dialectic API configuration (provider, model, query generation settings, semantic search parameters, context window size) * `[deriver]` - Background worker settings (worker count, polling intervals, queue management) and theory of mind configuration (model, tokens, observation limits) * `[peer_card]` - Peer card generation settings (provider, model, token limits) * `[summary]` - Session summarization settings (frequency thresholds, provider, model, token limits for short and long summaries) * `[dream]` - Dream processing configuration (enable/disable, thresholds, idle timeouts, dream types, LLM settings) * `[webhook]` - Webhook configuration (webhook secret, workspace limits) * `[metrics]` - Metrics collection settings (enable/disable metrics, namespace) * `[sentry]` - Error tracking and monitoring settings (enable/disable, DSN, environment, sample rates) ### [​](https://docs.honcho.dev/v2/contributing/configuration#using-environment-variables) Using Environment Variables All configuration values can be overridden using environment variables. The environment variable names follow this pattern: * `{SECTION}_{KEY}` for nested settings * Just `{KEY}` for app-level settings Examples: * `DB_CONNECTION_URI` → `[db].CONNECTION_URI` * `DB_POOL_SIZE` → `[db].POOL_SIZE` * `AUTH_JWT_SECRET` → `[auth].JWT_SECRET` * `DIALECTIC_MODEL` → `[dialectic].MODEL` * `LOG_LEVEL` (no section) → `[app].LOG_LEVEL` ### [​](https://docs.honcho.dev/v2/contributing/configuration#configuration-priority) Configuration Priority When a configuration value is set in multiple places, Honcho uses this priority: 1. **Environment variables** - Always take precedence 2. **.env file** - Loaded for local development 3. **config.toml** - Base configuration 4. **Default values** - Built-in defaults This allows you to: * Use `config.toml` for base configuration * Override specific values with environment variables in production * Use `.env` files for local development without modifying config.toml ### [​](https://docs.honcho.dev/v2/contributing/configuration#example) Example If you have this in `config.toml`: [db] CONNECTION_URI = "postgresql+psycopg://localhost/honcho_dev" POOL_SIZE = 10 You can override just the connection URI in production: export DB_CONNECTION_URI="postgresql+psycopg://prod-server/honcho_prod" The application will use the production connection URI while keeping the pool size from config.toml. [​](https://docs.honcho.dev/v2/contributing/configuration#core-configuration) Core Configuration --------------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v2/contributing/configuration#application-settings) Application Settings Application-level settings control core behavior of the Honcho server including logging, session limits, message handling, and optional integrations. **Basic Application Configuration:** # Logging and server settings LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR, CRITICAL # Session and context limits SESSION_OBSERVERS_LIMIT=10 # Maximum number of observers per session GET_CONTEXT_MAX_TOKENS=100000 # Maximum tokens for context retrieval MAX_MESSAGE_SIZE=25000 # Maximum message size in characters # Embedding settings EMBED_MESSAGES=true # Enable vector embeddings for messages MAX_EMBEDDING_TOKENS=8192 # Maximum tokens per embedding MAX_EMBEDDING_TOKENS_PER_REQUEST=300000 # Batch embedding limit **Optional Integrations:** # Langfuse integration for LLM observability LANGFUSE_HOST=https://cloud.langfuse.com LANGFUSE_PUBLIC_KEY=your-langfuse-public-key # Local metrics collection COLLECT_METRICS_LOCAL=false LOCAL_METRICS_FILE=metrics.jsonl ### [​](https://docs.honcho.dev/v2/contributing/configuration#database-configuration) Database Configuration **Required Database Settings:** # PostgreSQL connection string (required) DB_CONNECTION_URI=postgresql+psycopg://username:password@host:port/database # Example for local development DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@localhost:5432/postgres # Example for production DB_CONNECTION_URI=postgresql+psycopg://honcho_user:secure_password@db.example.com:5432/honcho_prod **Database Pool Settings:** # Connection pool configuration DB_SCHEMA=public DB_POOL_SIZE=10 DB_MAX_OVERFLOW=20 DB_POOL_TIMEOUT=30 DB_POOL_RECYCLE=300 DB_POOL_PRE_PING=true DB_SQL_DEBUG=false DB_TRACING=false **Docker Compose for PostgreSQL:** # docker-compose.yml version: '3.8' services: database: image: pgvector/pgvector:pg15 environment: POSTGRES_USER: postgres POSTGRES_PASSWORD: postgres POSTGRES_DB: honcho ports: - "5432:5432" volumes: - postgres_data:/var/lib/postgresql/data - ./init.sql:/docker-entrypoint-initdb.d/init.sql volumes: postgres_data: ### [​](https://docs.honcho.dev/v2/contributing/configuration#authentication-configuration) Authentication Configuration **JWT Authentication:** # Enable/disable authentication AUTH_USE_AUTH=false # Set to true for production # JWT settings (required if AUTH_USE_AUTH is true) AUTH_JWT_SECRET=your-super-secret-jwt-key **Generate JWT Secret:** # Generate a secure JWT secret python scripts/generate_jwt_secret.py ### [​](https://docs.honcho.dev/v2/contributing/configuration#cache-configuration) Cache Configuration Honcho supports Redis caching to improve performance by caching frequently accessed data like peers, sessions, and working representations. Caching also includes lock mechanisms to prevent cache stampede scenarios. **Redis Cache Settings:** # Enable/disable Redis caching CACHE_ENABLED=false # Set to true to enable caching # Redis connection CACHE_URL=redis://localhost:6379/0?suppress=true # Cache namespace and TTL CACHE_NAMESPACE=honcho # Prefix for all cache keys CACHE_DEFAULT_TTL_SECONDS=300 # How long items stay in cache (5 minutes) # Lock settings for preventing cache stampede CACHE_DEFAULT_LOCK_TTL_SECONDS=5 # Lock duration when fetching from DB on cache miss **When to Enable Caching:** * High-traffic production environments * Applications with many repeated reads of the same data * When you need to reduce database load **Note:** Caching requires a Redis instance. You can run Redis locally with Docker: docker run -d -p 6379:6379 redis:latest [​](https://docs.honcho.dev/v2/contributing/configuration#llm-provider-configuration) LLM Provider Configuration ------------------------------------------------------------------------------------------------------------------- Honcho supports multiple LLM providers for different tasks. API keys are configured in the `[llm]` section, while specific features use their own configuration sections. ### [​](https://docs.honcho.dev/v2/contributing/configuration#api-keys) API Keys All provider API keys use the `LLM_` prefix: # Provider API Keys LLM_ANTHROPIC_API_KEY=your-anthropic-api-key LLM_OPENAI_API_KEY=your-openai-api-key LLM_GEMINI_API_KEY=your-gemini-api-key LLM_GROQ_API_KEY=your-groq-api-key # OpenAI-compatible endpoints LLM_OPENAI_COMPATIBLE_API_KEY=your-api-key LLM_OPENAI_COMPATIBLE_BASE_URL=https://your-openai-compatible-endpoint.com ### [​](https://docs.honcho.dev/v2/contributing/configuration#general-llm-settings) General LLM Settings # Default settings for all LLM calls LLM_DEFAULT_MAX_TOKENS=2500 # Embedding provider (used when EMBED_MESSAGES=true) LLM_EMBEDDING_PROVIDER=openai # Options: openai, gemini ### [​](https://docs.honcho.dev/v2/contributing/configuration#feature-specific-model-configuration) Feature-Specific Model Configuration Different features can use different providers and models: **Dialectic API:** The Dialectic API provides theory-of-mind informed responses by integrating long-term facts with current context. # Main dialectic model (default: Anthropic) DIALECTIC_PROVIDER=anthropic DIALECTIC_MODEL=claude-sonnet-4-20250514 DIALECTIC_MAX_OUTPUT_TOKENS=2500 DIALECTIC_THINKING_BUDGET_TOKENS=1024 # Only used with Anthropic provider DIALECTIC_CONTEXT_WINDOW_SIZE=100000 # Maximum context window tokens # Query generation for dialectic searches DIALECTIC_PERFORM_QUERY_GENERATION=false # Enable query generation for semantic search DIALECTIC_QUERY_GENERATION_PROVIDER=groq DIALECTIC_QUERY_GENERATION_MODEL=llama-3.1-8b-instant # Semantic search settings DIALECTIC_SEMANTIC_SEARCH_TOP_K=10 # Number of results to retrieve DIALECTIC_SEMANTIC_SEARCH_MAX_DISTANCE=0.85 # Maximum distance for relevance **Deriver (Theory of Mind):** The Deriver is a background processing system that extracts facts from messages and builds theory-of-mind representations of peers. # LLM settings for deriver DERIVER_PROVIDER=google DERIVER_MODEL=gemini-2.5-flash-lite DERIVER_MAX_OUTPUT_TOKENS=10000 DERIVER_THINKING_BUDGET_TOKENS=1024 # Only used with Anthropic provider DERIVER_MAX_INPUT_TOKENS=23000 # Maximum input tokens for deriver # Worker settings DERIVER_WORKERS=1 # Number of background worker processes DERIVER_POLLING_SLEEP_INTERVAL_SECONDS=1.0 # Time between queue checks DERIVER_STALE_SESSION_TIMEOUT_MINUTES=5 # Timeout for stale sessions # Queue management DERIVER_QUEUE_ERROR_RETENTION_SECONDS=2592000 # Keep errored items for 30 days # Working representation settings DERIVER_WORKING_REPRESENTATION_MAX_OBSERVATIONS=50 # Max observations stored DERIVER_REPRESENTATION_BATCH_MAX_TOKENS=4096 # Max tokens per batch **Peer Card:** Peer cards are short, structured summaries of peer identity and characteristics. # Enable/disable peer card generation PEER_CARD_ENABLED=true # LLM settings for peer card generation PEER_CARD_PROVIDER=openai PEER_CARD_MODEL=gpt-5-nano-2025-08-07 PEER_CARD_MAX_OUTPUT_TOKENS=4000 # Includes thinking tokens for GPT-5 models **Summary Generation:** Session summaries provide compressed context for long conversations. Honcho creates two types: short summaries (frequent) and long summaries (comprehensive). # Enable/disable summarization SUMMARY_ENABLED=true # LLM settings for summary generation SUMMARY_PROVIDER=openai SUMMARY_MODEL=gpt-4o-mini-2024-07-18 SUMMARY_MAX_TOKENS_SHORT=1000 # Max tokens for short summaries SUMMARY_MAX_TOKENS_LONG=4000 # Max tokens for long summaries SUMMARY_THINKING_BUDGET_TOKENS=512 # Only used with Anthropic provider # Summary frequency thresholds SUMMARY_MESSAGES_PER_SHORT_SUMMARY=20 # Create short summary every N messages SUMMARY_MESSAGES_PER_LONG_SUMMARY=60 # Create long summary every N messages ### [​](https://docs.honcho.dev/v2/contributing/configuration#default-provider-usage) Default Provider Usage By default, Honcho uses: * **Anthropic** (Claude) for dialectic API responses * **Groq** for query generation (fast, cost-effective) * **Google** (Gemini) for theory of mind derivation * **OpenAI** (GPT) for peer cards and summarization * **OpenAI** for embeddings (if `EMBED_MESSAGES=true`) You only need to set the API keys for the providers you plan to use. All providers are configurable per feature. [​](https://docs.honcho.dev/v2/contributing/configuration#additional-features-configuration) Additional Features Configuration --------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v2/contributing/configuration#dream-processing) Dream Processing Dream processing consolidates and refines peer representations during idle periods, similar to how human memory consolidation works during sleep. **Dream Settings:** # Enable/disable dream processing DREAM_ENABLED=true # Trigger thresholds DREAM_DOCUMENT_THRESHOLD=50 # Minimum documents to trigger a dream DREAM_IDLE_TIMEOUT_MINUTES=60 # Minutes of inactivity before dream can start DREAM_MIN_HOURS_BETWEEN_DREAMS=8 # Minimum hours between dreams for a peer # Dream types to enable DREAM_ENABLED_TYPES=["consolidate"] # Currently supported: consolidate # LLM settings for dream processing DREAM_PROVIDER=openai DREAM_MODEL=gpt-4o-mini-2024-07-18 DREAM_MAX_OUTPUT_TOKENS=2000 ### [​](https://docs.honcho.dev/v2/contributing/configuration#webhook-configuration) Webhook Configuration Webhooks allow you to receive real-time notifications when events occur in Honcho (e.g., new messages, session updates). **Webhook Settings:** # Webhook secret for signing payloads (optional but recommended) WEBHOOK_SECRET=your-webhook-signing-secret # Limit on webhooks per workspace WEBHOOK_MAX_WORKSPACE_LIMIT=10 ### [​](https://docs.honcho.dev/v2/contributing/configuration#metrics-collection) Metrics Collection Enable metrics collection for monitoring Honcho performance and usage. **Metrics Settings:** # Enable/disable metrics collection METRICS_ENABLED=false # Namespace for metrics (used in metric names) METRICS_NAMESPACE=honcho [​](https://docs.honcho.dev/v2/contributing/configuration#monitoring-configuration) Monitoring Configuration --------------------------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v2/contributing/configuration#sentry-error-tracking) Sentry Error Tracking **Sentry Settings:** # Enable/disable Sentry error tracking SENTRY_ENABLED=false # Sentry configuration SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id SENTRY_RELEASE=2.4.0 # Optional: track which version errors come from SENTRY_ENVIRONMENT=production # Environment name (development, staging, production) # Sampling rates (0.0 to 1.0) SENTRY_TRACES_SAMPLE_RATE=0.1 # 10% of transactions tracked SENTRY_PROFILES_SAMPLE_RATE=0.1 # 10% of transactions profiled [​](https://docs.honcho.dev/v2/contributing/configuration#environment-specific-examples) Environment-Specific Examples ------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v2/contributing/configuration#development-configuration) Development Configuration **config.toml for development:** [app] LOG_LEVEL = "DEBUG" SESSION_OBSERVERS_LIMIT = 10 EMBED_MESSAGES = false [db] CONNECTION_URI = "postgresql+psycopg://postgres:postgres@localhost:5432/honcho_dev" POOL_SIZE = 5 [auth] USE_AUTH = false [cache] ENABLED = false [dialectic] PROVIDER = "anthropic" MODEL = "claude-sonnet-4-20250514" PERFORM_QUERY_GENERATION = false MAX_OUTPUT_TOKENS = 2500 [deriver] WORKERS = 1 PROVIDER = "google" MODEL = "gemini-2.5-flash-lite" [peer_card] ENABLED = true PROVIDER = "openai" MODEL = "gpt-5-nano-2025-08-07" [summary] ENABLED = true PROVIDER = "openai" MODEL = "gpt-4o-mini-2024-07-18" MAX_TOKENS_SHORT = 1000 MAX_TOKENS_LONG = 4000 [dream] ENABLED = true [webhook] MAX_WORKSPACE_LIMIT = 10 [metrics] ENABLED = false [sentry] ENABLED = false **Environment variables for development:** # .env.development LOG_LEVEL=DEBUG DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@localhost:5432/honcho_dev AUTH_USE_AUTH=false CACHE_ENABLED=false # LLM Provider API Keys LLM_ANTHROPIC_API_KEY=your-dev-anthropic-key LLM_OPENAI_API_KEY=your-dev-openai-key LLM_GEMINI_API_KEY=your-dev-gemini-key ### [​](https://docs.honcho.dev/v2/contributing/configuration#production-configuration) Production Configuration **config.toml for production:** [app] LOG_LEVEL = "WARNING" SESSION_OBSERVERS_LIMIT = 10 EMBED_MESSAGES = true [db] CONNECTION_URI = "postgresql+psycopg://honcho_user:secure_password@prod-db:5432/honcho_prod" POOL_SIZE = 20 MAX_OVERFLOW = 40 [auth] USE_AUTH = true [cache] ENABLED = true URL = "redis://redis:6379/0" DEFAULT_TTL_SECONDS = 300 [dialectic] PROVIDER = "anthropic" MODEL = "claude-sonnet-4-20250514" PERFORM_QUERY_GENERATION = false MAX_OUTPUT_TOKENS = 2500 [deriver] WORKERS = 4 PROVIDER = "google" MODEL = "gemini-2.5-flash-lite" [peer_card] ENABLED = true PROVIDER = "openai" MODEL = "gpt-5-nano-2025-08-07" [summary] ENABLED = true PROVIDER = "openai" MODEL = "gpt-4o-mini-2024-07-18" MAX_TOKENS_SHORT = 1000 MAX_TOKENS_LONG = 4000 [dream] ENABLED = true PROVIDER = "openai" MODEL = "gpt-4o-mini-2024-07-18" [webhook] MAX_WORKSPACE_LIMIT = 10 [metrics] ENABLED = true [sentry] ENABLED = true ENVIRONMENT = "production" TRACES_SAMPLE_RATE = 0.1 PROFILES_SAMPLE_RATE = 0.1 **Environment variables for production:** # .env.production LOG_LEVEL=WARNING DB_CONNECTION_URI=postgresql+psycopg://honcho_user:secure_password@prod-db:5432/honcho_prod # Authentication AUTH_USE_AUTH=true AUTH_JWT_SECRET=your-super-secret-jwt-key # Cache CACHE_ENABLED=true CACHE_URL=redis://redis:6379/0 # LLM Provider API Keys LLM_ANTHROPIC_API_KEY=your-prod-anthropic-key LLM_OPENAI_API_KEY=your-prod-openai-key LLM_GEMINI_API_KEY=your-prod-gemini-key LLM_GROQ_API_KEY=your-prod-groq-key # Webhooks WEBHOOK_SECRET=your-webhook-signing-secret # Monitoring SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id SENTRY_ENVIRONMENT=production [​](https://docs.honcho.dev/v2/contributing/configuration#migration-management) Migration Management ------------------------------------------------------------------------------------------------------- **Running Database Migrations:** # Check current migration status uv run alembic current # Upgrade to latest uv run alembic upgrade head # Downgrade to specific revision uv run alembic downgrade revision_id # Create new migration uv run alembic revision --autogenerate -m "Description of changes" [​](https://docs.honcho.dev/v2/contributing/configuration#troubleshooting) Troubleshooting --------------------------------------------------------------------------------------------- **Common Configuration Issues:** 1. **Database Connection Errors** * Ensure `DB_CONNECTION_URI` uses `postgresql+psycopg://` prefix * Verify database is running and accessible * Check pgvector extension is installed 2. **Authentication Issues** * Set `AUTH_USE_AUTH=true` for production * Generate and set `AUTH_JWT_SECRET` if authentication is enabled * Use `python scripts/generate_jwt_secret.py` to create a secure secret 3. **LLM Provider Issues** * Verify API keys are set correctly * Check model names match provider specifications * Ensure provider is enabled in configuration 4. **Deriver Issues** * Increase `DERIVER_WORKERS` for better performance * Check `DERIVER_STALE_SESSION_TIMEOUT_MINUTES` for session cleanup * Monitor background processing logs This configuration guide covers all the settings available in Honcho. Always use environment-specific configuration files and never commit sensitive values like API keys or JWT secrets to version control. [Local Environment](https://docs.honcho.dev/v2/contributing/self-hosting) [License](https://docs.honcho.dev/v2/contributing/license) ⌘I --- # Get Or Create App - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-or-create-app#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation apps Get Or Create App [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const app = await client.apps.getOrCreate('name'); console.log(app.id); } main(); 200 422 { "id": "", "name": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } GET http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / get\_or\_create / {name} Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const app = await client.apps.getOrCreate('name'); console.log(app.id); } main(); 200 422 { "id": "", "name": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-or-create-app#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-or-create-app#parameter-name) name string required Name of the app to get or create #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-or-create-app#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-or-create-app#response-name) name string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-or-create-app#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-or-create-app#response-metadata) metadata Metadata · object [Create App](https://docs.honcho.dev/v1/api-reference/endpoint/apps/create-app) [Get Sessions](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-sessions) ⌘I --- # Summarizer - Honcho [Skip to main content](https://docs.honcho.dev/v2/documentation/core-concepts/summarizer#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Core Concepts Summarizer [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [Creating Summaries](https://docs.honcho.dev/v2/documentation/core-concepts/summarizer#creating-summaries) * [Retrieving Summaries](https://docs.honcho.dev/v2/documentation/core-concepts/summarizer#retrieving-summaries) Almost all agents require, in addition to personalization and memory, a way to quickly prime a context window with a summary of the conversation (in Honcho, this is equivalent to a `session`). The general strategy for summarization is to combine a list of recent messages verbatim with a compressed LLM-generated summary of the older messages not included. Implementing this correctly, in such a way that the resulting context is: * Exhaustive: the combination of recent messages and summary should cover the entire conversation * Dynamically sized: the tokens used on both summary and recent messages should be malleable based on desired token usage * Performant: while creation of the summary by LLM introduces necessary latency, this should never add latency to an arbitrary end-user request …is a non-trivial problem. Summarization should not be necessary to re-implement for every new agent you build, so Honcho comes with a built-in solution. ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/summarizer#creating-summaries) Creating Summaries Honcho already has an asynchronous task queue for the purpose of deriving facts from messages. This is the ideal place to create summaries where they won’t add latency to a message. Currently, Honcho has two configurable summary types: * Short summaries: by default, enqueued every 20 messages and given a token limit of 1000 * Long summaries: by default, enqueued every 60 messages and given a token limit of 4000 Both summaries are designed to be exhaustive: when enqueued, they are given the _prior_ summary of their type plus every message after that summary. This recursive compression process naturally biases the summary towards recent messages while still covering the entire conversation. For example, if message 160 in a conversation triggers a short summary, as it would with default settings, the summary task would retrieve the prior short summary (message 140) plus messages 141-160. It would then produce a summary of messages 0-160 and store that in the short summary slot on the session. Every session has a single slot for each summary type: new summaries replace old ones. It’s important to keep in mind that summary tasks run in the background and are not guaranteed to complete before the next message. However, they are guaranteed to complete in order, so that if a user saves 100 messages in a single batch, the short summary will first be created for messages 0-20, then 21-40, and so on, in our desired recursive way. ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/summarizer#retrieving-summaries) Retrieving Summaries Summaries are retrieved from the session by the `get_context` method. This method has two parameters: * `summary`: A boolean indicating whether to include the summary in the return type. The default is true. * `tokens`: An integer indicating the maximum number of tokens to use for the context. **If not provided, `get_context` will retrieve as many tokens as are required to create exhaustive conversation coverage.** The return type is simply a list of recent messages and a summary if the flag is used. These two components are dynamically sized based on the token limit. Combined, they will always be below the given token limit. Honcho reserves 60% of the context size for recent messages and 40% for the summary. There’s a critical trade-off to understand between exhaustiveness and token usage. Let’s go through some scenarios: * If the _last message_ contains more tokens than the context token limit, no summary _or_ message list is possible — both will be empty. * If the _last few messages_ contain more tokens than the context token limit, no summary is possible — the context will only contain the last 1 or 2 messages that fit in the token limit. * If the summaries contain more tokens than the context token limit, no summary is possible — the context will only contain the X most recent messages that fit in the token limit. Note that while summaries will often be smaller than their token limits, avoiding this scenario means passing a higher token limit than the Honcho-configured summary size(s). For this reason, the default token limit for `get_context` is a few times larger than the configured long summary size. The above scenarios indicate where summarization is not possible — therefore, the context retrieved will almost certainly **not** be exhaustive. Sometimes, gaps in context aren’t an issue. In these cases, it’s best to pass a reasonable token limit depending on your needs. Other cases demand exhaustive context — don’t pass a token limit and just let Honcho retrieve the ideal combination of summary and recent messages. Finally, if you don’t care about the conversation at large and just want the last few messages, set `summary` to false and `tokens` to some multiple of your desired message count. Note that context messages are not paginated, so there’s a hard limit on the number of messages that can be retrieved (currently 100,000 tokens). As a final note, remember that summaries are generated asynchronously and therefore may not be available immediately. If you batch-save a large number of messages, assume that summaries will not be available until those messages are processed, which can take seconds to minutes depending on the number of messages and the configured LLM provider. Exhaustive `get_context` calls performed during this time will likely just return the messages in the session. [Configure Reasoning](https://docs.honcho.dev/v2/documentation/core-concepts/configuration) [Terminology](https://docs.honcho.dev/v2/documentation/core-concepts/glossary) ⌘I --- # Update App - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/apps/update-app#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation apps Update App [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const app = await client.apps.update('app_id'); console.log(app.id); } main(); 200 422 { "id": "", "name": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } PUT http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const app = await client.apps.update('app_id'); console.log(app.id); } main(); 200 422 { "id": "", "name": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/update-app#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/update-app#parameter-app-id) app\_id string required ID of the app to update #### Body application/json Updated app parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/update-app#body-name-one-of-0) name string | null [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/update-app#body-metadata-one-of-0) metadata Metadata · object #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/update-app#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/update-app#response-name) name string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/update-app#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/apps/update-app#response-metadata) metadata Metadata · object [Get All Apps](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-all-apps) [Get App By Name](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-app-by-name) ⌘I --- # Create Collection - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/collections/create-collection#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation collections Create Collection [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const collection = await client.apps.users.collections.create('app_id', 'user_id', { name: 'x' }); console.log(collection.id); } main(); 200 422 { "id": "", "name": "", "user_id": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } POST http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / collections Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const collection = await client.apps.users.collections.create('app_id', 'user_id', { name: 'x' }); console.log(collection.id); } main(); 200 422 { "id": "", "name": "", "user_id": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/create-collection#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/create-collection#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/create-collection#parameter-user-id) user\_id string required ID of the user #### Body application/json Collection creation parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/create-collection#body-name) name string required Required string length: `1 - 100` [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/create-collection#body-metadata) metadata Metadata · object #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/create-collection#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/create-collection#response-name) name string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/create-collection#response-user-id) user\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/create-collection#response-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/create-collection#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/create-collection#response-metadata) metadata Metadata · object [Get Collections](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collections) [Get Collection By Name](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection-by-name) ⌘I --- # Terminology - Honcho [Skip to main content](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Core Concepts Terminology [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [AI Development Basics](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#ai-development-basics) * [LLM (Large Language Model)](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#llm-large-language-model) * [Prompt](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#prompt) * [Token](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#token) * [Context Window](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#context-window) * [Embedding](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#embedding) * [Semantic Search](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#semantic-search) * [Agent](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#agent) * [Honcho Terms](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#honcho-terms) * [Global Representation](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#global-representation) * [Local Representation](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#local-representation) * [Cognitive Science Terms](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#cognitive-science-terms) * [Theory of Mind](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#theory-of-mind) * [Social Cognition](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#social-cognition) * [Cognitive Architecture](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#cognitive-architecture) * [Predictive Coding](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#predictive-coding) [​](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#ai-development-basics) AI Development Basics ------------------------------------------------------------------------------------------------------------------- Essential terms for developers new to building AI applications. #### [​](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#llm-large-language-model) LLM (Large Language Model) The AI model that generates text responses, like GPT-4, Claude, or Llama. Think of it as the “brain” that powers your chatbot or AI assistant. #### [​](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#prompt) Prompt The text you send to an AI model to get a response. This includes user messages, system instructions, and any context you provide. #### [​](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#token) Token How AI models count and limit text. Roughly 1 token = 0.75 words. Models have token limits (like 4,000 or 128,000 tokens) that determine how much text they can process at once. #### [​](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#context-window) Context Window The maximum amount of text an AI model can “remember” in one conversation. Once you exceed this limit, the model starts “forgetting” earlier parts of the conversation. #### [​](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#embedding) Embedding Converting text into numerical vectors that computers can understand and compare. Enables “smart search” that finds similar content based on meaning, not just keywords. #### [​](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#semantic-search) Semantic Search Search based on meaning rather than exact keyword matching, often using embeddings. #### [​](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#agent) Agent An AI system that can take actions and make decisions, not just generate text responses. Agents can use tools, call APIs, and interact with external systems. [​](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#honcho-terms) Honcho Terms ------------------------------------------------------------------------------------------------- #### [​](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#global-representation) Global Representation Derived context of a specific peer, synthesizing insights from interactions across all sessions, including arbitrary data ingested by this specific peer. With arbitrary data, a global representation can be made independent of sessions. #### [​](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#local-representation) Local Representation One peer’s persistent context of another based on observed interactions/messages. [​](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#cognitive-science-terms) Cognitive Science Terms ----------------------------------------------------------------------------------------------------------------------- Cognitive science terms that are used throughout the inspiration and implementation of Honcho #### [​](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#theory-of-mind) Theory of Mind The ability of a computer to understand, remember, and interact with its own mind, enabling it to form representations of the world and make decisions based on its own knowledge and behavior. #### [​](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#social-cognition) Social Cognition The mental processes by which we perceive, interpret, and respond to information about others and social situations. It includes the encoding, storage, retrieval, and application of social knowledge. #### [​](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#cognitive-architecture) Cognitive Architecture In CogSci, frameworks describing fixed structures & mechanisms underlying human cognition. Such frameworks aim to explain how various components of the mind—perception, memory, reasoning, learning, etc—combine to produce intelligent behavior across diverse environments. In AI, it’s a computational implementation of these theories—a designed framework to replicate human cognitive functions. #### [​](https://docs.honcho.dev/v2/documentation/core-concepts/glossary#predictive-coding) Predictive Coding A theory in CogSci proposing the brain is an active prediction machine, continually generating & updating internal world models to anticipate sensory input, rather than passively receiving it—closely linked to Bayesian brain hypotheses, which hold that the brain interprets the world probabilistically, weighing prior knowledge against new evidence to minimize uncertainty. [Summarizer](https://docs.honcho.dev/v2/documentation/core-concepts/summarizer) [Dashboard Overview](https://docs.honcho.dev/v2/documentation/reference/platform) ⌘I --- # Storing Data - Honcho [Skip to main content](https://docs.honcho.dev/v2/documentation/core-concepts/features/storing-data#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Core Concepts Storing Data [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [Chat Bots](https://docs.honcho.dev/v2/documentation/core-concepts/features/storing-data#chat-bots) The most basic building block of Honcho’s data model is the `Message` object. A `Message` is sent by a `Peer` and saved in a `Session` Python TypeScript from honcho import Honcho honcho = Honcho() peer = honcho.peer("sample-peer") session = honcho.session("sample-session") message = peer.message("Hello, world!") session.add_messages([message]) Once a `Message` is saved in Honcho, it will kick off a background task that looks at the new data to generate insights about the `Peer` that sent the `Message` This is the default behavior of Honcho and can be turned off by [configuring the Peer or Session](https://docs.honcho.dev/v2/documentation/core-concepts/configuration) This pattern of having a Peer, Session, and Messages is highly flexible and works for many different use cases and agent setups. Some use cases may only need a single Peer, but many Sessions. Others will only use a single `Session` for their entire app. These are flexible components that work in any situation. [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/storing-data#chat-bots) Chat Bots -------------------------------------------------------------------------------------------------------- A common use case for Honcho to is to build a chatbot like ChatGPT or Claude. In this case you can simply * Make a `Peer` for the User * Make a `Peer` for the AI Then you can make a `Session` for each thread of conversation and save `Messages` from the user and assistant in each turn of conversation [Architecture](https://docs.honcho.dev/v2/documentation/core-concepts/architecture) [Dialectic Endpoint](https://docs.honcho.dev/v2/documentation/core-concepts/features/dialectic-endpoint) ⌘I --- # Honcho - Honcho [Skip to main content](https://docs.honcho.dev/v2/documentation/introduction/overview#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Introduction Honcho [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [How It Works](https://docs.honcho.dev/v2/documentation/introduction/overview#how-it-works) * [Get Context](https://docs.honcho.dev/v2/documentation/introduction/overview#get-context) * [Search](https://docs.honcho.dev/v2/documentation/introduction/overview#search) * [Working Representation](https://docs.honcho.dev/v2/documentation/introduction/overview#working-representation) * [Dialectic API](https://docs.honcho.dev/v2/documentation/introduction/overview#dialectic-api) * [Getting Started](https://docs.honcho.dev/v2/documentation/introduction/overview#getting-started) * [Community & Support](https://docs.honcho.dev/v2/documentation/introduction/overview#community-%26-support) Honcho is an AI-native memory library for building agents with [state-of-the-art](https://blog.plasticlabs.ai/research/Introducing-Neuromancer-XR) long-term memory. Agents using Honcho have perfect recall with a wide variety of tools to traverse their history and get the exact context they need when they need it. It then goes beyond basic memory by reasoning about the stored history to expand the latent information available to your agent. Agents using Honcho will understand who they are, who they are interacting with, what happened, and when it happened — all without you having to think about it. Use it to build * Highly personalized experiences * Agents with social cognition * Agents with rich identity that evolve over time * Multi-agent systems with complex social dynamics # Start simple by just adding messages session.add_messages([alice.message("I learn best with examples")]) # Honcho will automatically reason about the message to generate insights about Alice # Get insights by chatting with the agent insight = peer.chat("How should I explain this concept?") # > "This user learns best through concrete examples..." Designed for developers and agents alike: * **Natural Language Queries**: Chat with Honcho in natural language via the [Dialectic API](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#dialectic-api) to get insights about your users and agents * **Automatic Context Management**: Smart conversation summaries to have infinite chats * **Native multi-agent support**: Sessions can natively have as many participants as you need * **Agent-first interfaces**: MCP connections and APIs designed for agents to consume and use as tools * **Provider Agnostic**: Works with any LLM or Agent Framework [​](https://docs.honcho.dev/v2/documentation/introduction/overview#how-it-works) How It Works ------------------------------------------------------------------------------------------------ High Level Diagram ![High Level Honcho Diagram](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/images/overview/honcho-overview.svg?w=2500&fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=9a4572b478bc8baa512dfc2ae401066a) At a high level Honcho works very simply: 1. Store messages sent by users and agents in Honcho 2. Honcho reasons about the messages to generate insights about each entity in the system 3. At runtime your agents can leverage insights from Honcho to get the exact context they need There are several API endpoints to leverage the memory & insights in Honcho. ### [​](https://docs.honcho.dev/v2/documentation/introduction/overview#get-context) Get Context This is the easiest way to leverage Honcho. simply call get context and get the most relevant information for your conversation. This endpoint is highly customizable so you can specify parameters such as: * A number of tokens you want * An option to include summaries of the conversation * An option to get a profile of a specific user (Peer Card & Representation) ### [​](https://docs.honcho.dev/v2/documentation/introduction/overview#search) Search This endpoint lets you search across Honcho for relevant messages using a hybrid search strategy that combines full-text and semantic search. You can optionally scope the endpoint to a specific workspace, peer, or session. ### [​](https://docs.honcho.dev/v2/documentation/introduction/overview#working-representation) Working Representation This endpoint gives you a snapshot of a user or what we call a **Representation**. Essentially, a list of explicit and deductive facts about the user that are relevant to the current conversation. Plug this into your prompt to get a quick overview of the user. ### [​](https://docs.honcho.dev/v2/documentation/introduction/overview#dialectic-api) Dialectic API This endpoint lets you chat with Honcho about any entity in your system. Honcho will leverage what it has remembered and learned about the entity to provide in-context actionable insights. This is especially helpful when you want your agent to back-channel with Honcho to change its behavior at runtime. Example Queries: * “What’s the best way to explain technical concepts to this user?” * “Is this user more task-oriented or relationship-oriented?” * “What time of day is this user most engaged?” * “How does this user prefer to receive feedback?” * “What are this user’s core values based on our conversations?” [​](https://docs.honcho.dev/v2/documentation/introduction/overview#getting-started) Getting Started ------------------------------------------------------------------------------------------------------ Ready to integrate Honcho into your application? Quickstart Guide ---------------- Get up and running with Honcho in minutes Core Concepts ------------- Understand Honcho’s fundamental concepts [​](https://docs.honcho.dev/v2/documentation/introduction/overview#community-&-support) Community & Support -------------------------------------------------------------------------------------------------------------- * **GitHub**: [plastic-labs/honcho](https://github.com/plastic-labs/honcho) * **Discord**: [Join our community](http://discord.gg/honcho) * **Issues**: Report bugs and request features on GitHub [Quickstart](https://docs.honcho.dev/v2/documentation/introduction/quickstart) ⌘I --- # Delete Collection - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/collections/delete-collection#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation collections Delete Collection [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const collection = await client.apps.users.collections.delete('app_id', 'user_id', 'collection_id'); console.log(collection); } main(); 422 { "detail": [\ {\ "loc": [\ ""\ ],\ "msg": "",\ "type": ""\ }\ ] } DELETE http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / collections / {collection\_id} Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const collection = await client.apps.users.collections.delete('app_id', 'user_id', 'collection_id'); console.log(collection); } main(); 422 { "detail": [\ {\ "loc": [\ ""\ ],\ "msg": "",\ "type": ""\ }\ ] } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/delete-collection#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/delete-collection#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/delete-collection#parameter-user-id) user\_id string required ID of the user [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/delete-collection#parameter-collection-id) collection\_id string required ID of the collection to delete #### Response 200 application/json Successful Response [Update Collection](https://docs.honcho.dev/v1/api-reference/endpoint/collections/update-collection) [Get Documents](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-documents) ⌘I --- # Local vs Global Representations - Honcho [Skip to main content](https://docs.honcho.dev/v2/documentation/core-concepts/features/local-vs-global#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Core Concepts Local vs Global Representations [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) One of the unique affordances of Honcho is that it allows developers to model directional relationships between Peers. What I mean by this is you can model how one `Peer` thinks about another `Peer`. There are many use cases where you don’t want every agent or human to know everything about another user such as games or multi-agent workflows. To illustrate this, the following examples shows 2 conversations. Conversation #1 (With Bob and Alice) Alice: I had a great breakfast today. Bob: What did you eat? Alice: I had pancakes and eggs and bacon Conversation #2 (With Alice and Charlie) Alice: I actually didn't eat any breakfast today. Charlie: Oh that's too bad. Alice: But I lied to Bob and told him I did, so back me up if you see them. Alice told Bob a lie in this conversation. If we stored both of these conversations in Honcho with Alice, Bob, and Charlie as `Peers` and let them use Honcho to get insights on each other then Bob would immediately know this deception. For example: Python # Bob could run alice.chat("What did Alice eat today?") # Response: Alice did not eat anything today This is a problem. Bob shouldn’t be able to know everything about Alice in this situation. So to support these situations we support what we call **Local Representations**. By default insights generated for a `Peer` are scoped globally. This means every message sent by that `Peer` in any conversation updates the same representation of that `Peer`. However, we can enable **Local Representations** so Bob can form a representation Alice based only on what they observe Alice do. This feature is illustrated in the graphic below: ![Peer Representations](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/local-vs-global-reps.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=99eae99847a6919fd8b4db0594b7a144) We can enable local representation for a `Peer` by setting `observe_others=True`. This is shown in the [Configure Reasoning](https://docs.honcho.dev/v2/documentation/core-concepts/configuration) page. Now if we used Bob’s local representation of Alice then Bob would only get insights on what they’ve seen Alice say to them. bob.chat(target="alice", query="What did Alice eat today?") # Response: Alice ate pancakes, eggs, and bacon Local Representations are turned off by default [Queue Status](https://docs.honcho.dev/v2/documentation/core-concepts/features/queue-status) [Configure Reasoning](https://docs.honcho.dev/v2/documentation/core-concepts/configuration) ⌘I --- # LangGraph - Honcho [Skip to main content](https://docs.honcho.dev/v2/integrations/langgraph#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Integrations LangGraph [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [What We’re Building](https://docs.honcho.dev/v2/integrations/langgraph#what-we%E2%80%99re-building) * [Setup](https://docs.honcho.dev/v2/integrations/langgraph#setup) * [Initialize Clients](https://docs.honcho.dev/v2/integrations/langgraph#initialize-clients) * [Define LangGraph State](https://docs.honcho.dev/v2/integrations/langgraph#define-langgraph-state) * [Build the LangGraph](https://docs.honcho.dev/v2/integrations/langgraph#build-the-langgraph) * [Understanding get\_context()](https://docs.honcho.dev/v2/integrations/langgraph#understanding-get-context) * [Chat Loop](https://docs.honcho.dev/v2/integrations/langgraph#chat-loop) * [Next Steps](https://docs.honcho.dev/v2/integrations/langgraph#next-steps) * [Related Resources](https://docs.honcho.dev/v2/integrations/langgraph#related-resources) Integrate Honcho with LangGraph to build a conversational AI agent that maintains memory across sessions. This guide shows you how to use Honcho’s memory layer with LangGraph’s orchestration. The full code is available on [GitHub](https://github.com/plastic-labs/honcho/tree/main/examples/langgraph) with examples in both [Python](https://github.com/plastic-labs/honcho/blob/main/examples/langgraph/python/main.py) and [TypeScript](https://github.com/plastic-labs/honcho/blob/main/examples/langgraph/typescript/main.ts) [​](https://docs.honcho.dev/v2/integrations/langgraph#what-we%E2%80%99re-building) What We’re Building --------------------------------------------------------------------------------------------------------- We’ll create a conversational agent that remembers and reasons over past exchanges with the user. Here’s how the pieces fit together: * **LangGraph** orchestrates the conversation flow * **Honcho** stores messages and retrieves relevant context * **Your LLM** generates responses using Honcho’s formatted context The key benefit: You don’t manually manage conversation history, token limits, or message formatting. Honcho handles memory so you can focus on your agent’s logic. This tutorial demonstrates a simple linear conversation flow to show how Honcho integrates with LangGraph. For production applications, you’ll likely want to add LangGraph features like conditional routing, tool calling, and multi-agent orchestration. [​](https://docs.honcho.dev/v2/integrations/langgraph#setup) Setup --------------------------------------------------------------------- Install required packages: Python (uv) Python (pip) TypeScript (npm) TypeScript (yarn) TypeScript (pnpm) uv add honcho-ai langgraph langchain-core openai python-dotenv This tutorial uses OpenAI, but Honcho works with any LLM provider. Create a `.env` file with your API keys: OPENAI_API_KEY=your_openai_key This tutorial uses the Honcho demo server at [https://demo.honcho.dev](https://demo.honcho.dev/) which runs a small instance of Honcho on the latest version. For production, get your Honcho API key at [app.honcho.dev](https://app.honcho.dev/) . For local development, use `environment="local"`. [​](https://docs.honcho.dev/v2/integrations/langgraph#initialize-clients) Initialize Clients ----------------------------------------------------------------------------------------------- Python TypeScript import os from dotenv import load_dotenv from typing_extensions import TypedDict from honcho import Honcho, Peer, Session from openai import OpenAI from langgraph.graph import StateGraph, START, END load_dotenv() # Initialize Honcho honcho = Honcho() # Initialize OpenAI llm = OpenAI(api_key=os.environ.get("OPENAI_API_KEY")) [​](https://docs.honcho.dev/v2/integrations/langgraph#define-langgraph-state) Define LangGraph State ------------------------------------------------------------------------------------------------------- Define your state schema to pass data through the graph. The state stores Honcho objects directly along with the current user message and assistant response. Before proceeding, it’s important to understand Honcho’s core concepts (`Peers` and `Sessions`). Review the [Honcho Architecture](https://docs.honcho.dev/v2/documentation/core-concepts/architecture) to familiarize yourself with these primitives. Python TypeScript class State(TypedDict): user_message: str assistant_response: str user: Peer assistant: Peer session: Session [​](https://docs.honcho.dev/v2/integrations/langgraph#build-the-langgraph) Build the LangGraph ------------------------------------------------------------------------------------------------- Define your chatbot logic, using Honcho to retrieve conversation context. This function demonstrates how Honcho can store messages, retrieve context, and generate responses. Python TypeScript def chatbot(state: State): user_message = state["user_message"] # Get objects from state user = state["user"] assistant = state["assistant"] session = state["session"] # Step 1: Store the user's message in the session # This adds it to Honcho's memory for future context retrieval session.add_messages([user.message(user_message)]) # Step 2: Get context in OpenAI format with token limit # get_context() retrieves relevant conversation history # tokens=2000 limits the context to 2000 tokens to manage costs and fit within model limits # to_openai() converts it to the format expected by OpenAI's API messages = session.get_context(tokens=2000).to_openai(assistant=assistant) # Step 3: Generate response using the context response = llm.chat.completions.create( model="gpt-5.1", messages=messages ) assistant_response = response.choices[0].message.content # Step 4: Store assistant response in Honcho for future context session.add_messages([assistant.message(assistant_response)]) return {"assistant_response": assistant_response} Now let’s build the LangGraph: Python TypeScript graph = StateGraph(State) \ .add_node("chatbot", chatbot) \ .add_edge(START, "chatbot") \ .add_edge("chatbot", END) \ .compile() ### [​](https://docs.honcho.dev/v2/integrations/langgraph#understanding-get-context) Understanding get\_context() The [`get_context()`](https://docs.honcho.dev/v2/documentation/core-concepts/features/get-context) method retrieves comprehensive conversation context and formats it for your LLM. It automatically: * **Manages conversation history** - Tracks all messages and determines what’s relevant * **Respects token limits** - Stays within context window constraints without manual counting * **Handles long conversations** - Combines recent detailed messages with summaries of older exchanges * **Provides `peer` understanding** - Includes representations and `peer` cards when requested The `SessionContext` object always includes fields for messages, summaries, `peer` representations, and `peer` cards. By default, only `messages` and `summary` are populated. To populate peer-specific context, pass a `peer_target` parameter: **Using `peer_target` for Context:** * **Without `peer_perspective`**: Returns Honcho’s omniscient view of `peer_target` (all observations and context) * **With `peer_perspective`**: Returns what `peer_perspective` knows about `peer_target` (perspective-based observations and context) That’s it. Call `session.get_context().to_openai(assistant)` and you get properly formatted context tailored for your assistant. **Adding System Prompts:** Since `get_context()` returns conversation messages, you can easily prepend custom system instructions. Just add your system prompt to the beginning of the messages array before sending it to your LLM: `[{"role": "system", "content": "..."}, ...context_messages]`. For more details on all available parameters, see [`get_context() documentation`](https://docs.honcho.dev/v2/documentation/core-concepts/features/get-context) [​](https://docs.honcho.dev/v2/integrations/langgraph#chat-loop) Chat Loop ----------------------------------------------------------------------------- Now we’ll create the main conversation function. To simplify logic, we initialize Honcho objects once per conversation and pass them through the LangGraph state. The `run_conversation_turn` function initializes a Honcho `Session` and `Peer` objects, passes them to the LangGraph, and returns the assistant’s response. By calling it repeatedly with the same `user_id` and in the same session, the chat builds context over time. **Production Usage:** Honcho accepts any nanoid-compatible string for `user_id` and `session_id`. You can use IDs directly from your authentication system (Auth0, Firebase, Clerk, etc.) and session management without modification.This tutorial uses hardcoded values for simplicity. Python TypeScript def run_conversation_turn(user_id: str, user_input: str, session_id: str | None = None): if not session_id: session_id = f"session_{user_id}" # Initialize Honcho objects user = honcho.peer(user_id) assistant = honcho.peer("assistant") session = honcho.session(session_id) result = graph.invoke({ "user_message": user_input, "user": user, "assistant": assistant, "session": session }) return result["assistant_response"] if __name__ == "__main__": print("Welcome to the AI Assistant! How can I help you today?") user_id = "test-user-123" while True: user_input = input("You: ") if user_input.lower() in ['quit', 'exit']: break response = run_conversation_turn(user_id, user_input) print(f"Assistant: {response}\n") [​](https://docs.honcho.dev/v2/integrations/langgraph#next-steps) Next Steps ------------------------------------------------------------------------------- Now that you have a working LangGraph integration with Honcho, you can: * **Create custom [LangChain tools](https://docs.langchain.com/oss/python/langchain/tools#customize-tool-properties) for your agent** - to fully utilize Honcho’s memory & context management features * **Build a multi-agent LangGraph** where each agent is a Honcho `Peer` with its own memory [​](https://docs.honcho.dev/v2/integrations/langgraph#related-resources) Related Resources --------------------------------------------------------------------------------------------- Get Context ----------- Learn more about retrieving and formatting conversation context MCP Integration --------------- Use Honcho in Claude Desktop with MCP [CrewAI](https://docs.honcho.dev/v2/integrations/crewai) [MCP](https://docs.honcho.dev/v2/integrations/mcp) ⌘I --- # Dialectic Endpoint - Honcho [Skip to main content](https://docs.honcho.dev/v2/documentation/core-concepts/features/dialectic-endpoint#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Core Concepts Dialectic Endpoint [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [Automatic Fact Derivation](https://docs.honcho.dev/v2/documentation/core-concepts/features/dialectic-endpoint#automatic-fact-derivation) * [Dialectic Endpoint](https://docs.honcho.dev/v2/documentation/core-concepts/features/dialectic-endpoint#dialectic-endpoint) * [Prerequisites](https://docs.honcho.dev/v2/documentation/core-concepts/features/dialectic-endpoint#prerequisites) * [Static Dialectic Call](https://docs.honcho.dev/v2/documentation/core-concepts/features/dialectic-endpoint#static-dialectic-call) * [Streaming Dialectic Call](https://docs.honcho.dev/v2/documentation/core-concepts/features/dialectic-endpoint#streaming-dialectic-call) Honcho by default runs ambient inference on top of the `message` objects you store. Those messages serve as the ground truth upon which facts about the user are derived and stored. The **Dialectic Endpoint** is the natural language interface through which insights are synthesized from those facts. We believe [intellectual respect](https://blog.plasticlabs.ai/extrusions/Extrusion-02.24) for LLMs is paramount in building effective AI agents/apps. It follows that the LLM should know better than any human what would aid them in their generation task. Thus, the Dialectic endpoint exists for flexible agent-to-agent communication. [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/dialectic-endpoint#automatic-fact-derivation) Automatic Fact Derivation ---------------------------------------------------------------------------------------------------------------------------------------------- On every message written to a session, an automatic callback is run that will reason about the conversation and store facts in a `collection` named `honcho`. This is a reserved `collection` specifically for the backend Honcho agent to interact with. [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/dialectic-endpoint#dialectic-endpoint) Dialectic Endpoint -------------------------------------------------------------------------------------------------------------------------------- The Dialectic endpoint allows you to define logic enabling your agent to talk to our agent that automatically retrieves and synthesizes facts from the collection. You can use the response as part of your reasoning process for your agent–add it to your next prompt to inject critical context about the user. This chat interface is exposed via the `peer.chat()` endpoint. It accepts a string query. Below is some example code on how this works. [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/dialectic-endpoint#prerequisites) Prerequisites ---------------------------------------------------------------------------------------------------------------------- Python TypeScript from honcho import Honcho # use the default workspace honcho = Honcho() # get/create a peer peer = honcho.peer("demo-user") # get/create a session session = honcho.session("demo-session") # (assuming some messages have been written to Honcho for the deriver to use) [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/dialectic-endpoint#static-dialectic-call) Static Dialectic Call -------------------------------------------------------------------------------------------------------------------------------------- Python TypeScript query = "What is the user's favorite way of completing the task?" answer = peer.chat(query) [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/dialectic-endpoint#streaming-dialectic-call) Streaming Dialectic Call -------------------------------------------------------------------------------------------------------------------------------------------- Python TypeScript query = "What do we know about the user?" response_stream = peer.chat(query, stream=True) for line in response_stream.iter_text(): print(line) We’ve designed the Dialectic endpoint to be infinitely flexible. We wrote an incomplete list of ideas on how to use it on our blog [here](https://blog.plasticlabs.ai/archive/ARCHIVED;-Introducing-Honcho's-Dialectic-API#how-it-works) . [Storing Data](https://docs.honcho.dev/v2/documentation/core-concepts/features/storing-data) [Get Context](https://docs.honcho.dev/v2/documentation/core-concepts/features/get-context) ⌘I --- # Architecture & Intuition - Honcho [Skip to main content](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Core Concepts Architecture & Intuition [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [Data Model](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#data-model) * [Workspaces](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#workspaces) * [Peers](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#peers) * [Sessions](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#sessions) * [Messages](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#messages) * [Reasoning Layer](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#reasoning-layer) * [Local & Global Representations](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#local-%26-global-representations) * [Summary](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#summary) * [Dialectic API](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#dialectic-api) * [Next Steps](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#next-steps) The goal of this page is to build an intuition for the primitives in Honcho and how they fit together Honcho has 2 main components that work together to manage agent identity and context. * **The Memory Layer**: The Memory layer for storing interaction history for your agents * **The Reasoning Layer**: The background processing layer that builds representations of users and agents Below we’ll deep dive into these different areas, discussing the data primitives, the flow of data through the system, artifacts Honcho produces, and how to use them. [​](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#data-model) Data Model ------------------------------------------------------------------------------------------------- Honcho has a hierarchical data model centered around the entities below. * A `Workspaces` has `Peers` & `Sessions` * A `Peer` can be in multiple `Sessions` and can send `Messages` in a `Session`. * A `Session` can have many `Peers` and stores `Messages` sent by its `Peers`. ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#workspaces) Workspaces Workspaces are the top-level containers that provide complete isolation between different applications or environments; they essentially serve as a namespace to isolate different workloads or environments **Key Features:** * **Isolation**: Complete data separation between workspaces * **Multi-tenancy**: Support multiple applications or environments * **Configuration**: Workspace-level settings and metadata * **Access Control**: Authentication scoped to workspace level **Use Cases:** * Separate development/staging/production environments * Multi-tenant SaaS applications * Different product lines or use cases * Complete data separation between teams * * * ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#peers) Peers Honcho has a Peer-Centric Architecture: Peers are the most important entity within Honcho, with everything revolving around Peers and their representations. Peers represent individual users, agents, or entities in a workspace. They are the primary subjects for memory and context management. Treating humans and agents the same lets us support arbitrary combinations of Peers for multi-agent or group chat scenarios. **Key Features:** * **Identity**: Unique identifier within a workspace * **Memory Storage**: Personal memory and context accumulation * **Configuration**: Per-peer behavioral settings * **Cross-Session Context**: Memory persists across all sessions **Use Cases:** * Individual users in chatbot applications * AI agents interacting with users or other agents * Customer profiles in support systems * Student profiles in educational platforms * NPCs in role-playing games * * * ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#sessions) Sessions Sessions represent individual conversation threads or interaction contexts between peers. **Key Features:** * **Multi-Peer**: Support multiple peers in a single session * **Temporal Boundaries**: Clear start/end to conversation threads * **Context Scoping**: Session-specific memory and context * **Configuration**: Session-level behavioral controls **Use Cases:** * Individual chat conversations * Support tickets * Meeting transcripts * Learning sessions * Single-Peer onboarding sessions where data is imported from an external source * * * ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#messages) Messages Messages are the fundamental units of interaction within sessions. They may also be used to ingest information of any kind that is not related to a specific interaction, but provides important context for a peer (emails, docs, files, etc.). Simple make a session with a single peer and structure the data as messages. **Key Features:** * **Rich Content**: Support for text, metadata, and structured data * **Attribution**: Clear association with sending peer * **Ordering**: Chronological sequence within sessions * **Processing**: Automatic background analysis and insight derivation **Message Types:** * User messages * AI responses * System notifications * Rich media content * User actions (clicked, reacted, etc.) * File uploads (PDFs, text files, JSON documents) [​](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#reasoning-layer) Reasoning Layer ----------------------------------------------------------------------------------------------------------- The raw data you store in Honcho is useful, but it’s not in a format that’s most useful for an LLM to consume. There may be too many tokens that need to be compacted, key facts about what happened may be hard to piece together because they involve messages from across different sessions, etc. To solve this problem, Honcho has a reasoning layer that continually processes incoming data to form the most informationally dense and useful representations of `Peers` that we can then expose to agents. Honcho does the following tasks in the reasoning engine. * **Fact Derivation** * **Generate Summaries** * **Generate Peer Cards** * **Dreaming** Honcho will reason about each `Message` it ingests to generate new facts and insights that are spelled out and easy to consume in an LLM prompt. We refer to this module of Honcho as the `Deriver`, because it’s constantly deriving new insights from messages. The sum total of all these generated insights are what we refer to as a `Representation`, all the data related to who and what a `Peer` is. Depending on the configuration of a `Peer` or `Session`, the deriver will behave differently and update different representations. Facts derived here are used in the Dialectic chat endpoint, get\_context endpoint, Deriver tasks are processed in parallel, but tasks affecting the same peer representation will always be processed serially in order of message creation, so as to properly understand their cumulative effect. There are two types of tasks that the deriver currently does: * **Representation Tasks**: Generate/update peer representations * **Summary Tasks**: Generate conversation summaries ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#local-&-global-representations) Local & Global Representations Peer representations are more of an abstract concept, as they are made up of various pieces of data stored throughout Honcho. There are however multiple types of representations that Honcho can produce. Honcho handles both **local** and **global** representations of Peers, where **local** representations are specific to a single Peer’s view of another Peer, while Global Representations are based on any message ever produced by a Peer. ![Peer Representations](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/local-vs-global-reps.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=99eae99847a6919fd8b4db0594b7a144) Everything is framed with regards to perspective. Alice owns her own global representation, but she also maintains a local representation of Bob based on what she observes and similarly Bob has a global representation of himself and local representation of Alice. So in the example above, when Alice sends a message to Bob it triggers an update to both Alice’s global representation of herself and Bob’s local representation of Alice. If Alice were to have another conversation with a different Peer, Nico, and sent them a message, this action would trigger an update to Alice’s Global Representation and Nico’s local representation of Alice. Bob’s local representation of Alice would not change since Bob would never receive that message. By default, local representations are disabled, but can be enabled in a Peer or Session level configuration Depending on the use case, a developer may choose to only use global representation, only use local, or a combination. ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#summary) Summary Summary tasks create conversation summaries. Periodically, a “short” summary will be created for each session as messages are added — every 20 messages by default. “Long” summaries are created every 60 messages by default and maintain a total overview of the session by including the previous summary in a recursive fashion. These summaries are accessed in the `get_context` endpoint along with recent messages, allowing developers to easily fetch everything necessary to generate the next LLM completion for an agent. The system defaults are also the checkpoints used on the managed version of Honcho hosted at [https://api.honcho.dev](https://api.honcho.dev/) [​](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#dialectic-api) Dialectic API ------------------------------------------------------------------------------------------------------- The Dialectic API is one of the most integral components of Honcho and acts as the main way to leverage Peer Representations. By using the `/chat` endpoint, developers can directly talk to Honcho about any Peer in a workspace to get insights into the psychology of a Peer and help them steer their behavior. This allows us to use this one endpoint for a wide variety of use cases. Model steering, personalization, hydrating a prompt, etc. Additionally, since the endpoint works through natural language, a developer can allow an agent to backchannel directly with Honcho, via MCP or a direct API call. Developers should frame the Dialectic as talking to an expert on the Peer rather than addressing the Peer itself, meaning: alice.chat("What is the user's mood today?") # ✅ Ideal alice.chat("What is alice's mood today?") # ✅ Works -- but make sure to consider what peer "Alice" has been saying in their messages about name/identity. alice.chat("What is your mood today?") # ❌ Likely to fail -- the dialectic agent may conflate itself and the user. Think of Dialectic Chat as an assisting agent that your main agent can consult for contextual information about any actor in your application. [​](https://docs.honcho.dev/v2/documentation/core-concepts/architecture#next-steps) Next Steps ------------------------------------------------------------------------------------------------- Platform SDK ------------ Learn how to use the SDK to interact with the data model Glossary -------- Reference for all technical terms and concepts API Reference ------------- Detailed API documentation and examples Quickstart ---------- Get started with your first integration [Vibecoding Setup](https://docs.honcho.dev/v2/documentation/introduction/vibecoding) [Storing Data](https://docs.honcho.dev/v2/documentation/core-concepts/features/storing-data) ⌘I --- # Peer Representations - Honcho [Skip to main content](https://docs.honcho.dev/v3/documentation/core-concepts/representation#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Core Concepts Peer Representations [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [What’s in a Representation?](https://docs.honcho.dev/v3/documentation/core-concepts/representation#what%E2%80%99s-in-a-representation) * [Observation & Perspective-Taking](https://docs.honcho.dev/v3/documentation/core-concepts/representation#observation-%26-perspective-taking) * [Why Representations Work](https://docs.honcho.dev/v3/documentation/core-concepts/representation#why-representations-work) * [Next Steps](https://docs.honcho.dev/v3/documentation/core-concepts/representation#next-steps) A representation is the collection of reasoning Honcho has done about a peer over time. It’s the continual learning about a peer over every message that’s been written to it. Representations evolve dynamically as new messages come in, with Honcho reasoning about them in the background. When you write messages to Honcho, the reasoning models extract premises, draw conclusions, and scaffold new conclusions as well. All of that reasoning gets stored as the peer’s representation. Think of it as Honcho’s understanding of who that peer is, what they care about, and how they behave, built through formal logic rather than simple storage. [​](https://docs.honcho.dev/v3/documentation/core-concepts/representation#what%E2%80%99s-in-a-representation) What’s in a Representation? -------------------------------------------------------------------------------------------------------------------------------------------- A peer representation is made up of several types of artifacts that Honcho generates through [_reasoning_](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning) : **Conclusions** are insights derived through formal logic. Deductive conclusions are things Honcho can be certain about based on extracted premises. Inductive conclusions identify patterns across multiple messages. Abductive conclusions infer the simplest explanations for observed behavior. For example, if a user frequently mentions work deadlines and rarely mentions hobbies, Honcho might inductively conclude they’re time-constrained or career-focused. **Summaries** capture the essence of sessions. Short summaries are generated every 20 messages by default, and long summaries every 60 messages. These help compress conversation history into dense, queryable context. **Peer cards** contain key biographical information. They essentially cache the most basic information about a peer (name, occupation, interests) to ensure the model never loses its grounding. These enable continuous improvement. Each new message refines conclusions, updates summaries, and keeps peer cards current—building a more accurate representation over time. [​](https://docs.honcho.dev/v3/documentation/core-concepts/representation#observation-&-perspective-taking) Observation & Perspective-Taking ----------------------------------------------------------------------------------------------------------------------------------------------- Honcho can build different representations based on what each peer observes. This enables sophisticated multi-peer scenarios where understanding is relative to what was actually witnessed. There are two observation modes controlled by [configuration](https://docs.honcho.dev/v3/documentation/features/advanced/configuration) : **Honcho observing peers** (`observe_me`): When enabled (default), Honcho forms a representation of the peer based on all messages they’ve sent across all sessions. This is Honcho’s understanding of that peer, built from everything they’ve said and done in your system. Set `observe_me: false` if you don’t want Honcho to reason about that peer at all. **Peers observing others** (`observe_others`): When enabled at the session level, a peer will form representations of other peers in that session based only on messages they’ve observed. If Alice and Bob are in a session together and Alice has `observe_others: true`, Alice will form a representation of Bob based solely on what Bob said in sessions Alice participated in. Alice’s representation of Bob will be completely different from Charlie’s representation of Bob if they’ve observed different interactions. In the diagram below, assume `observe_me` isn’t turned off (again, default behavior) and `observe_others` is turned on for both peers in a session that contains the peers Alice and Bob. ![](https://mintcdn.com/plasticlabs/Pwe1D9IEDkAtnMKn/images/observe_config.png?w=2500&fit=max&auto=format&n=Pwe1D9IEDkAtnMKn&q=85&s=0521fed32c7357817d679bb26b7754d4) The shared session that Alice and Bob have informs their respective representations of each other. Alice has a small set of conclusions that pertain to Bob, and Bob has a small set of conclusions that pertain to Alice. Honcho can observe the totality of each peer’s interactions, forming representations of the peers themselves, and enable peers to store conclusions about peers they interact with based only on what they witness in shared sessions. Why would you want peers observing others? So you can simulate stateful _perspectives_. If Bob participates with Alice in sessions 1 and 2, while Charlie participates with Alice in session 3, Bob’s representation of Alice will be built from sessions 1 and 2, while Charlie’s representation will only include what happened in session 3. Bob can reference shared history, inside jokes, or past conflicts that Charlie knows nothing about. Without perspective-based segmentation, all agents are omniscient—the simulation breaks down, trust falls apart, and users churn. [​](https://docs.honcho.dev/v3/documentation/core-concepts/representation#why-representations-work) Why Representations Work ------------------------------------------------------------------------------------------------------------------------------- Statefulness is simulated through reconstruction of the past. Traditional systems reconstruct by retrieving stored facts, querying semantically similar items, and hoping the LLM does the rest. Honcho reconstructs through reasoning about the past exhaustively, leaving much less to chance. Reasoning can surface insights never explicitly stated. If a user mentions they’re saving for a house in one session and complains about subscription costs in another, Honcho can conclude they’re budget-conscious without anyone saying it. Reasoning handles contradictions gracefully—when new information conflicts with old conclusions, it reconciles them instead of just accumulating more data. And reasoning enables prediction under uncertainty, inferring what’s likely true based on patterns even when data is incomplete. Humans reconstruct the past from imperfect recollections, then act on those reconstructions as if they were complete. Representations enable agents to do the same with far greater fidelity. Reasoning produces an exhaustive, explicit record of what can be concluded about a peer—giving agents complete recollection that humans can only pretend to have. That’s what makes truly stateful agents possible. [​](https://docs.honcho.dev/v3/documentation/core-concepts/representation#next-steps) Next Steps --------------------------------------------------------------------------------------------------- Get an API Key -------------- Sign up for the Honcho platform and start building Quickstart ---------- See representations in action with a working example Architecture ------------ Understand how representations fit into Honcho’s architecture Chat Endpoint ------------- Chat with Honcho about your users [Reasoning](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning) [Design Patterns](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns) ⌘I --- # Local Environment Setup - Honcho [Skip to main content](https://docs.honcho.dev/v3/contributing/self-hosting#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Self-Hosting Local Environment Setup [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Overview](https://docs.honcho.dev/v3/contributing/self-hosting#overview) * [Prerequisites](https://docs.honcho.dev/v3/contributing/self-hosting#prerequisites) * [Required Software](https://docs.honcho.dev/v3/contributing/self-hosting#required-software) * [Database Options](https://docs.honcho.dev/v3/contributing/self-hosting#database-options) * [LLM Setup](https://docs.honcho.dev/v3/contributing/self-hosting#llm-setup) * [Docker Setup (Recommended)](https://docs.honcho.dev/v3/contributing/self-hosting#docker-setup-recommended) * [1\. Clone the Repository](https://docs.honcho.dev/v3/contributing/self-hosting#1-clone-the-repository) * [2\. Set Up Environment Variables](https://docs.honcho.dev/v3/contributing/self-hosting#2-set-up-environment-variables) * [3\. Start the Services](https://docs.honcho.dev/v3/contributing/self-hosting#3-start-the-services) * [4\. Verify](https://docs.honcho.dev/v3/contributing/self-hosting#4-verify) * [Manual Setup](https://docs.honcho.dev/v3/contributing/self-hosting#manual-setup) * [1\. Clone and Install Dependencies](https://docs.honcho.dev/v3/contributing/self-hosting#1-clone-and-install-dependencies) * [2\. Set Up PostgreSQL](https://docs.honcho.dev/v3/contributing/self-hosting#2-set-up-postgresql) * [Option A: Local PostgreSQL Installation](https://docs.honcho.dev/v3/contributing/self-hosting#option-a-local-postgresql-installation) * [Option B: Docker PostgreSQL](https://docs.honcho.dev/v3/contributing/self-hosting#option-b-docker-postgresql) * [3\. Enable Extensions](https://docs.honcho.dev/v3/contributing/self-hosting#3-enable-extensions) * [4\. Configure Environment](https://docs.honcho.dev/v3/contributing/self-hosting#4-configure-environment) * [5\. Run Database Migrations](https://docs.honcho.dev/v3/contributing/self-hosting#5-run-database-migrations) * [6\. Start the Server](https://docs.honcho.dev/v3/contributing/self-hosting#6-start-the-server) * [7\. Start the Background Worker (Deriver)](https://docs.honcho.dev/v3/contributing/self-hosting#7-start-the-background-worker-deriver) * [Cloud Database Setup](https://docs.honcho.dev/v3/contributing/self-hosting#cloud-database-setup) * [Supabase (Recommended)](https://docs.honcho.dev/v3/contributing/self-hosting#supabase-recommended) * [Railway](https://docs.honcho.dev/v3/contributing/self-hosting#railway) * [Verify Your Setup](https://docs.honcho.dev/v3/contributing/self-hosting#verify-your-setup) * [1\. Health Check](https://docs.honcho.dev/v3/contributing/self-hosting#1-health-check) * [2\. Smoke Test (database + API)](https://docs.honcho.dev/v3/contributing/self-hosting#2-smoke-test-database-%2B-api) * [3\. API Documentation](https://docs.honcho.dev/v3/contributing/self-hosting#3-api-documentation) * [4\. Test with SDK](https://docs.honcho.dev/v3/contributing/self-hosting#4-test-with-sdk) * [Connect Your Application](https://docs.honcho.dev/v3/contributing/self-hosting#connect-your-application) * [Update SDK Configuration](https://docs.honcho.dev/v3/contributing/self-hosting#update-sdk-configuration) * [Next Steps](https://docs.honcho.dev/v3/contributing/self-hosting#next-steps) * [Troubleshooting](https://docs.honcho.dev/v3/contributing/self-hosting#troubleshooting) * [Production Considerations](https://docs.honcho.dev/v3/contributing/self-hosting#production-considerations) * [Security](https://docs.honcho.dev/v3/contributing/self-hosting#security) * [Scaling the Deriver](https://docs.honcho.dev/v3/contributing/self-hosting#scaling-the-deriver) * [Caching](https://docs.honcho.dev/v3/contributing/self-hosting#caching) * [Database Migrations](https://docs.honcho.dev/v3/contributing/self-hosting#database-migrations) * [LLM Providers](https://docs.honcho.dev/v3/contributing/self-hosting#llm-providers) * [Monitoring](https://docs.honcho.dev/v3/contributing/self-hosting#monitoring) * [Backups](https://docs.honcho.dev/v3/contributing/self-hosting#backups) This guide helps you set up a local environment to run Honcho for development, testing, or self-hosting. [​](https://docs.honcho.dev/v3/contributing/self-hosting#overview) Overview ------------------------------------------------------------------------------ By the end of this guide, you’ll have: * A local Honcho server running on your machine * A PostgreSQL database with pgvector extension * Basic configuration to connect your applications * A working environment for development or testing [​](https://docs.honcho.dev/v3/contributing/self-hosting#prerequisites) Prerequisites ---------------------------------------------------------------------------------------- Before you begin, ensure you have the following installed: ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#required-software) Required Software * **uv** - Python package manager: `curl -LsSf https://astral.sh/uv/install.sh | sh` or `brew install uv` * **Git** - [Download from git-scm.com](https://git-scm.com/downloads) * **Docker** (required for Docker setup, not needed for manual setup) - [Download from docker.com](https://www.docker.com/products/docker-desktop/) ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#database-options) Database Options You’ll need a PostgreSQL database with the pgvector extension. Choose one: * **Local PostgreSQL** - Install locally or use Docker * **Supabase** - Free cloud PostgreSQL with pgvector * **Railway** - Simple cloud PostgreSQL hosting * **Your own PostgreSQL server** [​](https://docs.honcho.dev/v3/contributing/self-hosting#llm-setup) LLM Setup -------------------------------------------------------------------------------- Honcho uses LLMs for memory extraction, summarization, dialectic chat, and dreaming. The server will **fail to start** without a provider configured. If you keep the built-in defaults, you only need one API key: all text-generation features default to `openai / gpt-5.4-mini`, and embeddings default to `openai / text-embedding-3-small`. Any OpenAI-compatible endpoint works too — OpenRouter, Together, Fireworks, Ollama, vLLM, or LiteLLM. Models must support tool calling (function calling). After copying `.env.template` to `.env`, the default setup is: # Required for the built-in defaults LLM_OPENAI_API_KEY=sk-... If you want a different model or an OpenAI-compatible proxy, uncomment and edit the relevant `*_MODEL_CONFIG__TRANSPORT`, `*_MODEL_CONFIG__MODEL`, and `*_MODEL_CONFIG__OVERRIDES__BASE_URL` lines in the Deriver, Dialectic, Summary, and Dream sections. For example: LLM_OPENAI_API_KEY=sk-or-v1-... DERIVER_MODEL_CONFIG__TRANSPORT=openai DERIVER_MODEL_CONFIG__MODEL=google/gemini-2.5-flash DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1 For recommended model tiers per feature, using multiple providers, or direct vendor API keys, see the [Configuration Guide](https://docs.honcho.dev/v3/contributing/configuration#llm-configuration) . **Community quick-start**: [elkimek/honcho-self-hosted](https://github.com/elkimek/honcho-self-hosted) provides a one-command installer with pre-configured model tiers, interactive provider setup, and Hermes Agent integration. [​](https://docs.honcho.dev/v3/contributing/self-hosting#docker-setup-recommended) Docker Setup (Recommended) ---------------------------------------------------------------------------------------------------------------- Docker Compose handles the database, Redis, and Honcho server. The compose file **builds the image from source** (there is no pre-built image on Docker Hub). This requires Docker with BuildKit enabled — see [Troubleshooting](https://docs.honcho.dev/v3/contributing/troubleshooting#docker-build-fails-with-permission-errors) if the build fails. The compose file is production-oriented by default (ports bound to `127.0.0.1`, restart policies, caching enabled). For development, uncomment the source mounts and monitoring services inside the file. ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#1-clone-the-repository) 1\. Clone the Repository git clone https://github.com/plastic-labs/honcho.git cd honcho ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#2-set-up-environment-variables) 2\. Set Up Environment Variables Copy the example environment file and configure it: cp .env.template .env Edit `.env` and configure your LLM provider — see [LLM Setup](https://docs.honcho.dev/v3/contributing/self-hosting#llm-setup) above. The database connection is set in the compose file. Auth is disabled by default (`AUTH_USE_AUTH=false`). ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#3-start-the-services) 3\. Start the Services cp docker-compose.yml.example docker-compose.yml docker compose up -d --build The first build takes a few minutes (compiling from source). Subsequent starts are fast. This starts four services: **api** (port 8000), **deriver** (background worker), **database** (PostgreSQL with pgvector, port 5432), and **redis** (port 6379). All ports are bound to `127.0.0.1`. Redis caching is enabled by default. For development, uncomment the source mount and monitoring sections inside `docker-compose.yml` to enable live reload, Prometheus, and Grafana. ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#4-verify) 4\. Verify Migrations run automatically on startup. # Check all containers are running docker compose ps # Health check (confirms the process is up) curl http://localhost:8000/health # Check the deriver is processing (look for "polling" or "processing" in logs) docker compose logs deriver --tail 20 For a full end-to-end test, see [Verify Your Setup](https://docs.honcho.dev/v3/contributing/self-hosting#verify-your-setup) below. [​](https://docs.honcho.dev/v3/contributing/self-hosting#manual-setup) Manual Setup -------------------------------------------------------------------------------------- For more control over your environment, you can set up everything manually. ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#1-clone-and-install-dependencies) 1\. Clone and Install Dependencies git clone https://github.com/plastic-labs/honcho.git cd honcho # Install dependencies using uv (this will also set up Python if needed) uv sync # Activate the virtual environment source .venv/bin/activate # On Windows: .venv\Scripts\activate ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#2-set-up-postgresql) 2\. Set Up PostgreSQL #### [​](https://docs.honcho.dev/v3/contributing/self-hosting#option-a-local-postgresql-installation) Option A: Local PostgreSQL Installation Install PostgreSQL and pgvector on your system: **macOS (using Homebrew):** brew install postgresql brew install pgvector **Ubuntu/Debian:** sudo apt update sudo apt install postgresql postgresql-contrib # Install pgvector extension (see pgvector docs for your version) **Windows:** Download from [postgresql.org](https://www.postgresql.org/download/windows/) #### [​](https://docs.honcho.dev/v3/contributing/self-hosting#option-b-docker-postgresql) Option B: Docker PostgreSQL docker run --name honcho-db \ -e POSTGRES_USER=postgres \ -e POSTGRES_PASSWORD=postgres \ -p 5432:5432 \ -d pgvector/pgvector:pg15 ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#3-enable-extensions) 3\. Enable Extensions Connect to PostgreSQL and enable pgvector: # Connect to PostgreSQL psql -U postgres # Enable the pgvector extension on the default database CREATE EXTENSION IF NOT EXISTS vector; \q ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#4-configure-environment) 4\. Configure Environment Create a `.env` file with your settings: cp .env.template .env Edit `.env` — configure your LLM provider (see [LLM Setup](https://docs.honcho.dev/v3/contributing/self-hosting#llm-setup) above) and set the database connection: DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@localhost:5432/postgres AUTH_USE_AUTH=false LOG_LEVEL=DEBUG ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#5-run-database-migrations) 5\. Run Database Migrations # Run migrations to create tables uv run alembic upgrade head ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#6-start-the-server) 6\. Start the Server # Start the development server uv run fastapi dev src/main.py The server will be available at `http://localhost:8000`. ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#7-start-the-background-worker-deriver) 7\. Start the Background Worker (Deriver) In a **separate terminal**, start the deriver background worker: uv run python -m src.deriver The deriver is essential for Honcho’s core functionality. It processes incoming messages to extract observations, build peer representations, generate session summaries, and run dream consolidation. Without it, messages will be stored but no memory or reasoning will occur. [​](https://docs.honcho.dev/v3/contributing/self-hosting#cloud-database-setup) Cloud Database Setup ------------------------------------------------------------------------------------------------------ If you prefer to use a managed PostgreSQL service: ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#supabase-recommended) Supabase (Recommended) 1. **Create a Supabase project** at [supabase.com](https://supabase.com/) 2. **Enable pgvector extension** in the SQL editor: CREATE EXTENSION IF NOT EXISTS vector; 3. **Get your connection string** from Settings > Database 4. **Update your `.env` file** with the connection string ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#railway) Railway 1. **Create a Railway project** at [railway.app](https://railway.app/) 2. **Add a PostgreSQL service** 3. **Enable pgvector** in the PostgreSQL console 4. **Get your connection string** from the service variables 5. **Update your `.env` file** [​](https://docs.honcho.dev/v3/contributing/self-hosting#verify-your-setup) Verify Your Setup ------------------------------------------------------------------------------------------------ Once your Honcho server is running, verify everything is working: ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#1-health-check) 1\. Health Check curl http://localhost:8000/health # {"status":"ok"} Note: `/health` only confirms the process is running. It does not check database or LLM connectivity. ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#2-smoke-test-database-+-api) 2\. Smoke Test (database + API) This confirms the database connection, migrations, and API are all working: # Create a workspace curl -s -X POST http://localhost:8000/v3/workspaces \ -H "Content-Type: application/json" \ -d '{"name": "test"}' | python3 -m json.tool If you get back a workspace object with an `id`, your database is connected and migrations ran correctly. ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#3-api-documentation) 3\. API Documentation Visit `http://localhost:8000/docs` to see the interactive API documentation. ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#4-test-with-sdk) 4\. Test with SDK from honcho import Honcho client = Honcho( base_url="http://localhost:8000", workspace_id="test" ) peer = client.peer("test-user") print(f"Created peer: {peer.id}") [​](https://docs.honcho.dev/v3/contributing/self-hosting#connect-your-application) Connect Your Application -------------------------------------------------------------------------------------------------------------- Now that Honcho is running locally, you can connect your applications: ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#update-sdk-configuration) Update SDK Configuration # Python SDK from honcho import Honcho client = Honcho( base_url="http://localhost:8000", ) // TypeScript SDK import { Honcho } from '@honcho-ai/sdk'; const client = new Honcho({ baseUrl: 'http://localhost:8000', }); ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#next-steps) Next Steps * **Configure Honcho**: Visit the [Configuration Guide](https://docs.honcho.dev/v3/contributing/configuration) for model tiers, provider options, and tuning * **Explore the API**: Check out the [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) * **Try the SDKs**: See our [guides](https://docs.honcho.dev/v3/guides) for examples * **Join the community**: [Discord](https://discord.gg/honcho) [​](https://docs.honcho.dev/v3/contributing/self-hosting#troubleshooting) Troubleshooting -------------------------------------------------------------------------------------------- Running into issues? See the [Troubleshooting Guide](https://docs.honcho.dev/v3/contributing/troubleshooting) for detailed solutions to common problems including: * Startup failures (missing API keys, database issues) * Runtime errors (“An unexpected error occurred” on every request) * Deriver not processing messages * Database connection and migration issues * Docker and Redis problems **Quick checks:** * Verify the server is running: `curl http://localhost:8000/health` * Check logs: `docker compose logs api` (Docker) or check terminal output (manual setup) * Ensure migrations ran: `uv run alembic upgrade head` [​](https://docs.honcho.dev/v3/contributing/self-hosting#production-considerations) Production Considerations ---------------------------------------------------------------------------------------------------------------- The default compose file is already production-oriented — ports bound to `127.0.0.1`, restart policies, caching enabled. ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#security) Security * Set `AUTH_USE_AUTH=true` and generate a JWT secret with `python scripts/generate_jwt_secret.py` * Use HTTPS via a reverse proxy in front of Honcho. Example with Caddy (automatic TLS): honcho.example.com { reverse_proxy localhost:8000 } Or with nginx: server { listen 443 ssl; server_name honcho.example.com; ssl_certificate /etc/letsencrypt/live/honcho.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/honcho.example.com/privkey.pem; location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } * Secure your database with strong credentials and restrict network access * The production compose binds PostgreSQL and Redis to `127.0.0.1` only — they are not accessible from the network ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#scaling-the-deriver) Scaling the Deriver * Increase `DERIVER_WORKERS` (default: 1) for higher message throughput * You can also run multiple deriver processes across machines — they coordinate via the database queue * Monitor deriver logs for processing backlog ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#caching) Caching * The production compose enables Redis caching by default (`CACHE_ENABLED=true`) * For the development compose, enable manually: `CACHE_ENABLED=true` * Configure `CACHE_URL` to point to your Redis instance (or use a managed Redis service) ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#database-migrations) Database Migrations * Always run `uv run alembic upgrade head` after updating Honcho before starting the server * Check current migration status with `uv run alembic current` ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#llm-providers) LLM Providers * Ensure your API keys are configured (see [LLM Setup](https://docs.honcho.dev/v3/contributing/self-hosting#llm-setup) ) * For alternative providers or per-feature model overrides, see the [Configuration Guide](https://docs.honcho.dev/v3/contributing/configuration#llm-configuration) ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#monitoring) Monitoring * Enable Prometheus metrics with `METRICS_ENABLED=true`. The API exposes `/metrics` on port 8000, the deriver on port 9090 (internal to its container — not published to the host by default). * Enable Sentry error tracking with `SENTRY_ENABLED=true` * The development compose includes Prometheus (host port 9090) and Grafana (host port 3000) for scraping and dashboards. Uncomment those services to enable them. ### [​](https://docs.honcho.dev/v3/contributing/self-hosting#backups) Backups * Set up regular PostgreSQL backups: # One-off backup docker compose exec database pg_dump -U postgres postgres > backup-$(date +%Y%m%d).sql # Restore cat backup.sql | docker compose exec -T database psql -U postgres postgres * Back up your `.env` or `config.toml` configuration files [Configuration Guide](https://docs.honcho.dev/v3/contributing/configuration) ⌘I --- # Queue Status - Honcho [Skip to main content](https://docs.honcho.dev/v2/documentation/core-concepts/features/queue-status#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Core Concepts Queue Status [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) Whenever `Messages` are stored in Honcho, a background process called the [Deriver](https://docs.honcho.dev/docs/v2/documentation/core-concepts/architecture#reasoning-layer) is triggered to reason about the conversation and generate insights. The Deriver is an asynchronous process and, depending on load may not immediately generated insights for the latest message you’ve sent. To help with this, Honcho provides several utilities to check the status of the Deriver. Python typescript from honcho import Honcho honcho = Honcho() status = honcho.get_deriver_status() honcho.poll_deriver_status() Output types Python TypeScript class DeriverStatus(BaseModel): completed_work_units: int """Completed work units""" in_progress_work_units: int """Work units currently being processed""" pending_work_units: int """Work units waiting to be processed""" total_work_units: int """Total work units""" sessions: Optional[Dict[str, Sessions]] = None """Per-session status when not filtered by session""" Whenever a `Message` is sent it will generate several tasks. These could be tasks such as generating insights, cleaning up a representation, summarizing a conversation etc. These tasks are defined based on who is sending the message, what `Session` the message is in, and potentially who is observing the message. We call the combination of these parameters a `work_unit` This has a few different implications. * tasks within the same work\_unit are processed sequentially, but multiple work\_units will be processed in parallel * If local representations are turned in a Session then a `Message` will generate an additional work unit for every `Peer` that has `observe_others=True` The `get_deriver_status` and `poll_deriver_status` methods can take additional parameters to scope the status to a specific work unit Python TypeScript def get_deriver_status( self, observer_id: str | None = None, sender_id: str | None = None, session_id: str | None = None, ) -> DeriverStatus: Additionally, there are deriver status and polling deriver status methods available on the `Session` objects in each of the SDKs. Below are the function signatures for the session level deriver status method python TypeScript @validate_call def get_deriver_status( self, observer_id: str | None = None, sender_id: str | None = None, ) -> DeriverStatus: [File Uploads](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads) [Local vs Global Representations](https://docs.honcho.dev/v2/documentation/core-concepts/features/local-vs-global) ⌘I --- # Agent Zero - Honcho [Skip to main content](https://docs.honcho.dev/v3/guides/community/agent0#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Community Integrations Agent Zero [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Getting Started](https://docs.honcho.dev/v3/guides/community/agent0#getting-started) * [How It Works](https://docs.honcho.dev/v3/guides/community/agent0#how-it-works) * [Next Steps](https://docs.honcho.dev/v3/guides/community/agent0#next-steps) [Agent Zero](https://github.com/agent0ai/agent-zero) is a general AI agent framework with a plugin-first architecture. The Honcho plugin gives Agent Zero persistent memory across chat sessions — users are remembered with their preferences, context, and behavioral patterns, even after sessions end and new ones begin. [​](https://docs.honcho.dev/v3/guides/community/agent0#getting-started) Getting Started ------------------------------------------------------------------------------------------ The Honcho plugin is a community integration. See the [plugin README](https://github.com/alogotron/a0-plugin-honcho) for full installation and configuration instructions. The integration requires: 1. A Honcho API key from [app.honcho.dev](https://app.honcho.dev/) 2. Cloning the plugin into your Agent Zero plugins directory 3. Enabling it via **Settings > Plugins** in Agent Zero’s UI [​](https://docs.honcho.dev/v3/guides/community/agent0#how-it-works) How It Works ------------------------------------------------------------------------------------ The plugin hooks into Agent Zero’s extension system. It syncs user and assistant messages to Honcho after every turn, prefetches user context into the system prompt on each new turn, and maintains separate peer models for the user and agent. If Honcho is unavailable, the agent continues normally. [​](https://docs.honcho.dev/v3/guides/community/agent0#next-steps) Next Steps -------------------------------------------------------------------------------- Plugin Repository ----------------- Source code, installation, and full documentation. Honcho Architecture ------------------- Learn about peers, sessions, and dialectic reasoning. [Gmail](https://docs.honcho.dev/v3/guides/gmail) [Pi](https://docs.honcho.dev/v3/guides/community/pi-honcho-memory) ⌘I --- # Chat Endpoint - Honcho [Skip to main content](https://docs.honcho.dev/v3/documentation/features/chat#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Features Chat Endpoint [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Basic Usage](https://docs.honcho.dev/v3/documentation/features/chat#basic-usage) * [Reasoning Level](https://docs.honcho.dev/v3/documentation/features/chat#reasoning-level) * [Streaming Responses](https://docs.honcho.dev/v3/documentation/features/chat#streaming-responses) * [Integration Patterns](https://docs.honcho.dev/v3/documentation/features/chat#integration-patterns) * [Dynamic Prompt Enhancement](https://docs.honcho.dev/v3/documentation/features/chat#dynamic-prompt-enhancement) * [Conditional Logic](https://docs.honcho.dev/v3/documentation/features/chat#conditional-logic) * [Preference Extraction](https://docs.honcho.dev/v3/documentation/features/chat#preference-extraction) * [How Honcho Answers](https://docs.honcho.dev/v3/documentation/features/chat#how-honcho-answers) * [Best Practices](https://docs.honcho.dev/v3/documentation/features/chat#best-practices) * [Ask specific questions](https://docs.honcho.dev/v3/documentation/features/chat#ask-specific-questions) * [Let your LLM formulate queries](https://docs.honcho.dev/v3/documentation/features/chat#let-your-llm-formulate-queries) * [Use for runtime decisions](https://docs.honcho.dev/v3/documentation/features/chat#use-for-runtime-decisions) * [Combine with context()](https://docs.honcho.dev/v3/documentation/features/chat#combine-with-context) The Chat endpoint (`peer.chat()`) is the natural language interface to Honcho’s reasoning. Instead of manually retrieving conclusions, your LLM can ask questions and get synthesized answers based on all the reasoning Honcho has done about a peer. Think of it as agent-to-agent communication. [​](https://docs.honcho.dev/v3/documentation/features/chat#basic-usage) Basic Usage -------------------------------------------------------------------------------------- The simplest way to use the chat endpoint is to ask a question and get a text response: Python TypeScript from honcho import Honcho honcho = Honcho() peer = honcho.peer("user-123") # Ask Honcho about the peer query = "What is the user's favorite way of completing the task?" answer = peer.chat(query) print(answer) # "Based on conclusions, the user prefers using keyboard shortcuts..." The chat endpoint searches through the peer’s representation—all the conclusions Honcho has reasoned about them—and synthesizes a natural language answer. [​](https://docs.honcho.dev/v3/documentation/features/chat#reasoning-level) Reasoning Level ---------------------------------------------------------------------------------------------- Use `reasoning_level` to trade off speed against depth for a specific chat request. It is optional and defaults to `low`. Accepted values are `minimal`, `low`, `medium`, `high`, and `max`. The reasoning level controls which model the request is routed to, the tools used by the agent, the thinking budget, the maximum tool-iteration count, and output token limits. | Level | When to use | Notes | | --- | --- | --- | | `minimal` | Fast factual lookups | Smallest prefetch window and minimal tools for lower cost. | | `low` | Default balance | Standard tool set and budgets. | | `medium` | Multi-step or ambiguous questions | Calls fewer tools than `low`, but thinks harder and longer. | | `high` | Complex synthesis across sources | Thinks like `medium`, but uses more tools. | | `max` | Deep research, most complex queries | Highest thinking budget, max iterations. | Python TypeScript query = "Summarize the user's long-term goals." answer = peer.chat(query, reasoning_level="high") [​](https://docs.honcho.dev/v3/documentation/features/chat#streaming-responses) Streaming Responses ------------------------------------------------------------------------------------------------------ For longer answers, use streaming to get incremental responses: Python TypeScript query = "What do we know about the user?" response_stream = peer.chat(query, stream=True) for chunk in response_stream.iter_text(): print(chunk, end="", flush=True) Streaming is useful for displaying real-time responses in chat interfaces or when asking complex questions that require longer answers. [​](https://docs.honcho.dev/v3/documentation/features/chat#integration-patterns) Integration Patterns -------------------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v3/documentation/features/chat#dynamic-prompt-enhancement) Dynamic Prompt Enhancement Let your LLM decide what it needs to know, then inject that context into the next generation: Python TypeScript # Your LLM generates a query based on the conversation llm_query = "Does the user prefer formal or casual communication?" # Get answer from Honcho context = peer.chat(llm_query) # Add to your next LLM prompt enhanced_prompt = f""" Context about the user: {context} User message: {user_input} Respond appropriately based on the context. """ ### [​](https://docs.honcho.dev/v3/documentation/features/chat#conditional-logic) Conditional Logic Use chat endpoint responses to drive application logic: Python TypeScript # Check if user has completed onboarding onboarding_status = peer.chat("Has the user completed the onboarding flow?") if "yes" in onboarding_status.lower(): # Show main interface pass else: # Show onboarding pass ### [​](https://docs.honcho.dev/v3/documentation/features/chat#preference-extraction) Preference Extraction Extract specific preferences for personalization: Python TypeScript # Get multiple insights tone = peer.chat("What tone does the user prefer in responses?") expertise = peer.chat("What is the user's level of technical expertise?") goals = peer.chat("What are the user's main goals or objectives?") # Use these to configure your agent's behavior [​](https://docs.honcho.dev/v3/documentation/features/chat#how-honcho-answers) How Honcho Answers ---------------------------------------------------------------------------------------------------- When you call `peer.chat(query)`: 1. Honcho searches through the peer’s peer card and representation—conclusions drawn from reasoning over their messages 2. Retrieves conclusions semantically relevant to your query 3. Combines them with segments of source messages, if needed, to gather more context 4. Synthesizes them into a coherent natural language response to your query Honcho [reasoning](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning) runs continuously in the background, processing new messages and updating representations. The chat endpoint always has access to Honcho’s latest conclusions about the peer. [​](https://docs.honcho.dev/v3/documentation/features/chat#best-practices) Best Practices -------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v3/documentation/features/chat#ask-specific-questions) Ask specific questions Instead of “Tell me about the user”, ask “What communication style does the user prefer?” You’ll get more actionable answers. ### [​](https://docs.honcho.dev/v3/documentation/features/chat#let-your-llm-formulate-queries) Let your LLM formulate queries The chat endpoint shines when your LLM decides what it needs to know. This creates dynamic, context-aware personalization. An excellent way to achieve this, if building an agent, is to give access to the Honcho chat endpoint as just another tool. ### [​](https://docs.honcho.dev/v3/documentation/features/chat#use-for-runtime-decisions) Use for runtime decisions Don’t just use chat for LLM prompts - use it to drive application logic, routing, and feature flags based on user behavior. ### [​](https://docs.honcho.dev/v3/documentation/features/chat#combine-with-context) Combine with context() Use `context()` for conversation context and `peer.chat()` for specific insights. They complement each other. For more ideas on using the chat endpoint, see our [guides](https://docs.honcho.dev/v3/guides/overview) . [Get Context](https://docs.honcho.dev/v3/documentation/features/get-context) [Overview](https://docs.honcho.dev/v3/documentation/features/advanced/overview) ⌘I --- # Pi - Honcho [Skip to main content](https://docs.honcho.dev/v3/guides/community/pi-honcho-memory#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Community Integrations Pi [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Getting Started](https://docs.honcho.dev/v3/guides/community/pi-honcho-memory#getting-started) * [How It Works](https://docs.honcho.dev/v3/guides/community/pi-honcho-memory#how-it-works) * [Next Steps](https://docs.honcho.dev/v3/guides/community/pi-honcho-memory#next-steps) [pi-honcho-memory](https://github.com/agneym/pi-honcho-memory) is a persistent memory extension for [pi](https://pi.dev/) , a coding agent CLI. It gives pi long-term memory across sessions — user preferences, project context, and past decisions are remembered and automatically injected into the system prompt. [​](https://docs.honcho.dev/v3/guides/community/pi-honcho-memory#getting-started) Getting Started ---------------------------------------------------------------------------------------------------- Install the extension inside pi: pi install npm:@agney/pi-honcho-memory The integration requires: 1. A Honcho API key from [app.honcho.dev](https://app.honcho.dev/) 2. Running `/honcho-setup` inside pi for interactive configuration, or setting `HONCHO_API_KEY` in your environment The Honcho plugin is a community integration. See the [plugin README](https://github.com/agneym/pi-honcho-memory/blob/main/README.md) for full installation and configuration instructions. [​](https://docs.honcho.dev/v3/guides/community/pi-honcho-memory#how-it-works) How It Works ---------------------------------------------------------------------------------------------- The extension hooks into pi’s extension system. It automatically syncs user and assistant messages to Honcho after each agent response, injects cached user profile and project context into the system prompt with zero network latency, and exposes LLM tools (`honcho_search`, `honcho_chat`, `honcho_remember`) for active memory operations. Session scoping is configurable — memory can be shared per repo, per git branch, or per directory. If Honcho is unavailable, pi continues working normally. [​](https://docs.honcho.dev/v3/guides/community/pi-honcho-memory#next-steps) Next Steps ------------------------------------------------------------------------------------------ Extension Repository -------------------- Source code, installation, and full documentation. Honcho Architecture ------------------- Learn about peers, sessions, and dialectic reasoning. [Agent Zero](https://docs.honcho.dev/v3/guides/community/agent0) [Migrating from Mem0](https://docs.honcho.dev/v3/guides/migrations/mem0) ⌘I --- # Streaming Responses - Honcho [Skip to main content](https://docs.honcho.dev/v2/documentation/core-concepts/features/streaming-response#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Core Concepts Streaming Responses [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [When to Use Streaming](https://docs.honcho.dev/v2/documentation/core-concepts/features/streaming-response#when-to-use-streaming) * [Streaming with the Dialectic Endpoint](https://docs.honcho.dev/v2/documentation/core-concepts/features/streaming-response#streaming-with-the-dialectic-endpoint) * [Prerequisites](https://docs.honcho.dev/v2/documentation/core-concepts/features/streaming-response#prerequisites) * [Streaming from the Dialectic Endpoint](https://docs.honcho.dev/v2/documentation/core-concepts/features/streaming-response#streaming-from-the-dialectic-endpoint) * [Working with Streaming Data](https://docs.honcho.dev/v2/documentation/core-concepts/features/streaming-response#working-with-streaming-data) * [Example: Restaurant Recommendation Chat](https://docs.honcho.dev/v2/documentation/core-concepts/features/streaming-response#example-restaurant-recommendation-chat) * [Performance Considerations](https://docs.honcho.dev/v2/documentation/core-concepts/features/streaming-response#performance-considerations) When working with AI-generated content, streaming the response as it’s generated can significantly improve the user experience. Honcho provides streaming functionality in its SDKs that allows your application to display content as it’s being generated, rather than waiting for the complete response. [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/streaming-response#when-to-use-streaming) When to Use Streaming -------------------------------------------------------------------------------------------------------------------------------------- Streaming is particularly useful for: * Real-time chat interfaces * Long-form content generation * Applications where perceived speed is important * Interactive agent experiences * Reducing time-to-first-word in user interactions [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/streaming-response#streaming-with-the-dialectic-endpoint) Streaming with the Dialectic Endpoint ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- One of the primary use cases for streaming in Honcho is with the Dialectic endpoint. This allows you to stream the AI’s reasoning about a user in real-time. ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/streaming-response#prerequisites) Prerequisites Python TypeScript from honcho import Honcho # Initialize client (using the default workspace) honcho = Honcho() # Create or get peers user = honcho.peer("demo-user") assistant = honcho.peer("assistant") # Create a new session session = honcho.session("demo-session") # Add peers to the session session.add_peers([user, assistant]) # Store some messages for context (optional) session.add_messages([\ user.message("Hello, I'm testing the streaming functionality")\ ]) [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/streaming-response#streaming-from-the-dialectic-endpoint) Streaming from the Dialectic Endpoint ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- Python TypeScript import time # Basic streaming example response_stream = user.chat("What can you tell me about this user?", stream=True) for chunk in response_stream.iter_text(): print(chunk, end="", flush=True) # Print each chunk as it arrives time.sleep(0.01) # Optional delay for demonstration [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/streaming-response#working-with-streaming-data) Working with Streaming Data -------------------------------------------------------------------------------------------------------------------------------------------------- When working with streaming responses, consider these patterns: 1. **Progressive Rendering** - Update your UI as chunks arrive instead of waiting for the full response 2. **Buffered Processing** - Accumulate chunks until a logical break (like a sentence or paragraph) 3. **Token Counting** - Monitor token usage in real-time for applications with token limits 4. **Error Handling** - Implement appropriate error handling for interrupted streams [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/streaming-response#example-restaurant-recommendation-chat) Example: Restaurant Recommendation Chat ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Python TypeScript import asyncio from honcho import Honcho async def restaurant_recommendation_chat(): # Initialize client honcho = Honcho() # Create peers user = honcho.peer("food-lover") assistant = honcho.peer("restaurant-assistant") # Create session session = honcho.session("food-preferences-session") # Add peers to session await session.add_peers([user, assistant]) # Store multiple user messages about food preferences user_messages = [\ "I absolutely love spicy Thai food, especially curries with coconut milk.",\ "Italian cuisine is another favorite - fresh pasta and wood-fired pizza are my weakness!",\ "I try to eat vegetarian most of the time, but occasionally enjoy seafood.",\ "I can't handle overly sweet desserts, but love something with dark chocolate."\ ] # Add the user's messages to the session session_messages = [user.message(message) for message in user_messages] await session.add_messages(session_messages) # Print the user messages for message in user_messages: print(f"User: {message}") # Ask for restaurant recommendations based on preferences print("\nRequesting restaurant recommendations...") print("Assistant: ", end="", flush=True) full_response = "" # Stream the response using the user's peer to get recommendations response_stream = user.chat( "Based on this user's food preferences, recommend 3 restaurants they might enjoy in the Lower East Side.", stream=True, session_id=session.id ) for chunk in response_stream.iter_text(): print(chunk, end="", flush=True) full_response += chunk await asyncio.sleep(0.01) # Store the assistant's complete response await session.add_messages([\ assistant.message(full_response)\ ]) # Run the async function if __name__ == "__main__": asyncio.run(restaurant_recommendation_chat()) [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/streaming-response#performance-considerations) Performance Considerations ------------------------------------------------------------------------------------------------------------------------------------------------ When implementing streaming: * Consider connection stability for mobile or unreliable networks * Implement appropriate timeouts for stream operations * Be mindful of memory usage when accumulating large responses * Use appropriate error handling for network interruptions Streaming responses provide a more interactive and engaging user experience. By implementing streaming in your Honcho applications, you can create more responsive AI-powered features that feel natural and immediate to your users. [Working Representations](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep) [Using Filters](https://docs.honcho.dev/v2/documentation/core-concepts/features/using-filters) ⌘I --- # Configuration Guide - Honcho [Skip to main content](https://docs.honcho.dev/v3/contributing/configuration#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Self-Hosting Configuration Guide [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Environment Variable Naming](https://docs.honcho.dev/v3/contributing/configuration#environment-variable-naming) * [LLM Configuration](https://docs.honcho.dev/v3/contributing/configuration#llm-configuration) * [Choosing Models](https://docs.honcho.dev/v3/contributing/configuration#choosing-models) * [Provider Types](https://docs.honcho.dev/v3/contributing/configuration#provider-types) * [Tiered Model Setup](https://docs.honcho.dev/v3/contributing/configuration#tiered-model-setup) * [Direct Vendor Keys](https://docs.honcho.dev/v3/contributing/configuration#direct-vendor-keys) * [Self-Hosted (vLLM / Ollama)](https://docs.honcho.dev/v3/contributing/configuration#self-hosted-vllm-%2F-ollama) * [Thinking Budget](https://docs.honcho.dev/v3/contributing/configuration#thinking-budget) * [Provider-Specific Parameters](https://docs.honcho.dev/v3/contributing/configuration#provider-specific-parameters) * [Changing Transport](https://docs.honcho.dev/v3/contributing/configuration#changing-transport) * [General LLM Settings](https://docs.honcho.dev/v3/contributing/configuration#general-llm-settings) * [Embedding Configuration](https://docs.honcho.dev/v3/contributing/configuration#embedding-configuration) * [Feature-Specific Model Configuration](https://docs.honcho.dev/v3/contributing/configuration#feature-specific-model-configuration) * [Core Configuration](https://docs.honcho.dev/v3/contributing/configuration#core-configuration) * [Application Settings](https://docs.honcho.dev/v3/contributing/configuration#application-settings) * [Database](https://docs.honcho.dev/v3/contributing/configuration#database) * [Authentication](https://docs.honcho.dev/v3/contributing/configuration#authentication) * [Cache (Redis)](https://docs.honcho.dev/v3/contributing/configuration#cache-redis) * [Webhooks](https://docs.honcho.dev/v3/contributing/configuration#webhooks) * [Vector Store](https://docs.honcho.dev/v3/contributing/configuration#vector-store) * [Monitoring](https://docs.honcho.dev/v3/contributing/configuration#monitoring) * [Prometheus Metrics](https://docs.honcho.dev/v3/contributing/configuration#prometheus-metrics) * [CloudEvents Telemetry](https://docs.honcho.dev/v3/contributing/configuration#cloudevents-telemetry) * [Sentry](https://docs.honcho.dev/v3/contributing/configuration#sentry) * [Reference config.toml](https://docs.honcho.dev/v3/contributing/configuration#reference-config-toml) * [Database Migrations](https://docs.honcho.dev/v3/contributing/configuration#database-migrations) * [Troubleshooting](https://docs.honcho.dev/v3/contributing/configuration#troubleshooting) Most users only need the setup from the [Self-Hosting Guide](https://docs.honcho.dev/v3/contributing/self-hosting#llm-setup) . This page is the full reference for customizing providers, tuning features, and hardening your deployment. Honcho loads configuration in this priority order (highest wins): 1. **Environment variables** (always take precedence) 2. **`.env` file** 3. **`config.toml` file** 4. **Built-in defaults** Use `.env` for secrets and overrides, `config.toml` for base settings. Or use environment variables exclusively — whatever fits your deployment. Copy the examples to get started: cp .env.template .env cp config.toml.example config.toml ### [​](https://docs.honcho.dev/v3/contributing/configuration#environment-variable-naming) Environment Variable Naming All config values map to environment variables: * `{SECTION}_{KEY}` for top-level section settings (e.g., `DB_CONNECTION_URI` → `[db].CONNECTION_URI`) * `{KEY}` for app-level settings (e.g., `LOG_LEVEL` → `[app].LOG_LEVEL`) * Use `__` inside `{KEY}` for nested settings (e.g., `DIALECTIC_LEVELS__minimal__MODEL_CONFIG__TRANSPORT`, `DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL`) [​](https://docs.honcho.dev/v3/contributing/configuration#llm-configuration) LLM Configuration ------------------------------------------------------------------------------------------------- The [Self-Hosting Guide](https://docs.honcho.dev/v3/contributing/self-hosting#llm-setup) covers the basic setup: either the built-in OpenAI defaults or one OpenAI-compatible endpoint/model for all features. This section covers recommended model tiers, using multiple providers, and per-feature tuning. All Honcho agents (deriver, dialectic, dream) require tool calling. Your models must support the OpenAI tool calling format. ### [​](https://docs.honcho.dev/v3/contributing/configuration#choosing-models) Choosing Models Model choice matters more for tool-use reliability than raw intelligence: | Tier | Example models | Use case | Notes | | --- | --- | --- | --- | | **Light** | Gemini 2.5 Flash, GLM-4.7-Flash | Deriver, summary, dialectic minimal/low | High throughput, cheap, reliable tool use | | **Medium** | Claude Haiku 4.5, Grok 4.1 Fast | Dialectic medium/high | Good reasoning + tool use balance | | **Heavy** | Claude Sonnet 4, GLM-5 | Dream, dialectic max | Best quality for rare/complex tasks | You can mix providers freely — for example, use Gemini for the deriver and Claude for dreaming. ### [​](https://docs.honcho.dev/v3/contributing/configuration#provider-types) Provider Types | Transport value | What it connects to | API key env var | | --- | --- | --- | | `openai` | OpenAI or any OpenAI-compatible endpoint (OpenRouter, Together, Fireworks, LiteLLM, vLLM, Ollama) | `LLM_OPENAI_API_KEY` | | `anthropic` | Anthropic Claude (direct) | `LLM_ANTHROPIC_API_KEY` | | `gemini` | Google Gemini (direct) | `LLM_GEMINI_API_KEY` | For OpenAI-compatible proxies (OpenRouter, vLLM, Ollama, etc.), use `transport = "openai"` and set `MODEL_CONFIG__OVERRIDES__BASE_URL` on each feature to point at your endpoint. ### [​](https://docs.honcho.dev/v3/contributing/configuration#tiered-model-setup) Tiered Model Setup Once you’re past initial setup, you can assign different models per feature for better cost/quality tradeoffs. This example uses OpenRouter with light/medium/heavy tiers: LLM_OPENAI_API_KEY=sk-or-v1-... # All features route through OpenRouter via overrides.base_url # (You can set this on each feature's MODEL_CONFIG) # Light tier — high throughput, cheap DERIVER_MODEL_CONFIG__TRANSPORT=openai DERIVER_MODEL_CONFIG__MODEL=google/gemini-2.5-flash-lite DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1 SUMMARY_MODEL_CONFIG__TRANSPORT=openai SUMMARY_MODEL_CONFIG__MODEL=google/gemini-2.5-flash DIALECTIC_LEVELS__minimal__MODEL_CONFIG__TRANSPORT=openai DIALECTIC_LEVELS__minimal__MODEL_CONFIG__MODEL=google/gemini-2.5-flash-lite DIALECTIC_LEVELS__low__MODEL_CONFIG__TRANSPORT=openai DIALECTIC_LEVELS__low__MODEL_CONFIG__MODEL=google/gemini-2.5-flash-lite # Medium tier — better reasoning DIALECTIC_LEVELS__medium__MODEL_CONFIG__TRANSPORT=openai DIALECTIC_LEVELS__medium__MODEL_CONFIG__MODEL=anthropic/claude-haiku-4-5 DIALECTIC_LEVELS__high__MODEL_CONFIG__TRANSPORT=openai DIALECTIC_LEVELS__high__MODEL_CONFIG__MODEL=anthropic/claude-haiku-4-5 DIALECTIC_LEVELS__max__MODEL_CONFIG__TRANSPORT=openai DIALECTIC_LEVELS__max__MODEL_CONFIG__MODEL=anthropic/claude-haiku-4-5 # Heavy tier — best quality for complex tasks DREAM_DEDUCTION_MODEL_CONFIG__TRANSPORT=openai DREAM_DEDUCTION_MODEL_CONFIG__MODEL=anthropic/claude-haiku-4-5 DREAM_INDUCTION_MODEL_CONFIG__TRANSPORT=openai DREAM_INDUCTION_MODEL_CONFIG__MODEL=anthropic/claude-haiku-4-5 ### [​](https://docs.honcho.dev/v3/contributing/configuration#direct-vendor-keys) Direct Vendor Keys Instead of an OpenAI-compatible proxy, you can use vendor APIs directly. Each transport picks up its own `LLM_{TRANSPORT}_API_KEY`. If you keep the built-in defaults, only `LLM_OPENAI_API_KEY` is required: LLM_OPENAI_API_KEY=... # Built-in model defaults # - deriver: openai / gpt-5.4-mini # - dialectic (all levels): openai / gpt-5.4-mini # - summary: openai / gpt-5.4-mini # - dream specialists: openai / gpt-5.4-mini # - embeddings: openai / text-embedding-3-small To use Gemini or Anthropic directly, override the features you want to move: LLM_GEMINI_API_KEY=... DERIVER_MODEL_CONFIG__TRANSPORT=gemini DERIVER_MODEL_CONFIG__MODEL=gemini-2.5-flash LLM_ANTHROPIC_API_KEY=... DREAM_DEDUCTION_MODEL_CONFIG__TRANSPORT=anthropic DREAM_DEDUCTION_MODEL_CONFIG__MODEL=claude-haiku-4-5 ### [​](https://docs.honcho.dev/v3/contributing/configuration#self-hosted-vllm-/-ollama) Self-Hosted (vLLM / Ollama) Use `transport = "openai"` and set `MODEL_CONFIG__OVERRIDES__BASE_URL` on each feature: # vLLM LLM_OPENAI_API_KEY=not-needed DERIVER_MODEL_CONFIG__TRANSPORT=openai DERIVER_MODEL_CONFIG__MODEL=your-model-name DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL=http://localhost:8000/v1 # Ollama LLM_OPENAI_API_KEY=ollama DERIVER_MODEL_CONFIG__TRANSPORT=openai DERIVER_MODEL_CONFIG__MODEL=llama3.3:70b DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL=http://localhost:11434/v1 Set `MODEL_CONFIG__TRANSPORT`, `MODEL_CONFIG__MODEL`, and `MODEL_CONFIG__OVERRIDES__BASE_URL` for each feature the same way. The same overrides are available in `config.toml`: [deriver.model_config] transport = "openai" model = "my-local-model" [deriver.model_config.overrides] base_url = "http://localhost:8000/v1" api_key_env = "DERIVER_LOCAL_API_KEY" ### [​](https://docs.honcho.dev/v3/contributing/configuration#thinking-budget) Thinking Budget Built-in defaults do not set `MODEL_CONFIG__THINKING_BUDGET_TOKENS` or `MODEL_CONFIG__THINKING_EFFORT`. Add one only when your chosen model supports it. Use `MODEL_CONFIG__THINKING_EFFORT` for OpenAI reasoning models: DERIVER_MODEL_CONFIG__THINKING_EFFORT=minimal DIALECTIC_LEVELS__max__MODEL_CONFIG__THINKING_EFFORT=medium Use `MODEL_CONFIG__THINKING_BUDGET_TOKENS` for Anthropic and Gemini models. Set it to `0` or omit it for providers that don’t support extended thinking: SUMMARY_MODEL_CONFIG__THINKING_BUDGET_TOKENS=1024 DREAM_DEDUCTION_MODEL_CONFIG__THINKING_BUDGET_TOKENS=1024 ### [​](https://docs.honcho.dev/v3/contributing/configuration#provider-specific-parameters) Provider-Specific Parameters Each model config supports an `overrides.provider_params` dict for passing arbitrary parameters to the underlying provider SDK. Use this for vendor-specific features that aren’t part of the standard config: [deriver.model_config.overrides.provider_params] # These are passed directly to the provider SDK verbosity = "low" ### [​](https://docs.honcho.dev/v3/contributing/configuration#changing-transport) Changing Transport When changing a feature’s `transport`, always specify `model` explicitly. Partial overrides that change transport without model will keep the previous model name, which may not be valid for the new provider. ### [​](https://docs.honcho.dev/v3/contributing/configuration#general-llm-settings) General LLM Settings LLM_DEFAULT_MAX_TOKENS=2500 # Tool output limits (to prevent token explosion) LLM_MAX_TOOL_OUTPUT_CHARS=10000 # ~2500 tokens at 4 chars/token LLM_MAX_MESSAGE_CONTENT_CHARS=2000 # Max chars per message in tool results ### [​](https://docs.honcho.dev/v3/contributing/configuration#embedding-configuration) Embedding Configuration Embeddings use their own nested model config, separate from the main text-generation LLM settings. # Embedding vector settings EMBEDDING_VECTOR_DIMENSIONS=1536 EMBEDDING_MAX_INPUT_TOKENS=8192 EMBEDDING_MAX_TOKENS_PER_REQUEST=300000 # Embedding transport/model selection EMBEDDING_MODEL_CONFIG__TRANSPORT=openai # openai, gemini EMBEDDING_MODEL_CONFIG__MODEL=text-embedding-3-small # Optional endpoint overrides EMBEDDING_MODEL_CONFIG__OVERRIDES__BASE_URL=http://localhost:8000/v1 EMBEDDING_MODEL_CONFIG__OVERRIDES__API_KEY_ENV=EMBEDDING_CUSTOM_API_KEY Current constraint: * `EMBEDDING_VECTOR_DIMENSIONS` can be changed for fully migrated external vector stores, but pgvector and dual-write mode still require `1536` until the schema migration lands. ### [​](https://docs.honcho.dev/v3/contributing/configuration#feature-specific-model-configuration) Feature-Specific Model Configuration Each feature can use a different provider and model. Below are all the tuning knobs. **Dialectic API:** The Dialectic API provides theory-of-mind informed responses. It uses a tiered reasoning system with five levels: # Global dialectic settings DIALECTIC_MAX_OUTPUT_TOKENS=8192 DIALECTIC_MAX_INPUT_TOKENS=100000 DIALECTIC_HISTORY_TOKEN_LIMIT=8192 DIALECTIC_SESSION_HISTORY_MAX_TOKENS=4096 **Per-Level Configuration:** Each reasoning level has its own provider, model, and settings: # config.toml example [dialectic.levels.minimal] MAX_TOOL_ITERATIONS = 1 MAX_OUTPUT_TOKENS = 250 TOOL_CHOICE = "any" [dialectic.levels.minimal.model_config] transport = "openai" model = "gpt-5.4-mini" [dialectic.levels.low] MAX_TOOL_ITERATIONS = 5 TOOL_CHOICE = "any" [dialectic.levels.low.model_config] transport = "openai" model = "gpt-5.4-mini" [dialectic.levels.medium] MAX_TOOL_ITERATIONS = 2 [dialectic.levels.medium.model_config] transport = "openai" model = "gpt-5.4-mini" [dialectic.levels.high] MAX_TOOL_ITERATIONS = 4 [dialectic.levels.high.model_config] transport = "openai" model = "gpt-5.4-mini" [dialectic.levels.max] MAX_TOOL_ITERATIONS = 10 [dialectic.levels.max.model_config] transport = "openai" model = "gpt-5.4-mini" Environment variables for nested levels use double underscores: DIALECTIC_LEVELS__minimal__MODEL_CONFIG__TRANSPORT=openai DIALECTIC_LEVELS__minimal__MODEL_CONFIG__MODEL=gpt-5.4-mini DIALECTIC_LEVELS__minimal__MAX_TOOL_ITERATIONS=1 DIALECTIC_LEVELS__minimal__MAX_OUTPUT_TOKENS=250 DIALECTIC_LEVELS__minimal__TOOL_CHOICE=any **Deriver (Theory of Mind):** The Deriver extracts facts from messages and builds theory-of-mind representations of peers. DERIVER_ENABLED=true # LLM settings DERIVER_MODEL_CONFIG__TRANSPORT=openai DERIVER_MODEL_CONFIG__MODEL=gpt-5.4-mini DERIVER_MAX_INPUT_TOKENS=23000 # DERIVER_MODEL_CONFIG__THINKING_EFFORT=minimal # DERIVER_MODEL_CONFIG__THINKING_BUDGET_TOKENS=1024 # DERIVER_MODEL_CONFIG__TEMPERATURE=0.7 # Optional temperature override # Backup model (optional) # DERIVER_MODEL_CONFIG__FALLBACK__MODEL=claude-haiku-4-5 # DERIVER_MODEL_CONFIG__FALLBACK__TRANSPORT=anthropic # Worker settings DERIVER_WORKERS=1 # Increase for higher throughput DERIVER_POLLING_SLEEP_INTERVAL_SECONDS=1.0 DERIVER_STALE_SESSION_TIMEOUT_MINUTES=5 # Queue management DERIVER_QUEUE_ERROR_RETENTION_SECONDS=2592000 # 30 days # Observation settings DERIVER_DEDUPLICATE=true DERIVER_LOG_OBSERVATIONS=false DERIVER_WORKING_REPRESENTATION_MAX_OBSERVATIONS=100 DERIVER_REPRESENTATION_BATCH_MAX_TOKENS=1024 **Peer Card:** PEER_CARD_ENABLED=true **Summary Generation:** Session summaries provide compressed context for long conversations — short summaries (frequent) and long summaries (comprehensive). SUMMARY_ENABLED=true SUMMARY_MODEL_CONFIG__TRANSPORT=openai SUMMARY_MODEL_CONFIG__MODEL=gpt-5.4-mini SUMMARY_MAX_TOKENS_SHORT=1000 SUMMARY_MAX_TOKENS_LONG=4000 # SUMMARY_MODEL_CONFIG__THINKING_EFFORT=minimal # SUMMARY_MODEL_CONFIG__THINKING_BUDGET_TOKENS=1024 SUMMARY_MESSAGES_PER_SHORT_SUMMARY=20 SUMMARY_MESSAGES_PER_LONG_SUMMARY=60 **Dream Processing:** Dream processing consolidates and refines peer representations during idle periods. DREAM_ENABLED=true DREAM_DOCUMENT_THRESHOLD=50 DREAM_IDLE_TIMEOUT_MINUTES=60 DREAM_MIN_HOURS_BETWEEN_DREAMS=8 DREAM_ENABLED_TYPES=["omni"] DREAM_MAX_TOOL_ITERATIONS=20 DREAM_HISTORY_TOKEN_LIMIT=16384 # Specialist model configs (each is independent) DREAM_DEDUCTION_MODEL_CONFIG__TRANSPORT=openai DREAM_DEDUCTION_MODEL_CONFIG__MODEL=gpt-5.4-mini DREAM_INDUCTION_MODEL_CONFIG__TRANSPORT=openai DREAM_INDUCTION_MODEL_CONFIG__MODEL=gpt-5.4-mini **Surprisal-Based Sampling (Advanced):** Optional subsystem for identifying unusual observations during dreaming: DREAM_SURPRISAL__ENABLED=false DREAM_SURPRISAL__TREE_TYPE=kdtree DREAM_SURPRISAL__TREE_K=5 DREAM_SURPRISAL__SAMPLING_STRATEGY=recent DREAM_SURPRISAL__SAMPLE_SIZE=200 DREAM_SURPRISAL__TOP_PERCENT_SURPRISAL=0.10 DREAM_SURPRISAL__MIN_HIGH_SURPRISAL_FOR_REPLACE=10 DREAM_SURPRISAL__INCLUDE_LEVELS=["explicit", "deductive"] [​](https://docs.honcho.dev/v3/contributing/configuration#core-configuration) Core Configuration --------------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v3/contributing/configuration#application-settings) Application Settings LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR, CRITICAL SESSION_OBSERVERS_LIMIT=10 GET_CONTEXT_MAX_TOKENS=100000 MAX_MESSAGE_SIZE=25000 MAX_FILE_SIZE=5242880 # 5MB EMBED_MESSAGES=true EMBEDDING_MAX_INPUT_TOKENS=8192 EMBEDDING_MAX_TOKENS_PER_REQUEST=300000 NAMESPACE=honcho **Optional Integrations:** LANGFUSE_HOST=https://cloud.langfuse.com LANGFUSE_PUBLIC_KEY=your-langfuse-public-key COLLECT_METRICS_LOCAL=false LOCAL_METRICS_FILE=metrics.jsonl REASONING_TRACES_FILE=traces.jsonl ### [​](https://docs.honcho.dev/v3/contributing/configuration#database) Database # Connection (required) DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@localhost:5432/postgres # Pool settings DB_SCHEMA=public DB_POOL_PRE_PING=true DB_POOL_SIZE=10 DB_MAX_OVERFLOW=20 DB_POOL_TIMEOUT=30 DB_POOL_RECYCLE=300 DB_POOL_USE_LIFO=true DB_SQL_DEBUG=false ### [​](https://docs.honcho.dev/v3/contributing/configuration#authentication) Authentication AUTH_USE_AUTH=false # Set to true to require JWT tokens AUTH_JWT_SECRET=your-super-secret-jwt-key # Required when auth is enabled Generate a secret: `python scripts/generate_jwt_secret.py` ### [​](https://docs.honcho.dev/v3/contributing/configuration#cache-redis) Cache (Redis) Redis caching is optional. Honcho works without it but benefits from caching in high-traffic scenarios. CACHE_ENABLED=false CACHE_URL=redis://localhost:6379/0?suppress=true CACHE_NAMESPACE=honcho CACHE_DEFAULT_TTL_SECONDS=300 CACHE_DEFAULT_LOCK_TTL_SECONDS=5 # Cache stampede prevention ### [​](https://docs.honcho.dev/v3/contributing/configuration#webhooks) Webhooks WEBHOOK_SECRET=your-webhook-signing-secret WEBHOOK_MAX_WORKSPACE_LIMIT=10 ### [​](https://docs.honcho.dev/v3/contributing/configuration#vector-store) Vector Store VECTOR_STORE_TYPE=pgvector # Options: pgvector, turbopuffer, lancedb VECTOR_STORE_MIGRATED=false VECTOR_STORE_NAMESPACE=honcho VECTOR_STORE_DIMENSIONS=1536 # Turbopuffer-specific VECTOR_STORE_TURBOPUFFER_API_KEY=your-turbopuffer-api-key VECTOR_STORE_TURBOPUFFER_REGION=us-east-1 # LanceDB-specific VECTOR_STORE_LANCEDB_PATH=./lancedb_data [​](https://docs.honcho.dev/v3/contributing/configuration#monitoring) Monitoring ----------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v3/contributing/configuration#prometheus-metrics) Prometheus Metrics Honcho exposes `/metrics` endpoints for scraping: * **API process**: Port 8000 * **Deriver process**: Port 9090 METRICS_ENABLED=false METRICS_NAMESPACE=honcho ### [​](https://docs.honcho.dev/v3/contributing/configuration#cloudevents-telemetry) CloudEvents Telemetry TELEMETRY_ENABLED=false TELEMETRY_ENDPOINT=https://telemetry.honcho.dev/v1/events TELEMETRY_HEADERS='{"Authorization": "Bearer your-token"}' TELEMETRY_BATCH_SIZE=100 TELEMETRY_FLUSH_INTERVAL_SECONDS=1.0 TELEMETRY_MAX_RETRIES=3 TELEMETRY_MAX_BUFFER_SIZE=10000 ### [​](https://docs.honcho.dev/v3/contributing/configuration#sentry) Sentry SENTRY_ENABLED=false SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id SENTRY_ENVIRONMENT=production SENTRY_TRACES_SAMPLE_RATE=0.1 SENTRY_PROFILES_SAMPLE_RATE=0.1 [​](https://docs.honcho.dev/v3/contributing/configuration#reference-config-toml) Reference config.toml --------------------------------------------------------------------------------------------------------- A complete config.toml with all defaults. Copy and modify what you need: [app] LOG_LEVEL = "INFO" SESSION_OBSERVERS_LIMIT = 10 EMBED_MESSAGES = true NAMESPACE = "honcho" [db] CONNECTION_URI = "postgresql+psycopg://postgres:postgres@localhost:5432/postgres" POOL_SIZE = 10 MAX_OVERFLOW = 20 [auth] USE_AUTH = false [cache] ENABLED = false URL = "redis://localhost:6379/0?suppress=true" DEFAULT_TTL_SECONDS = 300 [deriver] ENABLED = true WORKERS = 1 [deriver.model_config] transport = "openai" model = "gpt-5.4-mini" [peer_card] ENABLED = true [dialectic] MAX_OUTPUT_TOKENS = 8192 [dialectic.levels.minimal] MAX_TOOL_ITERATIONS = 1 MAX_OUTPUT_TOKENS = 250 TOOL_CHOICE = "any" [dialectic.levels.minimal.model_config] transport = "openai" model = "gpt-5.4-mini" [dialectic.levels.low] MAX_TOOL_ITERATIONS = 5 TOOL_CHOICE = "any" [dialectic.levels.low.model_config] transport = "openai" model = "gpt-5.4-mini" [dialectic.levels.medium] MAX_TOOL_ITERATIONS = 2 [dialectic.levels.medium.model_config] transport = "openai" model = "gpt-5.4-mini" [dialectic.levels.high] MAX_TOOL_ITERATIONS = 4 [dialectic.levels.high.model_config] transport = "openai" model = "gpt-5.4-mini" [dialectic.levels.max] MAX_TOOL_ITERATIONS = 10 [dialectic.levels.max.model_config] transport = "openai" model = "gpt-5.4-mini" [summary] ENABLED = true MAX_TOKENS_SHORT = 1000 MAX_TOKENS_LONG = 4000 [summary.model_config] transport = "openai" model = "gpt-5.4-mini" [dream] ENABLED = true [dream.deduction_model_config] transport = "openai" model = "gpt-5.4-mini" [dream.induction_model_config] transport = "openai" model = "gpt-5.4-mini" [webhook] MAX_WORKSPACE_LIMIT = 10 [metrics] ENABLED = false [telemetry] ENABLED = false [vector_store] TYPE = "pgvector" [sentry] ENABLED = false [​](https://docs.honcho.dev/v3/contributing/configuration#database-migrations) Database Migrations ----------------------------------------------------------------------------------------------------- uv run alembic current # Check status uv run alembic upgrade head # Upgrade to latest uv run alembic downgrade # Downgrade to specific revision uv run alembic revision --autogenerate -m "Description" # Create new migration [​](https://docs.honcho.dev/v3/contributing/configuration#troubleshooting) Troubleshooting --------------------------------------------------------------------------------------------- 1. **Database connection errors** — Ensure `DB_CONNECTION_URI` uses `postgresql+psycopg://` prefix. Verify database is running and pgvector extension is installed. 2. **Authentication issues** — Generate and set `AUTH_JWT_SECRET` when `AUTH_USE_AUTH=true`. Use `python scripts/generate_jwt_secret.py`. 3. **LLM provider errors** — Verify API keys are set. Check model names match your provider’s format. Ensure models support tool calling. 4. **Deriver not processing** — Check logs. Increase `DERIVER_WORKERS` for throughput. Verify database and LLM connectivity. 5. **Dialectic level issues** — Unset level fields inherit from the built-in defaults. For Anthropic, `THINKING_BUDGET_TOKENS` must be >= 1024 when enabled. For providers without budgeted thinking, omit it or set it to `0`. `MAX_OUTPUT_TOKENS` must exceed `THINKING_BUDGET_TOKENS`. 6. **Vector store issues** — For Turbopuffer, set the API key. Check `VECTOR_STORE_DIMENSIONS` matches your embedding model. [Local Environment](https://docs.honcho.dev/v3/contributing/self-hosting) [Troubleshooting](https://docs.honcho.dev/v3/contributing/troubleshooting) ⌘I --- # Hermes Agent + Honcho - Honcho [Skip to main content](https://docs.honcho.dev/v3/guides/integrations/hermes#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Integrations Hermes Agent + Honcho [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [What Honcho provides](https://docs.honcho.dev/v3/guides/integrations/hermes#what-honcho-provides) * [Dual-peer architecture](https://docs.honcho.dev/v3/guides/integrations/hermes#dual-peer-architecture) * [Available tools](https://docs.honcho.dev/v3/guides/integrations/hermes#available-tools) * [Running Honcho locally with Hermes](https://docs.honcho.dev/v3/guides/integrations/hermes#running-honcho-locally-with-hermes) * [Verifying the integration](https://docs.honcho.dev/v3/guides/integrations/hermes#verifying-the-integration) * [1\. Check status](https://docs.honcho.dev/v3/guides/integrations/hermes#1-check-status) * [2\. Store a fact and recall it across sessions](https://docs.honcho.dev/v3/guides/integrations/hermes#2-store-a-fact-and-recall-it-across-sessions) * [3\. Test tool calling directly](https://docs.honcho.dev/v3/guides/integrations/hermes#3-test-tool-calling-directly) * [Configuration options](https://docs.honcho.dev/v3/guides/integrations/hermes#configuration-options) * [Next steps](https://docs.honcho.dev/v3/guides/integrations/hermes#next-steps) [Hermes Agent](https://github.com/NousResearch/hermes-agent) is an open-source AI agent from [Nous Research](https://nousresearch.com/) with tool-calling, terminal access, a skills system, and multi-platform deployment (Telegram, Discord, Slack, WhatsApp). Honcho gives Hermes persistent cross-session memory and user modeling. For setup, configuration, and CLI commands, see the [Hermes Agent Honcho docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/honcho) . [​](https://docs.honcho.dev/v3/guides/integrations/hermes#what-honcho-provides) What Honcho provides ------------------------------------------------------------------------------------------------------- Honcho acts as a long-term memory and user-model layer alongside Hermes’ built-in memory files (`MEMORY.md` and `USER.md`). It gives Hermes three capabilities: 1. **Prompt-time context injection** — durable context about a user loaded into the prompt before generating a response. 2. **Cross-session continuity** — recall of stable preferences, project history, and working context across conversations. 3. **Durable writeback** — stable facts learned during a conversation stored back for future turns. These sit alongside Hermes’ local session history. Session history remembers the current conversation. Honcho remembers what should still matter later. [​](https://docs.honcho.dev/v3/guides/integrations/hermes#dual-peer-architecture) Dual-peer architecture ----------------------------------------------------------------------------------------------------------- Both the user and the AI agent have peer representations in Honcho: * **User peer**: observed from user messages. Learns preferences, goals, communication style. * **AI peer**: observed from assistant messages. Builds the agent’s knowledge representation. Both representations are injected into the system prompt, giving Hermes awareness of both who it’s talking to and what it knows. [​](https://docs.honcho.dev/v3/guides/integrations/hermes#available-tools) Available tools --------------------------------------------------------------------------------------------- Hermes exposes four Honcho tools to the agent: | Tool | What it does | | --- | --- | | `honcho_profile` | Fast peer card retrieval (no LLM). Returns curated key facts about the user. | | `honcho_search` | Semantic search over memory. Returns raw excerpts ranked by relevance. | | `honcho_context` | Dialectic Q&A powered by Honcho’s LLM. Synthesizes answers from conversation history. | | `honcho_conclude` | Writes durable facts to Honcho when the user states preferences, corrections, or important context. | [​](https://docs.honcho.dev/v3/guides/integrations/hermes#running-honcho-locally-with-hermes) Running Honcho locally with Hermes ----------------------------------------------------------------------------------------------------------------------------------- Follow the [Self-Hosting Guide](https://docs.honcho.dev/v3/contributing/self-hosting) to get Honcho running locally. Once it’s up, point Hermes at your instance: hermes memory setup # select "honcho", enter http://localhost:8000 as the base URL Or manually create/edit the config file (checked in order: `$HERMES_HOME/honcho.json` > `~/.hermes/honcho.json` > `~/.honcho/config.json`): { "baseUrl": "http://localhost:8000", "hosts": { "hermes": { "enabled": true, "aiPeer": "hermes", "peerName": "your-name", "workspace": "hermes" } } } For the full list of config fields (`recallMode`, `writeFrequency`, `sessionStrategy`, `dialecticReasoningLevel`, etc.), see the [Hermes memory provider docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#honcho) . **Community quick-start**: [elkimek/honcho-self-hosted](https://github.com/elkimek/honcho-self-hosted) provides a one-command installer with pre-configured model tiers and Hermes Agent integration. [​](https://docs.honcho.dev/v3/guides/integrations/hermes#verifying-the-integration) Verifying the integration ----------------------------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v3/guides/integrations/hermes#1-check-status) 1\. Check status hermes memory status This should show Honcho as the active memory provider with your base URL. ### [​](https://docs.honcho.dev/v3/guides/integrations/hermes#2-store-a-fact-and-recall-it-across-sessions) 2\. Store a fact and recall it across sessions In one conversation, tell Hermes something specific: My favorite programming language is Rust and I always use dark mode. Start a **new session** (different thread, new CLI invocation, or a different platform). Ask: What do you know about my preferences? If Hermes mentions Rust and dark mode without being told again, cross-session memory is working. The deriver processed your messages, extracted observations, and the dialectic recalled them. ### [​](https://docs.honcho.dev/v3/guides/integrations/hermes#3-test-tool-calling-directly) 3\. Test tool calling directly Ask Hermes to use a specific Honcho tool: Use your honcho_search tool to find anything you know about me. If Hermes calls the tool and returns results, the full tool pipeline (API connection, vector search, embedding) is functional. [​](https://docs.honcho.dev/v3/guides/integrations/hermes#configuration-options) Configuration options --------------------------------------------------------------------------------------------------------- | Field | Default | Description | | --- | --- | --- | | `recallMode` | `hybrid` | `hybrid` (auto-inject + tools), `context` (inject only), `tools` (tools only) | | `writeFrequency` | `async` | `async`, `turn`, `session`, or integer N | | `sessionStrategy` | `per-directory` | `per-directory`, `per-repo`, `per-session`, `global` | | `dialecticReasoningLevel` | `low` | `minimal`, `low`, `medium`, `high`, `max` | | `dialecticDynamic` | `true` | Auto-bump reasoning level by query complexity | | `messageMaxChars` | `25000` | Max chars per message (chunked if exceeded) | [​](https://docs.honcho.dev/v3/guides/integrations/hermes#next-steps) Next steps ----------------------------------------------------------------------------------- Hermes Agent Honcho Docs ------------------------ Setup, configuration, CLI commands, and all config options. Hermes Agent Source ------------------- Source code, installation, and full documentation. Honcho Architecture ------------------- Peers, sessions, and how reasoning works. Self-Hosting Guide ------------------ Full local environment setup, provider configuration, and troubleshooting. [OpenClaw](https://docs.honcho.dev/v3/guides/integrations/openclaw) [Zo Computer](https://docs.honcho.dev/v3/guides/integrations/zo-computer) ⌘I --- # Paperclip - Honcho [Skip to main content](https://docs.honcho.dev/v3/guides/integrations/paperclip#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Integrations Paperclip [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Install the Plugin](https://docs.honcho.dev/v3/guides/integrations/paperclip#install-the-plugin) * [Quick Setup](https://docs.honcho.dev/v3/guides/integrations/paperclip#quick-setup) * [Minimal Path](https://docs.honcho.dev/v3/guides/integrations/paperclip#minimal-path) * [Multi-Agent Hierarchy](https://docs.honcho.dev/v3/guides/integrations/paperclip#multi-agent-hierarchy) * [What Maps Where](https://docs.honcho.dev/v3/guides/integrations/paperclip#what-maps-where) * [How Agent Observation Works](https://docs.honcho.dev/v3/guides/integrations/paperclip#how-agent-observation-works) * [How It Works](https://docs.honcho.dev/v3/guides/integrations/paperclip#how-it-works) * [Identity And Scope](https://docs.honcho.dev/v3/guides/integrations/paperclip#identity-and-scope) * [Operator Actions](https://docs.honcho.dev/v3/guides/integrations/paperclip#operator-actions) * [Configuration Defaults And Overrides](https://docs.honcho.dev/v3/guides/integrations/paperclip#configuration-defaults-and-overrides) * [Default Behavior](https://docs.honcho.dev/v3/guides/integrations/paperclip#default-behavior) * [Agent Tools](https://docs.honcho.dev/v3/guides/integrations/paperclip#agent-tools) * [Next Steps](https://docs.honcho.dev/v3/guides/integrations/paperclip#next-steps) Honcho for [Paperclip](https://paperclip.ing/) adds persistent Honcho memory to Paperclip while keeping Paperclip as the system of record. This page covers the current public-host-compatible Paperclip plugin. It supports tools, sync, migration import, and manual prompt previews. It does not depend on automatic prompt-context injection hooks, run transcript import, or legacy workspace file import. [​](https://docs.honcho.dev/v3/guides/integrations/paperclip#install-the-plugin) Install the Plugin ------------------------------------------------------------------------------------------------------ 1. In Paperclip, open `Instance Settings` -> `Plugins`. 2. Click `Install Plugin`. 3. Enter `@honcho-ai/paperclip-honcho`. 4. Complete the install from the Paperclip UI. * Plugin download does not currently work on Windows because of a Paperclip host-side issue. [​](https://docs.honcho.dev/v3/guides/integrations/paperclip#quick-setup) Quick Setup ---------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v3/guides/integrations/paperclip#minimal-path) Minimal Path 1. Create a Paperclip secret containing the Honcho API key. * For a local Honcho, use whatever credential your local startup expects & `honchoApiKey` is not needed. 2. Open the Honcho plugin settings page in Paperclip. 3. If you are using Honcho Cloud, leave the deployment on the default cloud setting. 4. If you are using a local Honcho instance, switch the deployment to `Self-hosted / local` and set `honchoApiBaseUrl`. 5. Set `honchoApiKey`. 6. Save the settings. 7. Run `Initialize Honcho memory`. `honchoApiKey` is the only field required for the standard setup path. The other settings already have defaults. If you use a local Honcho deployment, `honchoApiBaseUrl` must be reachable from the Paperclip host runtime. If Paperclip is running in Docker, `localhost` may not point at your machine. [​](https://docs.honcho.dev/v3/guides/integrations/paperclip#multi-agent-hierarchy) Multi-Agent Hierarchy ------------------------------------------------------------------------------------------------------------ ### [​](https://docs.honcho.dev/v3/guides/integrations/paperclip#what-maps-where) What Maps Where Paperclip memory is organized around company, issue, and agent boundaries: * **Company -> workspace**: each Paperclip company maps to one Honcho workspace. * **Issue -> session**: each Paperclip issue maps to one Honcho session inside that workspace. * **Humans and agents -> peers**: human actors and Paperclip agents map to Honcho peers. This gives the plugin a natural hierarchy: company-level memory lives at the workspace level, issue-level memory lives at the session level, and people or agents are modeled as peers that participate across those scopes. ### [​](https://docs.honcho.dev/v3/guides/integrations/paperclip#how-agent-observation-works) How Agent Observation Works The current plugin gives agent peers explicit observation settings: * `observe_me` defaults to `true` * `observe_others` defaults to `true` In practice, that means agent peers can both be observed by Honcho and form representations of other peers they interact with. [​](https://docs.honcho.dev/v3/guides/integrations/paperclip#how-it-works) How It Works ------------------------------------------------------------------------------------------ ### [​](https://docs.honcho.dev/v3/guides/integrations/paperclip#identity-and-scope) Identity And Scope The integration breaks down into four parts: * **Identity and scope** - each Paperclip company maps to a Honcho workspace, agents and human actors map to peers, and issues map to sessions. * **What gets copied into Honcho** - issue comments and document revisions sync into Honcho, with document content sectioned and normalized message content capped before ingestion. * **What operators get** - operators get a plugin settings page, migration preview/status data, including a per-issue migration mapping preview, repair tools, and an issue-level `Memory` tab. * **What agents get** - agents get Honcho retrieval and peer-chat tools inside Paperclip. [​](https://docs.honcho.dev/v3/guides/integrations/paperclip#operator-actions) Operator Actions -------------------------------------------------------------------------------------------------- The settings page exposes the main operator workflow directly: | Action | What it does | | --- | --- | | `Validate config` | Validates the current plugin configuration before any sync or import work runs. | | `Test connection` | Resolves the API key secret, checks the Honcho connection, and returns the mapped workspace ID. | | `Initialize memory for this company` | Connects Honcho, creates core mappings, imports baseline issue memory, and verifies manual prompt previews. | | `Rescan migration sources` | Scans issue comments and issue documents and writes a fresh import preview. | | `Import history` | Imports the approved historical preview into Honcho with idempotent ledger checks. | | `Preview prompt context` | Builds a manual prompt-context preview for a company or issue without relying on automatic host hooks. | | `Repair mappings` | Recreates missing workspace, peer, and session mappings for the current company. | | `Resync this issue` | Replays sync for the current issue from the issue Memory tab. | [​](https://docs.honcho.dev/v3/guides/integrations/paperclip#configuration-defaults-and-overrides) Configuration Defaults And Overrides ------------------------------------------------------------------------------------------------------------------------------------------ ### [​](https://docs.honcho.dev/v3/guides/integrations/paperclip#default-behavior) Default Behavior | Setting | Default | Use when | | --- | --- | --- | | `honchoApiKey` | — | Required. Points the plugin at the Paperclip secret containing your Honcho API key. | | `honchoApiBaseUrl` | `https://api.honcho.dev` | Override this for self-hosted or non-default Honcho deployments. | | `workspacePrefix` | `paperclip` | Change this if you want a different workspace namespace. | | `syncIssueComments` | `true` | Turn this off if you do not want comment history imported into Honcho. | | `syncIssueDocuments` | `true` | Turn this off if you do not want issue document revisions imported. | | `enablePeerChat` | `true` | Required for the peer chat tool surface. | | `enablePromptContext` | `false` | Keep this off on the public-host-compatible path and use manual prompt previews instead. | | `observe_me` | `true` | Controls whether agent peers are observed by Honcho. | | `observe_others` | `true` | Controls whether agent peers form representations of other peers they interact with. | The plugin also accepts additional advanced fields in the settings page, including noise-pattern and metadata-strip controls. Most setups can ignore those and start with the defaults above. [​](https://docs.honcho.dev/v3/guides/integrations/paperclip#agent-tools) Agent Tools ---------------------------------------------------------------------------------------- The plugin registers the following Honcho tools for Paperclip agents: | Tool | Description | | --- | --- | | `honcho_get_issue_context` | Retrieve compact Honcho context for the current issue session. | | `honcho_search_memory` | Search Honcho memory within the current workspace, narrowing to the current issue by default. | | `honcho_search_messages` | Search raw Honcho messages. | | `honcho_search_conclusions` | Search high-signal summarized Honcho memory. | | `honcho_get_workspace_context` | Retrieve broad workspace recall from Honcho. | | `honcho_get_session` | Retrieve issue session context from Honcho. | | `honcho_get_agent_context` | Retrieve peer context for a specific agent. | | `honcho_get_hierarchy_context` | Retrieve delegated-work context when the host provides lineage metadata. | | `honcho_ask_peer` | Query Honcho peer chat for a target peer. Requires peer chat to be enabled in plugin config. | [​](https://docs.honcho.dev/v3/guides/integrations/paperclip#next-steps) Next Steps -------------------------------------------------------------------------------------- Paperclip-Honcho Repository --------------------------- Open the repository for source and setup details. Honcho Architecture ------------------- Review how workspaces, peers, and sessions fit together. Representation Scopes --------------------- Review how `observe_me` and `observe_others` change what peers can model. [Zo Computer](https://docs.honcho.dev/v3/guides/integrations/zo-computer) [Discord Bot](https://docs.honcho.dev/v3/guides/discord) ⌘I --- # Agentic Development - Honcho [Skip to main content](https://docs.honcho.dev/v3/documentation/introduction/vibecoding#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Introduction Agentic Development [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [MCP Server](https://docs.honcho.dev/v3/documentation/introduction/vibecoding#mcp-server) * [Claude Code Plugin](https://docs.honcho.dev/v3/documentation/introduction/vibecoding#claude-code-plugin) * [Agent Skills](https://docs.honcho.dev/v3/documentation/introduction/vibecoding#agent-skills) * [Available Skills](https://docs.honcho.dev/v3/documentation/introduction/vibecoding#available-skills) * [honcho-integration](https://docs.honcho.dev/v3/documentation/introduction/vibecoding#honcho-integration) * [migrate-honcho-py / migrate-honcho-ts](https://docs.honcho.dev/v3/documentation/introduction/vibecoding#migrate-honcho-py-%2F-migrate-honcho-ts) * [Universal Starter Prompt](https://docs.honcho.dev/v3/documentation/introduction/vibecoding#universal-starter-prompt) [​](https://docs.honcho.dev/v3/documentation/introduction/vibecoding#mcp-server) MCP Server ---------------------------------------------------------------------------------------------- The fastest way to give any AI tool persistent memory is through the Honcho MCP server. It works with any client that supports the Model Context Protocol. **Get started in 2 minutes:** 1. Get an API key at [app.honcho.dev](https://app.honcho.dev/) 2. Add the config for your client below 3. Restart your client See the [full MCP documentation](https://docs.honcho.dev/v3/guides/integrations/mcp) for all available tools, advanced configuration, and setup instructions for every supported client. Claude Desktop Cursor Claude Code { "mcpServers": { "honcho": { "command": "npx", "args": [\ "mcp-remote",\ "https://mcp.honcho.dev",\ "--header",\ "Authorization:${AUTH_HEADER}",\ "--header",\ "X-Honcho-User-Name:${USER_NAME}"\ ], "env": { "AUTH_HEADER": "Bearer hch-your-key-here", "USER_NAME": "YourName" } } } } * * * [​](https://docs.honcho.dev/v3/documentation/introduction/vibecoding#claude-code-plugin) Claude Code Plugin -------------------------------------------------------------------------------------------------------------- Use Honcho to build with Honcho! The [plugin](https://docs.honcho.dev/v3/guides/integrations/claudecode) provides Claude Code persistent memory that survives context wipes and session restarts. /plugin marketplace add plastic-labs/claude-honcho /plugin install honcho@honcho # Tools for Claude to use Honcho to manage its own context /plugin install honcho-dev@honcho # Skills to teach Claude how to integrate Honcho The marketplace also includes all the agent skills below, so you can use `/honcho-dev:integrate` directly after installing. See the [full Claude Code integration guide](https://docs.honcho.dev/v3/guides/integrations/claudecode) for setup details. * * * [​](https://docs.honcho.dev/v3/documentation/introduction/vibecoding#agent-skills) Agent Skills -------------------------------------------------------------------------------------------------- We provide agent skills for coding assistants like Claude Code, Cursor, Windsurf, and others. Install via npx (Recommended) Install as Claude Skill Manually npx skills add plastic-labs/honcho ### [​](https://docs.honcho.dev/v3/documentation/introduction/vibecoding#available-skills) Available Skills #### [​](https://docs.honcho.dev/v3/documentation/introduction/vibecoding#honcho-integration) honcho-integration **For new integrations.** This skill helps you add Honcho to an existing Python or TypeScript codebase. It provides a guided, interactive experience: 1. **Explores your codebase** to understand your language, framework, and existing AI/LLM integrations 2. **Interviews you** about which entities should be peers, your preferred integration pattern, and session structure 3. **Implements the integration** based on your answers—installing the SDK, creating peers, configuring sessions, and wiring up the chat endpoint 4. **Verifies the setup** to ensure everything is configured correctly Invoke with `/honcho-integration` in your coding agent. #### [​](https://docs.honcho.dev/v3/documentation/introduction/vibecoding#migrate-honcho-py-/-migrate-honcho-ts) migrate-honcho-py / migrate-honcho-ts **For SDK upgrades.** Migrates code from v1.6.0 to v2.0.0 (required for Honcho 3.0.0+). Use when upgrading the SDK or seeing errors about removed APIs like `observations`, `Representation`, `.core`, or `get_config`. Both skills handle: terminology changes (`Observation` → `Conclusion`), `Representation` class removal, method renames, and streaming API updates. | Python | TypeScript | | --- | --- | | `/migrate-honcho-py` | `/migrate-honcho-ts` | | `AsyncHoncho` → `.aio` accessor | `@honcho-ai/core` removal | | | `snake_case` → `camelCase` | * * * [​](https://docs.honcho.dev/v3/documentation/introduction/vibecoding#universal-starter-prompt) Universal Starter Prompt -------------------------------------------------------------------------------------------------------------------------- I want to start building with Honcho - an open source memory library for building stateful agents. ## Honcho Resources **Documentation:** - Main docs: https://docs.honcho.dev - API Reference: https://docs.honcho.dev/v3/api-reference/introduction - Quickstart: https://docs.honcho.dev/v3/documentation/introduction/quickstart - Architecture: https://docs.honcho.dev/v3/documentation/core-concepts/architecture **Code & Examples:** - Core repo: https://github.com/plastic-labs/honcho - Python SDK: https://github.com/plastic-labs/honcho-python - TypeScript SDK: https://github.com/plastic-labs/honcho-node - Discord bot starter: https://github.com/plastic-labs/discord-python-starter - Telegram bot example: https://github.com/plastic-labs/telegram-python-starter **What Honcho Does:** Honcho is an open source memory library with a managed service for building stateful agents. It enables agents to build and maintain state about any entity--users, agents, groups, ideas, and more. Because it's a continual learning system, it understands entities that change over time. When you write messages to Honcho, they're stored and processed in the background. Custom reasoning models perform formal logical reasoning to generate conclusions about each peer. These conclusions are stored as representations that you can query to provide rich context for your agents. **Architecture Overview:** - Core primitives: Workspaces contain Peers (any entity that persists but changes) and Sessions (interaction threads between peers) - Peers can observe other peers in sessions (configurable with observe_me and observe_others) - Background reasoning processes messages to extract premises, draw conclusions, and build representations - Representations enable continuous improvement as new messages refine existing conclusions and scaffold new ones over time - Chat endpoint provides personalized responses based on learned context - Supports any LLM (OpenAI, Anthropic, open source) - Can use managed service or self-host Please assess the resources above and ask me relevant questions to help build a well-structured application using Honcho. Consider asking about: - What I'm trying to build - My technical preferences and stack - Whether I want to use the managed service or self-host - My experience level with the technologies involved - Specific features I need (multi-peer sessions, perspective-taking, streaming, etc.) Once you understand my needs, help me create a working implementation with proper memory and statefulness. [Quickstart](https://docs.honcho.dev/v3/documentation/introduction/quickstart) [Architecture](https://docs.honcho.dev/v3/documentation/core-concepts/architecture) ⌘I --- # Guides, Cookbooks, and Integrations - Honcho [Skip to main content](https://docs.honcho.dev/v3/guides/overview#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Overview Guides, Cookbooks, and Integrations [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [AI Assistants](https://docs.honcho.dev/v3/guides/overview#ai-assistants) * [Platform Connectors](https://docs.honcho.dev/v3/guides/overview#platform-connectors) * [Agent Frameworks](https://docs.honcho.dev/v3/guides/overview#agent-frameworks) * [Migrations](https://docs.honcho.dev/v3/guides/overview#migrations) Honcho plugs into whatever you’re already building. Add memory to an AI assistant, connect an external data source, wire Honcho into your agent framework, or migrate from another provider. [​](https://docs.honcho.dev/v3/guides/overview#ai-assistants) AI Assistants ------------------------------------------------------------------------------ Add persistent memory to AI assistants and agents: Claude Code ----------- Long-term memory that survives context wipes, session restarts, and project switches MCP Server ---------- Add Honcho memory to Claude Desktop, Cursor, Windsurf, Cline, and any MCP client Hermes Agent ------------ Cross-session memory for Nous Research’s Hermes agent OpenClaw -------- Memory across every channel — WhatsApp, Telegram, Discord, Slack, and more Agent Zero ---------- Persistent memory plugin for the Agent Zero framework [​](https://docs.honcho.dev/v3/guides/overview#platform-connectors) Platform Connectors ------------------------------------------------------------------------------------------ Connect external platforms to Honcho: Discord Bot ----------- Build a Discord bot that remembers users across conversations Telegram Bot ------------ Create a Telegram bot with persistent user understanding Gmail ----- Import email threads into Honcho — peers, sessions, and messages from your inbox Granola ------- Ingest meeting transcripts with speaker turns and participant data Paperclip --------- Add Honcho memory to Paperclip companies, agents, issues, and documents Reachy Mini ----------- Build an embodied voice robot with long-term memory [​](https://docs.honcho.dev/v3/guides/overview#agent-frameworks) Agent Frameworks ------------------------------------------------------------------------------------ Use Honcho as a memory layer in your agent orchestration stack: LangGraph --------- Add persistent memory and theory of mind to your LangGraph agents CrewAI ------ Give CrewAI agents memory that persists across sessions Zo Computer ----------- Persistent memory skill for Zo Computer AI workflows n8n --- Build intelligent automation workflows with persistent memory [​](https://docs.honcho.dev/v3/guides/overview#migrations) Migrations ------------------------------------------------------------------------ Coming from another memory provider? Migrate from Mem0 ----------------- Transfer your data and update your integration code [Claude Code](https://docs.honcho.dev/v3/guides/integrations/claude-code) ⌘I --- # OpenClaw - Honcho [Skip to main content](https://docs.honcho.dev/v3/guides/integrations/openclaw#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Integrations OpenClaw [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Install the Plugin](https://docs.honcho.dev/v3/guides/integrations/openclaw#install-the-plugin) * [Migrating Legacy Memory](https://docs.honcho.dev/v3/guides/integrations/openclaw#migrating-legacy-memory) * [Legacy files](https://docs.honcho.dev/v3/guides/integrations/openclaw#legacy-files) * [Upload to Honcho](https://docs.honcho.dev/v3/guides/integrations/openclaw#upload-to-honcho) * [How It Works](https://docs.honcho.dev/v3/guides/integrations/openclaw#how-it-works) * [Multi-Agent Support](https://docs.honcho.dev/v3/guides/integrations/openclaw#multi-agent-support) * [AI Tools](https://docs.honcho.dev/v3/guides/integrations/openclaw#ai-tools) * [Data Retrieval (fast, no LLM)](https://docs.honcho.dev/v3/guides/integrations/openclaw#data-retrieval-fast-no-llm) * [Q&A (LLM-powered)](https://docs.honcho.dev/v3/guides/integrations/openclaw#q%26a-llm-powered) * [CLI Commands](https://docs.honcho.dev/v3/guides/integrations/openclaw#cli-commands) * [Configuration](https://docs.honcho.dev/v3/guides/integrations/openclaw#configuration) * [Self-Hosted Honcho](https://docs.honcho.dev/v3/guides/integrations/openclaw#self-hosted-honcho) * [Local File Search (QMD Integration)](https://docs.honcho.dev/v3/guides/integrations/openclaw#local-file-search-qmd-integration) * [Setup](https://docs.honcho.dev/v3/guides/integrations/openclaw#setup) * [Available Tools](https://docs.honcho.dev/v3/guides/integrations/openclaw#available-tools) * [Next Steps](https://docs.honcho.dev/v3/guides/integrations/openclaw#next-steps) [OpenClaw](https://openclaw.ai/) is a general AI agent that can perform actions on behalf of a user. The Honcho plugin gives OpenClaw memory across every channel — WhatsApp, Telegram, Discord, Slack, and more. Honcho can run entirely locally with OpenClaw — no external API required. Keep your data on your machine while getting full memory capabilities across all channels. See the [self-hosting guide](https://docs.honcho.dev/v3/contributing/self-hosting) to get started. For OpenClaw’s own documentation on Honcho, see the [Honcho Memory guide](https://docs.openclaw.ai/concepts/memory-honcho) . [​](https://docs.honcho.dev/v3/guides/integrations/openclaw#install-the-plugin) Install the Plugin ----------------------------------------------------------------------------------------------------- openclaw plugins install @honcho-ai/openclaw-honcho openclaw honcho setup openclaw gateway --force `openclaw honcho setup` prompts for your API key, writes the config, and optionally uploads any legacy memory files to Honcho. **Alternative: ClawHub Skill**The `honcho-setup` skill handles installation and migration interactively from a chat session: npx clawhub install honcho-setup # Restart OpenClaw, then invoke the skill from a session openclaw plugins install @honcho-ai/openclaw-honcho openclaw gateway restart [​](https://docs.honcho.dev/v3/guides/integrations/openclaw#migrating-legacy-memory) Migrating Legacy Memory --------------------------------------------------------------------------------------------------------------- If you have existing workspace memory files (`USER.md`, `MEMORY.md`, `IDENTITY.md`, `memory/`, `canvas/`, etc.), `openclaw honcho setup` will detect them and offer to migrate them. Migration is **non-destructive** — files are uploaded to Honcho. Originals are never deleted or moved. ### [​](https://docs.honcho.dev/v3/guides/integrations/openclaw#legacy-files) Legacy files **User/owner files** (content describes the user): * `USER.md`, `IDENTITY.md`, `MEMORY.md` * All files in `memory/` and `canvas/` directories **Agent/self files** (content describes the agent): * `SOUL.md`, `AGENTS.md`, `TOOLS.md`, `BOOTSTRAP.md` ### [​](https://docs.honcho.dev/v3/guides/integrations/openclaw#upload-to-honcho) Upload to Honcho Files are uploaded via `session.uploadFile()`. User/owner files go to the owner peer; agent/self files go to the openclaw peer. [​](https://docs.honcho.dev/v3/guides/integrations/openclaw#how-it-works) How It Works ----------------------------------------------------------------------------------------- Once installed, the plugin runs automatically: * **Message Observation** — After every AI turn, the conversation is persisted to Honcho. Both user and agent messages are observed, allowing Honcho to build and refine its models. * **Tool-Based Context Access** — The AI can query Honcho mid-conversation using tools like `honcho_context`, `honcho_search_conclusions`, `honcho_search_messages`, and `honcho_ask` to retrieve relevant context. Context is injected during OpenClaw’s `before_prompt_build` phase, ensuring accurate turn boundaries. * **Dual Peer Model** — Honcho maintains separate representations: one for the user (preferences, facts, communication style) and one for the agent (personality, learned behaviors). Each OpenClaw agent gets its own Honcho peer (`agent-{id}`), so multi-agent workspaces maintain isolated memory. * **Clean Persistence** — Platform metadata (conversation info, sender headers, thread context, forwarded messages) is stripped before saving to Honcho, ensuring only meaningful content is persisted. [​](https://docs.honcho.dev/v3/guides/integrations/openclaw#multi-agent-support) Multi-Agent Support ------------------------------------------------------------------------------------------------------- OpenClaw uses a multi-agent architecture where a primary agent can spawn **subagents** to handle specialized tasks. The Honcho plugin is fully aware of this hierarchy: * **Automatic Subagent Detection** — When OpenClaw spawns a subagent, the plugin tracks the parent→child relationship via the `subagent_spawned` hook. Each subagent session records its `parentPeerId` in metadata. * **Parent Observer Peer** — The spawning agent is added as a silent observer in the subagent’s Honcho session (`observeMe: false, observeOthers: true`). This gives Honcho visibility into the full agent tree — the parent can see what its subagents are doing without its own messages being attributed to the subagent session. [​](https://docs.honcho.dev/v3/guides/integrations/openclaw#ai-tools) AI Tools --------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v3/guides/integrations/openclaw#data-retrieval-fast-no-llm) Data Retrieval (fast, no LLM) | Tool | Description | | --- | --- | | `honcho_context` | User knowledge across all sessions. `detail='card'` for key facts, `'full'` for broad representation. | | `honcho_search_conclusions` | Semantic vector search over stored conclusions ranked by relevance. | | `honcho_search_messages` | Find specific messages across all sessions. Filter by sender, date, or metadata. | | `honcho_session` | Current session history and summary. Supports semantic search within the session. | ### [​](https://docs.honcho.dev/v3/guides/integrations/openclaw#q&a-llm-powered) Q&A (LLM-powered) | Tool | Description | | --- | --- | | `honcho_ask` | Ask Honcho a question about the user. `depth='quick'` for facts, `'thorough'` for synthesis. | [​](https://docs.honcho.dev/v3/guides/integrations/openclaw#cli-commands) CLI Commands ----------------------------------------------------------------------------------------- openclaw honcho setup # Configure API key and migrate legacy files openclaw honcho status # Connection status openclaw honcho ask # Query Honcho about the user openclaw honcho search [-k N] [-d D] # Semantic search (topK, maxDistance) [​](https://docs.honcho.dev/v3/guides/integrations/openclaw#configuration) Configuration ------------------------------------------------------------------------------------------- Run `openclaw honcho setup` to configure interactively, or set values directly in `~/.openclaw/openclaw.json` under `plugins.entries["openclaw-honcho"].config`. | Key | Default | Description | | --- | --- | --- | | `apiKey` | — | Honcho API key (required for managed; omit for self-hosted). | | `workspaceId` | `"openclaw"` | Honcho workspace ID for memory isolation. | | `baseUrl` | `"https://api.honcho.dev"` | API endpoint (for self-hosted instances). | ### [​](https://docs.honcho.dev/v3/guides/integrations/openclaw#self-hosted-honcho) Self-Hosted Honcho Point the plugin to your local instance and follow the [self-hosting guide](https://github.com/plastic-labs/honcho?tab=readme-ov-file#local-development) to get started: openclaw honcho setup # Enter blank API key, set Base URL to http://localhost:8000 [​](https://docs.honcho.dev/v3/guides/integrations/openclaw#local-file-search-qmd-integration) Local File Search (QMD Integration) ------------------------------------------------------------------------------------------------------------------------------------- The plugin automatically exposes OpenClaw’s `memory_search` and `memory_get` tools when a [memory backend](https://docs.openclaw.ai/concepts/memory) is configured, allowing both Honcho memory and local file search together. ### [​](https://docs.honcho.dev/v3/guides/integrations/openclaw#setup) Setup 1. Install [QMD](https://github.com/tobi/qmd) on your server 2. Configure OpenClaw to use QMD as the memory backend in `~/.openclaw/openclaw.json`: { "memory": { "backend": "qmd" } } OpenClaw manages QMD collections automatically from your workspace memory files and any extra paths in `memory.qmd.paths`. See the [QMD Memory Engine docs](https://docs.openclaw.ai/concepts/memory-qmd) for full setup. 3. Restart the gateway: openclaw gateway restart ### [​](https://docs.honcho.dev/v3/guides/integrations/openclaw#available-tools) Available Tools When QMD is configured, you get both Honcho and local file tools: | Tool | Source | Description | | --- | --- | --- | | `honcho_*` | Honcho | Cross-session memory, user modeling, dialectic reasoning | | `memory_search` | QMD | Search local markdown files | | `memory_get` | QMD | Retrieve file content | [​](https://docs.honcho.dev/v3/guides/integrations/openclaw#next-steps) Next Steps ------------------------------------------------------------------------------------- GitHub Repository ----------------- Source code, issues, and README. OpenClaw Memory Docs -------------------- Memory backends, search, and configuration in the OpenClaw docs. Honcho Architecture ------------------- Learn about peers, sessions, and dialectic reasoning. [n8n](https://docs.honcho.dev/v3/guides/integrations/n8n) [Hermes Agent](https://docs.honcho.dev/v3/guides/integrations/hermes) ⌘I --- # Quickstart - Honcho [Skip to main content](https://docs.honcho.dev/v2/documentation/introduction/quickstart#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Introduction Quickstart [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [Getting Started](https://docs.honcho.dev/v2/documentation/introduction/quickstart#getting-started) * [1\. Install the SDK](https://docs.honcho.dev/v2/documentation/introduction/quickstart#1-install-the-sdk) * [2\. Initialize the Client](https://docs.honcho.dev/v2/documentation/introduction/quickstart#2-initialize-the-client) * [Demo Environment (Default)](https://docs.honcho.dev/v2/documentation/introduction/quickstart#demo-environment-default) * [Production Environment](https://docs.honcho.dev/v2/documentation/introduction/quickstart#production-environment) * [3\. Create Peers](https://docs.honcho.dev/v2/documentation/introduction/quickstart#3-create-peers) * [4\. Create a Session](https://docs.honcho.dev/v2/documentation/introduction/quickstart#4-create-a-session) * [5\. Add Messages](https://docs.honcho.dev/v2/documentation/introduction/quickstart#5-add-messages) * [6\. Query for Insights](https://docs.honcho.dev/v2/documentation/introduction/quickstart#6-query-for-insights) * [7\. Putting it all together](https://docs.honcho.dev/v2/documentation/introduction/quickstart#7-putting-it-all-together) * [What Just Happened?](https://docs.honcho.dev/v2/documentation/introduction/quickstart#what-just-happened) * [Next Steps](https://docs.honcho.dev/v2/documentation/introduction/quickstart#next-steps) For production-level use, Honcho offers two powerful ways to leverage ambient personalization: our managed platform and our open source solution. Read further if you want to explore the quickstart demo. Honcho Platform --------------- Fully managed, hassle-free solution with one-click deployment Honcho Open Source ------------------ Self-hosted, fully customizable, and open source [​](https://docs.honcho.dev/v2/documentation/introduction/quickstart#getting-started) Getting Started ======================================================================================================== Have your project use Honcho’s ambient personalization capabilities in just a few steps. No signup required! By default, the SDK uses the demo server hosted at demo.honcho.dev. The demo server is meant for quick experimentation and the data is cleared on a regular basis. Do not use for production applications.For production use: 1. Get your API key at [app.honcho.dev/api-keys](https://app.honcho.dev/api-keys) 2. Set `environment="production"` and provide your `api_key` [​](https://docs.honcho.dev/v2/documentation/introduction/quickstart#1-install-the-sdk) 1\. Install the SDK -------------------------------------------------------------------------------------------------------------- Python (uv) Python (pip) TypeScript (npm) TypeScript (yarn) TypeScript (pnpm) uv add honcho-ai [​](https://docs.honcho.dev/v2/documentation/introduction/quickstart#2-initialize-the-client) 2\. Initialize the Client -------------------------------------------------------------------------------------------------------------------------- The Honcho client is the main entry point for interacting with Honcho’s API. By default, it uses the demo environment and a default workspace. ### [​](https://docs.honcho.dev/v2/documentation/introduction/quickstart#demo-environment-default) Demo Environment (Default) Python TypeScript from honcho import Honcho # Initialize client (uses demo environment and default workspace) honcho = Honcho() ### [​](https://docs.honcho.dev/v2/documentation/introduction/quickstart#production-environment) Production Environment Python TypeScript import os from honcho import Honcho # Production environment with API key honcho = Honcho( api_key=os.environ["HONCHO_API_KEY"], environment="production", # Create a workspace, otherwise set to "default" # workspaceId="your-workspace-id" ) [​](https://docs.honcho.dev/v2/documentation/introduction/quickstart#3-create-peers) 3\. Create Peers -------------------------------------------------------------------------------------------------------- Peers represent individual users, AI agents, or any conversational entity in your system: Python TypeScript alice = honcho.peer("alice") bob = honcho.peer("bob") [​](https://docs.honcho.dev/v2/documentation/introduction/quickstart#4-create-a-session) 4\. Create a Session ---------------------------------------------------------------------------------------------------------------- Sessions are independent conversations that can include multiple peers: Python TypeScript session = honcho.session("session_1") session.add_peers([alice, bob]) [​](https://docs.honcho.dev/v2/documentation/introduction/quickstart#5-add-messages) 5\. Add Messages -------------------------------------------------------------------------------------------------------- Add some conversation messages. Honcho automatically learns from these interactions: Python TypeScript session.add_messages([\ alice.message("Hi Bob, how are you?"),\ bob.message("I'm good, thank you!"),\ alice.message("What are you doing today after work?"),\ bob.message("I'm going to the gym! I've been trying to get back in shape."),\ alice.message("That's great! I should probably start exercising too."),\ bob.message("You should! I find that evening workouts help me relax."),\ ]) [​](https://docs.honcho.dev/v2/documentation/introduction/quickstart#6-query-for-insights) 6\. Query for Insights -------------------------------------------------------------------------------------------------------------------- Now ask Honcho what it’s learned - this is where the magic happens: Python TypeScript # Ask what Bob is like response = bob.chat("Tell me about Bob's interests and habits") print(response) # Returns rich context like: # "Bob is health-conscious and has been working on getting back in shape. # He regularly goes to the gym, particularly in the evenings, and finds # exercise helps him relax. He's encouraging about fitness and willing # to share advice about workout routines." [​](https://docs.honcho.dev/v2/documentation/introduction/quickstart#7-putting-it-all-together) 7\. Putting it all together ------------------------------------------------------------------------------------------------------------------------------ Python TypeScript import os from honcho import Honcho # Create your client honcho = Honcho( api_key=os.environ["HONCHO_API_KEY"], environment="production", # Create a workspace, otherwise set to "default" # workspaceId="your-workspace-id" ) # Get your Peers alice = honcho.peer("alice") bob = honcho.peer("bob") # Make a Session and add your Peers session = honcho.session("session_1") session.add_peers([alice, bob]) # Add messages sent by your Peers session.add_messages([\ alice.message("Hi Bob, how are you?"),\ bob.message("I'm good, thank you!"),\ alice.message("What are you doing today after work?"),\ bob.message("I'm going to the gym! I've been trying to get back in shape."),\ alice.message("That's great! I should probably start exercising too."),\ bob.message("You should! I find that evening workouts help me relax."),\ ]) # Get insights about your Peers response = bob.chat("Tell me about Bob's interests and habits") print(response) # Returns rich context like: # "Bob is health-conscious and has been working on getting back in shape. # He regularly goes to the gym, particularly in the evenings, and finds # exercise helps him relax. He's encouraging about fitness and willing # to share advice about workout routines." [​](https://docs.honcho.dev/v2/documentation/introduction/quickstart#what-just-happened) What Just Happened? --------------------------------------------------------------------------------------------------------------- You just got through building a simple conversation between two people, Alice and Bob. We: 1. Set up our connection to Honcho. 2. Setup who the participants of our conversation are, these are called `Peers`. 3. Made a `Session` and added our `Peers` to it. 4. Sent messages from our `Peers` 5. Chat with Honcho to get insights about one of the `Peers` in the conversation As soon as you save a message in Honcho, it will start to reason about it to pull out insights and develop a profile of the user. This is the default behavior and can be toggled off via [the configuration](https://docs.honcho.dev/v2/documentation/core-concepts/configuration) . [​](https://docs.honcho.dev/v2/documentation/introduction/quickstart#next-steps) Next Steps ---------------------------------------------------------------------------------------------- Architecture ------------ Learn about the data primitives in Honcho and how they work together Start Building -------------- Sign up for Managed Honcho and get started building agents now. Guides ------ Check out spellbooks to see different examples apps built with Honcho [Overview](https://docs.honcho.dev/v2/documentation/introduction/overview) [Vibecoding Setup](https://docs.honcho.dev/v2/documentation/introduction/vibecoding) ⌘I --- # Advanced Features - Honcho [Skip to main content](https://docs.honcho.dev/v3/documentation/features/advanced/overview#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Advanced Advanced Features [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Reasoning & Memory](https://docs.honcho.dev/v3/documentation/features/advanced/overview#reasoning-%26-memory) * [Querying & Data](https://docs.honcho.dev/v3/documentation/features/advanced/overview#querying-%26-data) Advanced features give you fine-grained control over Honcho’s behavior and implementation. [​](https://docs.honcho.dev/v3/documentation/features/advanced/overview#reasoning-&-memory) Reasoning & Memory ----------------------------------------------------------------------------------------------------------------- * [Configuration](https://docs.honcho.dev/v3/documentation/features/advanced/reasoning-configuration) - Configure reasoning models and behavior * [Summarizer](https://docs.honcho.dev/v3/documentation/features/advanced/summarizer) - Automatic session summarization * [Peer Card](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card) - Quick-reference profile of stable biographical facts about a peer * [Representation Scopes](https://docs.honcho.dev/v3/documentation/features/advanced/representation-scopes) - Directional representations for multi-peer scenarios * [Dreaming](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming) - Autonomous memory consolidation and self-improvement * [Queue Status](https://docs.honcho.dev/v3/documentation/features/advanced/queue-status) - Monitor background processing and reasoning tasks [​](https://docs.honcho.dev/v3/documentation/features/advanced/overview#querying-&-data) Querying & Data ----------------------------------------------------------------------------------------------------------- * [Search](https://docs.honcho.dev/v3/documentation/features/advanced/search) - Search across peers, sessions, and messages * [Filters](https://docs.honcho.dev/v3/documentation/features/advanced/using-filters) - Filter queries with advanced parameters * [Streaming Responses](https://docs.honcho.dev/v3/documentation/features/advanced/streaming-response) - Stream dialectic responses in real-time * [File Uploads](https://docs.honcho.dev/v3/documentation/features/advanced/file-uploads) - Ingest files into peer memory [Chat Endpoint](https://docs.honcho.dev/v3/documentation/features/chat) [Reasoning Configuration](https://docs.honcho.dev/v3/documentation/features/advanced/reasoning-configuration) ⌘I --- # Search - Honcho [Skip to main content](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Core Concepts Search [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [Search Scopes](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#search-scopes) * [Workspace Search](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#workspace-search) * [Session Search](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#session-search) * [Peer Search](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#peer-search) * [Filters and Limits](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#filters-and-limits) * [Get a specific number of results](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#get-a-specific-number-of-results) * [Get messages from a Peer in a specific Session](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#get-messages-from-a-peer-in-a-specific-session) * [Filter results by time range](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#filter-results-by-time-range) * [Filter results by metadata](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#filter-results-by-metadata) * [Best Practices](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#best-practices) * [Handle Empty Results Gracefully](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#handle-empty-results-gracefully) * [Conclusion](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#conclusion) Honcho’s search functionality allows you to find relevant messages and conversations across different scopes - from entire workspaces down to specific peers or sessions. [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#search-scopes) Search Scopes ---------------------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#workspace-search) Workspace Search Search across all content in your workspace - sessions, peers, and messages: Python TypeScript from honcho import Honcho # Initialize client honcho = Honcho() # Search across entire workspace results = honcho.search("budget planning") # Iterate through all results for result in results: print(f"Found: {result}") ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#session-search) Session Search Search within a specific session’s conversation history: Python TypeScript # Create or get a session session = honcho.session("team-meeting-jan") # Search within this session only results = session.search("action items") # Process results for result in results: print(f"Session result: {result}") ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#peer-search) Peer Search Search across all content associated with a specific peer: Python TypeScript # Create or get a peer alice = honcho.peer("alice") # Search across all of Alice's messages and interactions results = alice.search("programming") # View results for result in results: print(f"Alice's content: {result}") [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#filters-and-limits) Filters and Limits -------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#get-a-specific-number-of-results) Get a specific number of results You can specify the number of results you want to return by passing the `limit` parameter to the search method. The default is 10 results, with a maximum of 100. Python TypeScript results = honcho.search("budget planning", limit=20) ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#get-messages-from-a-peer-in-a-specific-session) Get messages from a Peer in a specific Session Combine Peer-level search with a `session_id` filter to get messages from a Peer in a specific Session. Python TypeScript my_peer = honcho.peer("my-peer") my_session = honcho.session("team-meeting-jan") results = my_peer.search("budget planning", filters={"session_id": my_session.id}) Search returns an object containing an `items` array of message objects: { "items": [\ {\ "id": "",\ "content": "",\ "peer_id": "",\ "session_id": "",\ "metadata": {},\ "created_at": "2023-11-07T05:31:56Z",\ "workspace_id": "",\ "token_count": 123\ }\ ] } ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#filter-results-by-time-range) Filter results by time range Python TypeScript results = honcho.search("budget planning", filters={"created_at": {"gte": "2024-01-01", "lte": "2024-01-31"}}) ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#filter-results-by-metadata) Filter results by metadata Python TypeScript results = honcho.search("budget planning", filters={"metadata": {"key": "value"}}) ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#best-practices) Best Practices ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#handle-empty-results-gracefully) Handle Empty Results Gracefully Python TypeScript # Always check for empty results results = honcho.search("very specific query") result_list = list(results) if result_list: print(f"Found {len(result_list)} results") for result in result_list: print(f"- {result}") else: print("No results found - try a broader search") [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/search#conclusion) Conclusion ---------------------------------------------------------------------------------------------------- Honcho’s search functionality provides powerful discovery capabilities across your conversational data. By understanding how to: * Choose the appropriate search scope (workspace, session, or peer) * Handle paginated results effectively * Combine search with context building You can build applications that provide intelligent insights and context-aware responses based on historical conversations and interactions. [Get Context](https://docs.honcho.dev/v2/documentation/core-concepts/features/get-context) [Working Representations](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep) ⌘I --- # Voice Agent - Reachy Mini - Honcho [Skip to main content](https://docs.honcho.dev/v3/guides/integrations/reachy-mini#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Tutorials Voice Agent - Reachy Mini [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [What It Does](https://docs.honcho.dev/v3/guides/integrations/reachy-mini#what-it-does) * [Setup](https://docs.honcho.dev/v3/guides/integrations/reachy-mini#setup) * [Architecture](https://docs.honcho.dev/v3/guides/integrations/reachy-mini#architecture) * [Honcho Integration](https://docs.honcho.dev/v3/guides/integrations/reachy-mini#honcho-integration) * [Memory Tools](https://docs.honcho.dev/v3/guides/integrations/reachy-mini#memory-tools) * [Multi-User Support](https://docs.honcho.dev/v3/guides/integrations/reachy-mini#multi-user-support) * [System Prompt](https://docs.honcho.dev/v3/guides/integrations/reachy-mini#system-prompt) * [Run](https://docs.honcho.dev/v3/guides/integrations/reachy-mini#run) * [Next Steps](https://docs.honcho.dev/v3/guides/integrations/reachy-mini#next-steps) [Reachy Mini](https://huggingface.co/blog/reachy-mini) is Hugging Face and Pollen Robotics’ open-source robot for human-robot interaction. This guide integrates Honcho for persistent, multi-user memory with OpenAI’s Realtime API for voice. **Real-time memory**: Honcho’s async API is designed for live voice interactions. Messages persist in the background without blocking audio, and the dialectic API returns user context fast enough for mid-conversation tool calls. GitHub Repository ----------------- Full source code Build Livestream ---------------- Watch us build it live [​](https://docs.honcho.dev/v3/guides/integrations/reachy-mini#what-it-does) What It Does -------------------------------------------------------------------------------------------- * **Face recognition** identifies users and loads their personal memory * **Honcho** stores conversations and reasons about each user over time * **OpenAI Realtime** handles low-latency voice interaction * **Gaze tracking** maintains eye contact during conversation When a user returns days later, the robot remembers their name, interests, and previous discussions. [​](https://docs.honcho.dev/v3/guides/integrations/reachy-mini#setup) Setup ------------------------------------------------------------------------------ pip install reachy-mini honcho-ai openai python-dotenv numpy scipy mediapipe face-recognition export OPENAI_API_KEY=your_openai_key export HONCHO_API_KEY=your_honcho_key # get at app.honcho.dev [​](https://docs.honcho.dev/v3/guides/integrations/reachy-mini#architecture) Architecture -------------------------------------------------------------------------------------------- Reachy Mini (camera, mic, speaker) ↓ OpenAI Realtime API (voice + tools) ↓ Honcho (memory + reasoning per user) [​](https://docs.honcho.dev/v3/guides/integrations/reachy-mini#honcho-integration) Honcho Integration -------------------------------------------------------------------------------------------------------- Initialize Honcho with a robot peer (not observed) and dynamic user peers (observed): from honcho import Honcho from honcho.api_types import PeerConfig honcho = Honcho(api_key=api_key, workspace_id="reachy-mini") # Robot peer - stores messages but isn't reasoned about robot_peer = await honcho.aio.peer( "reachy", configuration=PeerConfig(observe_me=False), ) # User peers - Honcho reasons about their preferences and history user_peer = await honcho.aio.peer(user_id) session = await honcho.aio.session(f"chat-{user_id}") Store messages in the background without blocking the voice loop: # Queue messages async - doesn't block audio playback await session.aio.add_messages(user_peer.message(transcript)) await session.aio.add_messages(robot_peer.message(response)) [​](https://docs.honcho.dev/v3/guides/integrations/reachy-mini#memory-tools) Memory Tools -------------------------------------------------------------------------------------------- The robot calls Honcho mid-conversation via OpenAI function calling — fast enough for real-time voice: | Tool | Purpose | | --- | --- | | `recall` | Query Honcho about the user (“What’s their name?”) | | `create_conclusion` | Save important facts to long-term memory | | `see` | Capture and analyze camera feed | # Recall - ask Honcho's dialectic API (returns in ~200-500ms) result = await user_peer.aio.chat( "What do I know about this user?", session=session, reasoning_level="medium" ) # Create conclusion - save a fact await user_peer.conclusions_of(user_id).aio.create([\ {"content": "Their name is Alice"}\ ]) [​](https://docs.honcho.dev/v3/guides/integrations/reachy-mini#multi-user-support) Multi-User Support -------------------------------------------------------------------------------------------------------- Face recognition identifies returning users. When a new face is detected, the agent: 1. Flushes pending transcripts to the previous user’s session 2. Switches Honcho context to the new user 3. Fetches a briefing from Honcho’s dialectic API 4. Reconnects OpenAI with fresh context and triggers a greeting # Get briefing when user is recognized briefing = await user_peer.aio.chat( "What should I know about this user? Name, interests, recent topics.", session=session, reasoning_level="low" ) [​](https://docs.honcho.dev/v3/guides/integrations/reachy-mini#system-prompt) System Prompt ---------------------------------------------------------------------------------------------- SYSTEM_PROMPT = """You are Reachy, a friendly robot. Keep responses concise. You have a recall tool for memory. ALWAYS use it before claiming you don't know something about the user. Never say "Nice to meet you" if you've met before.""" [​](https://docs.honcho.dev/v3/guides/integrations/reachy-mini#run) Run -------------------------------------------------------------------------- uv run python main.py [​](https://docs.honcho.dev/v3/guides/integrations/reachy-mini#next-steps) Next Steps ---------------------------------------------------------------------------------------- Honcho Architecture ------------------- Understand peers, sessions, and reasoning Chat Endpoint ------------- Learn about Honcho’s dialectic API Get Context ----------- Retrieve formatted conversation history GitHub code ----------- Dig into the code [Telegram Bot](https://docs.honcho.dev/v3/guides/telegram) [Gmail](https://docs.honcho.dev/v3/guides/gmail) ⌘I --- # Get Collection By Name - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection-by-name#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation collections Get Collection By Name [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const collection = await client.apps.users.collections.getByName('app_id', 'user_id', 'name'); console.log(collection.id); } main(); 200 422 { "id": "", "name": "", "user_id": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } GET http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / collections / name / {name} Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const collection = await client.apps.users.collections.getByName('app_id', 'user_id', 'name'); console.log(collection.id); } main(); 200 422 { "id": "", "name": "", "user_id": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection-by-name#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection-by-name#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection-by-name#parameter-user-id) user\_id string required ID of the user [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection-by-name#parameter-name) name string required Name of the collection to retrieve #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection-by-name#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection-by-name#response-name) name string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection-by-name#response-user-id) user\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection-by-name#response-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection-by-name#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection-by-name#response-metadata) metadata Metadata · object [Create Collection](https://docs.honcho.dev/v1/api-reference/endpoint/collections/create-collection) [Get Collection](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection) ⌘I --- # Summarizer - Honcho [Skip to main content](https://docs.honcho.dev/v3/documentation/features/advanced/summarizer#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Advanced Summarizer [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Creating Summaries](https://docs.honcho.dev/v3/documentation/features/advanced/summarizer#creating-summaries) * [Retrieving Summaries](https://docs.honcho.dev/v3/documentation/features/advanced/summarizer#retrieving-summaries) Almost all agents require, in addition to personalization and memory, a way to quickly prime a context window with a summary of the conversation (in Honcho, this is equivalent to a `session`). The general strategy for summarization is to combine a list of recent messages verbatim with a compressed LLM-generated summary of the older messages not included. Implementing this correctly, in such a way that the resulting context is: * Exhaustive: the combination of recent messages and summary should cover the entire conversation * Dynamically sized: the tokens used on both summary and recent messages should be malleable based on desired token usage * Performant: while creation of the summary by LLM introduces necessary latency, this should never add latency to an arbitrary end-user request …is a non-trivial problem. Summarization should not be necessary to re-implement for every new agent you build, so Honcho comes with a built-in solution. ### [​](https://docs.honcho.dev/v3/documentation/features/advanced/summarizer#creating-summaries) Creating Summaries Honcho already has an asynchronous task queue for the purpose of deriving facts from messages. This is the ideal place to create summaries where they won’t add latency to a message. Currently, Honcho has two configurable summary types: * Short summaries: by default, enqueued every 20 messages and given a token limit of 1000 * Long summaries: by default, enqueued every 60 messages and given a token limit of 4000 Both summaries are designed to be exhaustive: when enqueued, they are given the _prior_ summary of their type plus every message after that summary. This recursive compression process naturally biases the summary towards recent messages while still covering the entire conversation. For example, if message 160 in a conversation triggers a short summary, as it would with default settings, the summary task would retrieve the prior short summary (message 140) plus messages 141-160. It would then produce a summary of messages 0-160 and store that in the short summary slot on the session. Every session has a single slot for each summary type: new summaries replace old ones. It’s important to keep in mind that summary tasks run in the background and are not guaranteed to complete before the next message. However, they are guaranteed to complete in order, so that if a user saves 100 messages in a single batch, the short summary will first be created for messages 0-20, then 21-40, and so on, in our desired recursive way. ### [​](https://docs.honcho.dev/v3/documentation/features/advanced/summarizer#retrieving-summaries) Retrieving Summaries Summaries are retrieved from the session by the [`get_context`](https://docs.honcho.dev/v3/documentation/features/get-context) method. This method has two parameters: * `summary`: A boolean indicating whether to include the summary in the return type. The default is true. * `tokens`: An integer indicating the maximum number of tokens to use for the context. **If not provided, `get_context` will retrieve as many tokens as are required to create exhaustive conversation coverage.** The return type is simply a list of recent messages and a summary if the flag is used. These two components are dynamically sized based on the token limit. Combined, they will always be below the given token limit. Honcho reserves 60% of the context size for recent messages and 40% for the summary. There’s a critical trade-off to understand between exhaustiveness and token usage. Let’s go through some scenarios: * If the _last message_ contains more tokens than the context token limit, no summary _or_ message list is possible — both will be empty. * If the _last few messages_ contain more tokens than the context token limit, no summary is possible — the context will only contain the last 1 or 2 messages that fit in the token limit. * If the summaries contain more tokens than the context token limit, no summary is possible — the context will only contain the X most recent messages that fit in the token limit. Note that while summaries will often be smaller than their token limits, avoiding this scenario means passing a higher token limit than the Honcho-configured summary size(s). For this reason, the default token limit for `get_context` is a few times larger than the configured long summary size. The above scenarios indicate where summarization is not possible — therefore, the context retrieved will almost certainly **not** be exhaustive. Sometimes, gaps in context aren’t an issue. In these cases, it’s best to pass a reasonable token limit depending on your needs. Other cases demand exhaustive context — don’t pass a token limit and just let Honcho retrieve the ideal combination of summary and recent messages. Finally, if you don’t care about the conversation at large and just want the last few messages, set `summary` to false and `tokens` to some multiple of your desired message count. Note that context messages are not paginated, so there’s a hard limit on the number of messages that can be retrieved (currently 100,000 tokens). As a final note, remember that summaries are generated asynchronously and therefore may not be available immediately. If you batch-save a large number of messages, assume that summaries will not be available until those messages are processed, which can take seconds to minutes depending on the number of messages and the configured LLM provider. Exhaustive `get_context` calls performed during this time will likely just return the messages in the session. [Reasoning Configuration](https://docs.honcho.dev/v3/documentation/features/advanced/reasoning-configuration) [Peer Card](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card) ⌘I --- # Zo Computer - Honcho [Skip to main content](https://docs.honcho.dev/v3/guides/integrations/zo-computer#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Integrations Zo Computer [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [What It Does](https://docs.honcho.dev/v3/guides/integrations/zo-computer#what-it-does) * [Setup](https://docs.honcho.dev/v3/guides/integrations/zo-computer#setup) * [Quick Start](https://docs.honcho.dev/v3/guides/integrations/zo-computer#quick-start) * [Saving Messages](https://docs.honcho.dev/v3/guides/integrations/zo-computer#saving-messages) * [Querying Memory](https://docs.honcho.dev/v3/guides/integrations/zo-computer#querying-memory) * [Retrieving Context](https://docs.honcho.dev/v3/guides/integrations/zo-computer#retrieving-context) * [Concept Mapping](https://docs.honcho.dev/v3/guides/integrations/zo-computer#concept-mapping) * [Publishing to the Zo Marketplace](https://docs.honcho.dev/v3/guides/integrations/zo-computer#publishing-to-the-zo-marketplace) * [Next Steps](https://docs.honcho.dev/v3/guides/integrations/zo-computer#next-steps) [Zo Computer](https://zo.computer/) is a cloud AI platform where users build reusable workflows called skills. The Honcho memory skill gives any Zo workflow persistent memory — saving conversations, answering questions about past interactions, and injecting context into LLM prompts. The full source code is available on [GitHub](https://github.com/plastic-labs/honcho/tree/main/examples/zo) with working tests and Zo marketplace submission instructions. [​](https://docs.honcho.dev/v3/guides/integrations/zo-computer#what-it-does) What It Does -------------------------------------------------------------------------------------------- The skill provides three tools that any Zo workflow can call: | Tool | Description | | --- | --- | | `save_memory` | Save user or assistant messages to a Honcho session | | `query_memory` | Ask natural language questions about what Honcho remembers | | `get_context` | Retrieve conversation history formatted for LLM use (OpenAI message format) | [​](https://docs.honcho.dev/v3/guides/integrations/zo-computer#setup) Setup ------------------------------------------------------------------------------ Install dependencies: pip install honcho-ai python-dotenv Set your environment variables: HONCHO_API_KEY=your-api-key HONCHO_WORKSPACE_ID=default # optional, defaults to "default" Get your API key at [app.honcho.dev](https://app.honcho.dev/) . [​](https://docs.honcho.dev/v3/guides/integrations/zo-computer#quick-start) Quick Start ------------------------------------------------------------------------------------------ from tools.save_memory import save_memory from tools.query_memory import query_memory from tools.get_context import get_context # Save conversation turns save_memory("alice", "I love hiking in the mountains", "user", "session-1") save_memory("alice", "That sounds wonderful!", "assistant", "session-1") # Query what Honcho remembers answer = query_memory("alice", "What are my hobbies?", "session-1") print(answer) # "Alice enjoys hiking in the mountains." # Get context ready for an LLM call messages = get_context("alice", "session-1", "assistant", tokens=4000) # Returns [{"role": "user", "content": "..."}, ...] [​](https://docs.honcho.dev/v3/guides/integrations/zo-computer#saving-messages) Saving Messages -------------------------------------------------------------------------------------------------- `save_memory` creates peers and sessions automatically on first use and persists the message. save_memory( user_id="alice", # unique user identifier content="Hello!", # message text role="user", # "user" or "assistant" session_id="session-1", # conversation identifier assistant_id="assistant", # optional, defaults to "assistant" ) [​](https://docs.honcho.dev/v3/guides/integrations/zo-computer#querying-memory) Querying Memory -------------------------------------------------------------------------------------------------- `query_memory` uses Honcho’s Dialectic API to answer natural language questions grounded in stored memory. answer = query_memory( user_id="alice", query="What are my interests?", session_id="session-1", # optional — omit to query global memory ) [​](https://docs.honcho.dev/v3/guides/integrations/zo-computer#retrieving-context) Retrieving Context -------------------------------------------------------------------------------------------------------- `get_context` fetches recent conversation history within a token budget and returns it in OpenAI message format — ready to pass directly to an LLM. messages = get_context( user_id="alice", session_id="session-1", assistant_id="assistant", tokens=4000, # max tokens to include ) # Use directly: llm.chat.completions.create(messages=messages) [​](https://docs.honcho.dev/v3/guides/integrations/zo-computer#concept-mapping) Concept Mapping -------------------------------------------------------------------------------------------------- | Zo Computer | Honcho | | --- | --- | | Account | Workspace | | User | Peer | | Conversation | Session | | Message | Message | [​](https://docs.honcho.dev/v3/guides/integrations/zo-computer#publishing-to-the-zo-marketplace) Publishing to the Zo Marketplace ------------------------------------------------------------------------------------------------------------------------------------ To submit the skill to the [Zo Skills Registry](https://github.com/zocomputer/skills) : 1. Fork the `zocomputer/skills` repository 2. Copy the `examples/zo` directory into `/Community/honcho-memory/` in your fork 3. Run `bun validate` to check the skill format 4. Submit a pull request [​](https://docs.honcho.dev/v3/guides/integrations/zo-computer#next-steps) Next Steps ---------------------------------------------------------------------------------------- Source Code ----------- Full source, tests, and SKILL.md for the Zo integration Honcho Architecture ------------------- Understand peers, sessions, and how memory works Chat API -------- Learn more about querying peer memory with the Dialectic API Get Context ----------- Details on retrieving and formatting conversation context [Hermes Agent](https://docs.honcho.dev/v3/guides/integrations/hermes) [Paperclip](https://docs.honcho.dev/v3/guides/integrations/paperclip) ⌘I --- # File Uploads - Honcho [Skip to main content](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Core Concepts File Uploads [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [How It Works](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#how-it-works) * [Supported File Types](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#supported-file-types) * [Basic Usage](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#basic-usage) * [Upload Parameters](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#upload-parameters) * [File Processing Details](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#file-processing-details) * [Text Extraction](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#text-extraction) * [Chunking Strategy](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#chunking-strategy) * [Querying Uploaded Content](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#querying-uploaded-content) * [Error Handling](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#error-handling) * [Unsupported File Types](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#unsupported-file-types) * [Missing Required Fields](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#missing-required-fields) * [Complete Example: Document Analysis Assistant](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#complete-example-document-analysis-assistant) * [Error Handling](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#error-handling-2) Honcho’s file upload feature allows you to convert documents into messages automatically. Upload PDFs, text files, or JSON documents, and Honcho will extract the text content, split it into appropriately sized chunks, and create messages that become part of your peer’s knowledge or session context. This feature is perfect for ingesting documents, reports, research papers, or any text-based content that you want your AI agents to understand and reference. [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#how-it-works) How It Works -------------------------------------------------------------------------------------------------------------- When you upload a file, Honcho: 1. **Extracts text** from the file using specialized processors based on file type 2. **Creates messages** with the extracted content split into chunks that fit within message limits (messages are limited to 50,000 characters) 3. **Queues processing** for background analysis and insight derivation like any other message The file content becomes part of the peer’s representation, making it available for natural language queries and context retrieval. [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#supported-file-types) Supported File Types ------------------------------------------------------------------------------------------------------------------------------ Honcho currently supports the following file types with more to come: * **PDF files** (`application/pdf`) - Text extraction with page numbers * **Text files** (`text/*`) - Plain text, markdown, code files, etc. * **JSON files** (`application/json`) - Structured data converted to readable format Files are processed in memory and not stored on disk. Only the extracted text content is preserved in Honcho’s message system. [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#basic-usage) Basic Usage ------------------------------------------------------------------------------------------------------------ Python TypeScript from honcho import Honcho # Initialize client honcho = Honcho() # Create session and peer session = honcho.session("research-session") user = honcho.peer("researcher") # Upload a PDF to a session with open("research_paper.pdf", "rb") as file: messages = session.upload_file( file=file, peer_id=user.id, ) print(f"Created {len(messages)} messages from the PDF") [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#upload-parameters) Upload Parameters ------------------------------------------------------------------------------------------------------------------------ The upload methods accept the following parameters: | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `file` | File | Yes | File to upload | | `peer_id` | String | Yes | ID of the peer creating the messages | [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#file-processing-details) File Processing Details ------------------------------------------------------------------------------------------------------------------------------------ ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#text-extraction) Text Extraction **PDF Files**: Text is extracted page by page with page numbers preserved: [Page 1] Introduction This document provides... [Page 2] Methodology Our approach involves... **Text Files**: Content is decoded using UTF-8, UTF-16, or Latin-1 encoding as needed. **JSON Files**: Structured data is converted to string format. ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#chunking-strategy) Chunking Strategy Large files are automatically split into chunks of ~49,500 characters. The system seeks to break at natural boundaries if present: 1. Paragraph breaks (`\n\n`) 2. Line breaks (`\n`) 3. Sentence endings (`.` ) 4. Word boundaries ( ) Each chunk becomes a separate message, maintaining the original document structure. [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#querying-uploaded-content) Querying Uploaded Content ---------------------------------------------------------------------------------------------------------------------------------------- Once files are uploaded, you can query the content using Honcho’s natural language interface: Python TypeScript # Query what was learned from the uploaded documents response = user.chat("What are the key findings from the research papers I uploaded?") print(response) # Ask about specific documents response = user.chat("What does the quarterly report say about revenue growth?") print(response) # Get context from the uploaded documents for LLM integration context = session.get_context(tokens=3000) messages = context.to_openai(assistant=assistant) [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#error-handling) Error Handling ------------------------------------------------------------------------------------------------------------------ ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#unsupported-file-types) Unsupported File Types Files with unsupported content types will raise an exception: try: messages = session.upload_file( file=open("image.jpg", "rb"), peer_id=user.id ) except Exception as e: print(f"Upload failed: {e}") # Error: "Could not process file image.jpg: Unsupported file type: image/jpeg" ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#missing-required-fields) Missing Required Fields Session uploads require a `peer_id` parameter: # This will fail for session uploads try: messages = session.upload_file(file=file) # Missing peer_id except ValueError as e: print(f"Validation error: {e}") [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#complete-example-document-analysis-assistant) Complete Example: Document Analysis Assistant ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Here’s a complete example of building a document analysis assistant: Python TypeScript from honcho import Honcho # Initialize honcho = Honcho() session = honcho.session("document-analysis") user = honcho.peer("analyst") assistant = honcho.peer("analysis-bot") def upload_document(file_path, description): """Upload a document and add it to the session""" with open(file_path, "rb") as file: messages = session.upload_file( file=file, peer_id=user.id, ) return messages def analyze_documents(): """Get AI analysis of uploaded documents""" context = session.get_context(tokens=4000) messages = context.to_openai(assistant=assistant) # Add analysis request messages.append({ "role": "user", "content": "Please analyze all the documents I've uploaded and provide a comprehensive summary of the key findings, trends, and recommendations." }) # Call OpenAI (or your preferred LLM) # response = openai.chat.completions.create(model="gpt-4", messages=messages) # return response.choices[0].message.content return "Analysis would be generated here" # Upload multiple documents documents = [\ ("quarterly_report.pdf", "Q3 2024 Quarterly Financial Report"),\ ("market_research.pdf", "Market Analysis and Competitive Landscape"),\ ("product_roadmap.pdf", "Product Development Roadmap 2024-2025")\ ] for file_path, description in documents: messages = upload_document(file_path, description) print(f"Uploaded {file_path}: {len(messages)} messages created") # Get AI analysis analysis = analyze_documents() print("Document Analysis:", analysis) [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/file-uploads#error-handling-2) Error Handling -------------------------------------------------------------------------------------------------------------------- * **Always wrap uploads in try-catch blocks** for robust error handling * **Validate file types** before upload to avoid processing errors * **Handle large files gracefully** with progress indicators * **Implement retry logic** for network failures [Using Filters](https://docs.honcho.dev/v2/documentation/core-concepts/features/using-filters) [Queue Status](https://docs.honcho.dev/v2/documentation/core-concepts/features/queue-status) ⌘I --- # Working Representations - Honcho [Skip to main content](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Core Concepts Working Representations [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [How Working Representations Are Created](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#how-working-representations-are-created) * [Basic Usage](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#basic-usage) * [Semantic Search in Representations](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#semantic-search-in-representations) * [Parameters](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#parameters) * [Understanding Representation Content](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#understanding-representation-content) * [Current Mental State Predictions](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#current-mental-state-predictions) * [Relevant Long-term Facts](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#relevant-long-term-facts) * [Example Representation Structure](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#example-representation-structure) * [When Representations Are Updated](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#when-representations-are-updated) * [Message Processing Pipeline](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#message-processing-pipeline) * [Processing Triggers](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#processing-triggers) * [Comparison with Chat Method](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#comparison-with-chat-method) * [Use working\_rep() when:](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#use-working-rep-when) * [Use peer.chat() when:](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#use-peer-chat-when) * [Best Practices](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#best-practices) * [1\. Ensure Availability Before Using](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#1-ensure-availability-before-using) * [2\. Use for Fast Analytics](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#2-use-for-fast-analytics) * [3\. Combine with Fresh Analysis When Needed](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#3-combine-with-fresh-analysis-when-needed) * [Conclusion](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#conclusion) Working representations are Honcho’s system for accessing cached psychological models that capture what peers know, think, and remember. Unlike the `chat()` method which generates fresh representations on-demand, the `working_rep()` method retrieves pre-computed representations that have been automatically built and stored as conversations progress. [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#how-working-representations-are-created) How Working Representations Are Created ------------------------------------------------------------------------------------------------------------------------------------------------------------------- Working representations are automatically generated and cached through Honcho’s background processing system: 1. **Automatic Generation**: When messages are added to sessions, they trigger background jobs that analyze conversations using theory of mind inference and long-term memory integration 2. **Cached Storage**: The generated representations are stored in the database as metadata on `Peer` objects (for global representations) or `SessionPeer` objects (for session-scoped representations) 3. **Retrieval**: The `working_rep()` method provides fast access to these cached representations without requiring LLM processing **Cached vs On-Demand**: `working_rep()` retrieves cached representations for fast access, while `peer.chat()` generates fresh representations using the dialectic system. Use `working_rep()` when you need fast access to stored knowledge, and `chat()` when you need current analysis with custom queries. [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#basic-usage) Basic Usage ----------------------------------------------------------------------------------------------------------- Working representations are accessed through the `working_rep()` method on Session or Peer objects: Python TypeScript from honcho import Honcho # Initialize client honcho = Honcho() # Create peers and session user = honcho.peer("user-123") assistant = honcho.peer("ai-assistant") session = honcho.session("support-conversation") # Add conversation to trigger representation generation session.add_messages([\ user.message("I'm having trouble with my billing account"),\ assistant.message("I can help with that. What specific issue are you seeing?"),\ user.message("My credit card was charged twice last month"),\ assistant.message("I see duplicate charges on your account. Let me refund one of them.")\ ]) # Chat to generate a working representation response = user.chat("What is this user's main concern right now?", session_id=session.id) # Retrieve the cached working representation for the user user_representation = session.working_rep("user-123") print("Cached user representation:", user_representation) # Or access from the peer directly peer_representation = user.working_rep() [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#semantic-search-in-representations) Semantic Search in Representations --------------------------------------------------------------------------------------------------------------------------------------------------------- Working representations support semantic search to retrieve the most relevant observations for a given query. This is useful when you want to focus the representation on specific topics. ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#parameters) Parameters | Parameter | Type | Description | | --- | --- | --- | | `search_query` | `str` | Semantic search query to filter relevant observations | | `search_top_k` | `int` | Number of semantic search results to include (1-100) | | `search_max_distance` | `float` | Maximum semantic distance threshold (0.0-1.0) | | `include_most_derived` | `bool` | Whether to include the most recently derived observations | | `max_observations` | `int` | Maximum number of observations to include (1-100) | Python TypeScript # Get representation focused on a specific topic billing_rep = session.working_rep( "user-123", search_query="billing and payment issues", search_top_k=10, search_max_distance=0.8, include_most_derived=True, max_observations=25 ) # Get representation from peer with target # What user-123 knows about the assistant local_rep = session.working_rep( "user-123", target="ai-assistant", search_query="support interactions" ) # Access from peer object with semantic search user_rep = user.working_rep( session=session, search_query="preferences", search_top_k=5 ) [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#understanding-representation-content) Understanding Representation Content ------------------------------------------------------------------------------------------------------------------------------------------------------------- Cached working representations contain structured psychological analysis based on conversation history. The format typically includes: ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#current-mental-state-predictions) Current Mental State Predictions Information about what the peer is currently thinking, feeling, or focused on based on recent messages. ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#relevant-long-term-facts) Relevant Long-term Facts Facts about the peer that have been extracted and stored over time from various conversations. ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#example-representation-structure) Example Representation Structure Python TypeScript # Example of what a cached representation might contain representation = session.working_rep("user-123") # Typical content structure: """ PREDICTION ABOUT THE USER'S CURRENT MENTAL STATE: The user appears frustrated with a billing issue, specifically concerning duplicate charges. They seem to have some confidence in the support process as they provided specific details. RELEVANT LONG-TERM FACTS ABOUT THE USER: - User has had previous billing inquiries - User prefers direct, specific communication - User is detail-oriented when reporting issues """ print("Full representation:", representation) [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#when-representations-are-updated) When Representations Are Updated ----------------------------------------------------------------------------------------------------------------------------------------------------- Working representations are automatically updated through Honcho’s background processing system: ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#message-processing-pipeline) Message Processing Pipeline 1. **Message Creation**: When messages are added via `session.add_messages()` or similar methods 2. **Background Queuing**: Messages are queued for processing in the background 3. **Theory of Mind Analysis**: The system analyzes conversation patterns and psychological states 4. **Fact Extraction**: Long-term facts are extracted and stored in vector embeddings 5. **Representation Generation**: New representations are created combining current analysis with historical facts 6. **Cache Update**: The new representation is stored in the database metadata ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#processing-triggers) Processing Triggers Representations are updated when: * New messages are added to sessions * Sufficient new content has accumulated * The background processing system determines an update is needed [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#comparison-with-chat-method) Comparison with Chat Method ------------------------------------------------------------------------------------------------------------------------------------------- Understanding when to use `working_rep()` vs `peer.chat()`: ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#use-working-rep-when) Use `working_rep()` when: * You need fast access to stored psychological models * You want to see what the system has already learned about a peer * You’re building dashboards or analytics that display peer understanding * You need consistent representations that don’t change between calls ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#use-peer-chat-when) Use `peer.chat()` when: * You need to ask specific questions about a peer * You want fresh analysis based on current conversation state * You need customized insights for specific use cases * You want to query about relationships between peers Python TypeScript # Fast cached access cached_rep = session.working_rep("user-123") print("Cached:", cached_rep[:100] + "...") # Custom query with fresh analysis custom_analysis = user.chat("What is this user's main concern right now?", session_id=session.id) print("Fresh analysis:", custom_analysis) [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#best-practices) Best Practices ----------------------------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#1-ensure-availability-before-using) 1\. Ensure Availability Before Using Make sure that a representation exists before processing it by using the chat endpoint first. ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#2-use-for-fast-analytics) 2\. Use for Fast Analytics Cached representations are ideal for analytics dashboards: Python TypeScript # Good: Fast dashboard updates using cached data def update_analytics_dashboard(sessions): analytics = {} for session in sessions: for peer_id in session.get_peer_ids(): rep = session.working_rep(peer_id) analytics[peer_id] = analyze_representation(rep) return analytics ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#3-combine-with-fresh-analysis-when-needed) 3\. Combine with Fresh Analysis When Needed Use cached representations for baseline understanding, and fresh analysis for current insights: Python TypeScript # Get baseline understanding from cache baseline = session.working_rep("user-123") # Get current specific insights current_state = user.chat("How is this user feeling right now?", session_id=session.id) # Combine for comprehensive view comprehensive_view = { "baseline_knowledge": baseline, "current_analysis": current_state } [​](https://docs.honcho.dev/v2/documentation/core-concepts/features/working-rep#conclusion) Conclusion --------------------------------------------------------------------------------------------------------- Working representations provide fast access to cached psychological models that Honcho automatically builds and maintains. By understanding how to: * Retrieve cached representations using `session.working_rep()` * Parse and interpret representation content * Handle cases where representations aren’t available * Combine cached and fresh analysis appropriately You can build efficient applications that leverage Honcho’s continuous learning about peer knowledge and mental states without the latency of real-time generation. [Search](https://docs.honcho.dev/v2/documentation/core-concepts/features/search) [Streaming Responses](https://docs.honcho.dev/v2/documentation/core-concepts/features/streaming-response) ⌘I --- # Delete Document - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/documents/delete-document#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation documents Delete Document [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const document = await client.apps.users.collections.documents.delete( 'app_id', 'user_id', 'collection_id', 'document_id', ); console.log(document); } main(); 422 { "detail": [\ {\ "loc": [\ ""\ ],\ "msg": "",\ "type": ""\ }\ ] } DELETE http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / collections / {collection\_id} / documents / {document\_id} Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const document = await client.apps.users.collections.documents.delete( 'app_id', 'user_id', 'collection_id', 'document_id', ); console.log(document); } main(); 422 { "detail": [\ {\ "loc": [\ ""\ ],\ "msg": "",\ "type": ""\ }\ ] } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/delete-document#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/delete-document#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/delete-document#parameter-user-id) user\_id string required ID of the user [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/delete-document#parameter-collection-id) collection\_id string required ID of the collection [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/delete-document#parameter-document-id) document\_id string required ID of the document to delete #### Response 200 application/json Successful Response [Update Document](https://docs.honcho.dev/v1/api-reference/endpoint/documents/update-document) [Query Documents](https://docs.honcho.dev/v1/api-reference/endpoint/documents/query-documents) ⌘I --- # Update Collection - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/collections/update-collection#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation collections Update Collection [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const collection = await client.apps.users.collections.update('app_id', 'user_id', 'collection_id'); console.log(collection.id); } main(); 200 422 { "id": "", "name": "", "user_id": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } PUT http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / collections / {collection\_id} Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const collection = await client.apps.users.collections.update('app_id', 'user_id', 'collection_id'); console.log(collection.id); } main(); 200 422 { "id": "", "name": "", "user_id": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/update-collection#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/update-collection#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/update-collection#parameter-user-id) user\_id string required ID of the user [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/update-collection#parameter-collection-id) collection\_id string required ID of the collection to update #### Body application/json Updated collection parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/update-collection#body-name-one-of-0) name string | null [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/update-collection#body-metadata-one-of-0) metadata Metadata · object #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/update-collection#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/update-collection#response-name) name string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/update-collection#response-user-id) user\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/update-collection#response-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/update-collection#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/update-collection#response-metadata) metadata Metadata · object [Get Collection](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection) [Delete Collection](https://docs.honcho.dev/v1/api-reference/endpoint/collections/delete-collection) ⌘I --- # Get Collection - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation collections Get Collection [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const collection = await client.apps.users.collections.get('app_id', 'user_id'); console.log(collection.id); } main(); 200 422 { "id": "", "name": "", "user_id": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } GET http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / collections Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const collection = await client.apps.users.collections.get('app_id', 'user_id'); console.log(collection.id); } main(); 200 422 { "id": "", "name": "", "user_id": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection#parameter-user-id) user\_id string required ID of the user #### Query Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection#parameter-one-of-0) collection\_id string | null Collection ID to retrieve. If not provided, uses JWT #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection#response-name) name string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection#response-user-id) user\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection#response-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection#response-metadata) metadata Metadata · object [Get Collection By Name](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collection-by-name) [Update Collection](https://docs.honcho.dev/v1/api-reference/endpoint/collections/update-collection) ⌘I --- # Get Collections - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collections#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation collections Get Collections [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { // Automatically fetches more pages as needed. for await (const collection of client.apps.users.collections.list('app_id', 'user_id')) { console.log(collection.id); } } main(); 200 422 { "items": [\ {\ "id": "",\ "name": "",\ "user_id": "",\ "app_id": "",\ "created_at": "2023-11-07T05:31:56Z",\ "metadata": {}\ }\ ], "total": 1, "page": 2, "size": 2, "pages": 1 } POST http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / collections / list Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { // Automatically fetches more pages as needed. for await (const collection of client.apps.users.collections.list('app_id', 'user_id')) { console.log(collection.id); } } main(); 200 422 { "items": [\ {\ "id": "",\ "name": "",\ "user_id": "",\ "app_id": "",\ "created_at": "2023-11-07T05:31:56Z",\ "metadata": {}\ }\ ], "total": 1, "page": 2, "size": 2, "pages": 1 } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collections#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collections#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collections#parameter-user-id) user\_id string required ID of the user #### Query Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collections#parameter-one-of-0) reverse boolean | null default:false Whether to reverse the order of results [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collections#parameter-page) page integer default:1 Page number Required range: `x >= 1` [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collections#parameter-size) size integer default:50 Page size Required range: `1 <= x <= 100` #### Body application/json Filtering options for the collections list [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collections#body-one-of-0-filter-one-of-0) filter Filter · object #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collections#response-items) items Collection · object\[\] required Show child attributes [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collections#response-total) total integer required Required range: `x >= 0` [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collections#response-page) page integer required Required range: `x >= 1` [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collections#response-size) size integer required Required range: `x >= 1` [​](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collections#response-pages) pages integer Required range: `x >= 0` [Update Metamessage](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage) [Create Collection](https://docs.honcho.dev/v1/api-reference/endpoint/collections/create-collection) ⌘I --- # Create Document - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/documents/create-document#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation documents Create Document [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const document = await client.apps.users.collections.documents.create( 'app_id', 'user_id', 'collection_id', { content: 'x' }, ); console.log(document.id); } main(); 200 422 { "id": "", "content": "", "created_at": "2023-11-07T05:31:56Z", "collection_id": "", "app_id": "", "user_id": "", "metadata": {} } POST http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / collections / {collection\_id} / documents Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const document = await client.apps.users.collections.documents.create( 'app_id', 'user_id', 'collection_id', { content: 'x' }, ); console.log(document.id); } main(); 200 422 { "id": "", "content": "", "created_at": "2023-11-07T05:31:56Z", "collection_id": "", "app_id": "", "user_id": "", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/create-document#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/create-document#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/create-document#parameter-user-id) user\_id string required ID of the user [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/create-document#parameter-collection-id) collection\_id string required ID of the collection #### Body application/json Document creation parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/create-document#body-content) content string required Required string length: `1 - 100000` [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/create-document#body-metadata) metadata Metadata · object #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/create-document#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/create-document#response-content) content string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/create-document#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/create-document#response-collection-id) collection\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/create-document#response-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/create-document#response-user-id) user\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/create-document#response-metadata) metadata Metadata · object [Get Documents](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-documents) [Get Document](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-document) ⌘I --- # The Honcho Dashboard - Honcho [Skip to main content](https://docs.honcho.dev/v3/documentation/reference/platform#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Reference The Honcho Dashboard [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [1\. Go to app.honcho.dev](https://docs.honcho.dev/v3/documentation/reference/platform#1-go-to-app-honcho-dev) * [2\. Activate your Honcho instance](https://docs.honcho.dev/v3/documentation/reference/platform#2-activate-your-honcho-instance) * [3\. Manage API Keys](https://docs.honcho.dev/v3/documentation/reference/platform#3-manage-api-keys) * [4\. Test with API Playground](https://docs.honcho.dev/v3/documentation/reference/platform#4-test-with-api-playground) * [5\. Workspaces](https://docs.honcho.dev/v3/documentation/reference/platform#5-workspaces) * [6\. Peer Dashboard & Utilities](https://docs.honcho.dev/v3/documentation/reference/platform#6-peer-dashboard-%26-utilities) * [7\. Session Dashboard & Utilities](https://docs.honcho.dev/v3/documentation/reference/platform#7-session-dashboard-%26-utilities) * [8\. Webhooks Integration](https://docs.honcho.dev/v3/documentation/reference/platform#8-webhooks-integration) * [9\. Organization Member Access](https://docs.honcho.dev/v3/documentation/reference/platform#9-organization-member-access) * [Go Further](https://docs.honcho.dev/v3/documentation/reference/platform#go-further) * [Next Steps](https://docs.honcho.dev/v3/documentation/reference/platform#next-steps) Sign up to start using Honcho! ------------------------------ Start using the platform to manage Honcho instances for your workspace or app. The quickest way to begin using Honcho in production is with the [Honcho Cloud Service](https://app.honcho.dev/) . Sign up, generate an API key, and start building with Honcho. [​](https://docs.honcho.dev/v3/documentation/reference/platform#1-go-to-app-honcho-dev) 1\. Go to [app.honcho.dev](https://app.honcho.dev/) ----------------------------------------------------------------------------------------------------------------------------------------------- Create an account to start using Honcho. If a teammate already uses Honcho, ask them to invite you to their organization. Otherwise, you’ll see a banner prompting you to create a new one. ![Honcho Platform Dashboard](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/welcome-to-honcho.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=701f22a18abfe069a09cbce488098ad4) Once you’ve created an organization, you’ll be taken to the dashboard and see the Welcome page with integration guidance and links to documentation. ![Honcho Dashboard Getting Started](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/get-started-copy.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=3e40132eb420f5b4d4361919909687c1) Each organization has dedicated infrastructure running to isolate your workloads. Once you add a valid payment method under the [Billing](https://app.honcho.dev/billing) page, your instance will turn on. [​](https://docs.honcho.dev/v3/documentation/reference/platform#2-activate-your-honcho-instance) 2\. Activate your Honcho instance ------------------------------------------------------------------------------------------------------------------------------------- Navigate to the [Billing](https://app.honcho.dev/billing) page to add a payment method. Your Honcho instance provisions automatically, and you can monitor the deployment on the [Instance Status](https://app.honcho.dev/status) page until all systems show a green check mark. ![Instance Status Page](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/status-page.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=e199758f189cdd793e1542d2c2cf6438) You can also upgrade Honcho when new versions are made available directly from the status page. ![Upgrade Honcho](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/upgrade-honcho.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=94baab874fca159106fe30c5dac7c419) The **Performance** page provides comprehensive monitoring with usage metrics, health analytics, API response times, and endpoint usage across Honcho. ![Performance Analytics Dashboard](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/performance-analytics.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=95f123fe43b59cc2f98ec2ad632de1d4) [​](https://docs.honcho.dev/v3/documentation/reference/platform#3-manage-api-keys) 3\. Manage API Keys --------------------------------------------------------------------------------------------------------- The [API Keys](https://app.honcho.dev/api-keys) page allows you to create and manage authentication tokens for different environments. You can create admin-level keys with full instance access or scope keys to specific `Workspaces`, `Peers`, or `Sessions`. ![API Key Management Dashboard](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/api-keys.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=c9196ebf1ee6d9da9b533ad31940a831) [​](https://docs.honcho.dev/v3/documentation/reference/platform#4-test-with-api-playground) 4\. Test with API Playground --------------------------------------------------------------------------------------------------------------------------- The [API Playground](https://app.honcho.dev/playground) provides a Postman-like interface to test queries, explore endpoints, and validate your integration. Authenticate with an API key and send requests directly to your Honcho instance with real-time responses and full request/response logging. ![API Playground Interface](https://mintcdn.com/plasticlabs/6O7xRufE052olsvb/images/app-screenshots/api-playground.png?w=2500&fit=max&auto=format&n=6O7xRufE052olsvb&q=85&s=10a3b2ad44c842628268d4e33353c85e) [​](https://docs.honcho.dev/v3/documentation/reference/platform#5-workspaces) 5\. Workspaces ----------------------------------------------------------------------------------------------- The [Explore](https://app.honcho.dev/explore) page provides comprehensive `Workspace` management where you can create workspaces and begin exploring the platform. Each `Workspace` serves as a container for organizing your Honcho data. ![Workspace Table](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/explore-honcho.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=88e78ac31581b8373c07c7db76ade4be) Click into any workspace to access a general overview of `Peers` and `Sessions`. Here you can quickly create `Peers`, `Sessions`, and add multiple `Peers` to any `Session`. Edit the metadata and configuration for a `Workspace` with the Edit Config button. Click into any entity to navigate to their respective utilities pages or click the expand icon to view Workspace-wide `Peers` and `Sessions` data tables with more details. ![Workspace Dashboard Overview](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/workspace-dash.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=10b5d58b5cb81e07ceb8e948398336ec) [​](https://docs.honcho.dev/v3/documentation/reference/platform#6-peer-dashboard-&-utilities) 6\. Peer Dashboard & Utilities ------------------------------------------------------------------------------------------------------------------------------- Expand the `Peers` list from the `Workspace` dashboard to see a detailed view of `Peers`. ![Peer Dashboard](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/peer-dash.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=b5f859ec19097a9f7dc11bd62c099b00) Click into any peer to navigate to their respective utilities page. Next to the `Peer` name you can edit the [Peer Configuration](https://docs.honcho.dev/v3/documentation/features/advanced/reasoning-configuration) , and in the tabs below, explore all utilities for the `Peer`. ![Peer Management Dashboard](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/peer-utilities.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=f5aee393f48a871837df8896683aaa80) Utilities include: * **Message search** across all sessions for a `Peer` * **Chat** to query `Peer` representations with an optional session scope (results vary based on the `Peer`’s configuration) ![Chat Endpoint](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/chat-endpoint.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=7cd9e0b597db9df32aa970d768b2c676) * **Session logs** view which `Sessions` the `Peer` is active * **Peer configuration and metadata management** including [Session-Peer Configuration](https://docs.honcho.dev/v3/documentation/features/advanced/reasoning-configuration#session-configuration) ![Peer Management Dashboard](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/peer-utilities.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=f5aee393f48a871837df8896683aaa80) [​](https://docs.honcho.dev/v3/documentation/reference/platform#7-session-dashboard-&-utilities) 7\. Session Dashboard & Utilities ------------------------------------------------------------------------------------------------------------------------------------- Click into the sessions view within a workspace to see a table of all of your `Sessions` data. ![Sessions Table](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/session-dash.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=f524d4bb9ca462fff7ea78dcd190d4f7) Click into a `Session` to open its utilities page. ![Session Utilities](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/session-utilities.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=0dfccbdd96ea094f5f44645d1bc6f82b) Here you can: * **View and add Messages** within the `Session`; filter messages by `Peer` * **Advanced search** across `Session` messages * **Peer management** for adding/removing `Peers` and editing a `Peer`’s Session-level configuration * **Get Context** to generate LLM-ready context with customizable token limits ![Get Context](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/get-context.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=8be43a9459ac3059be295c4fbc4cbe2e) [​](https://docs.honcho.dev/v3/documentation/reference/platform#8-webhooks-integration) 8\. Webhooks Integration ------------------------------------------------------------------------------------------------------------------- The [Webhooks](https://app.honcho.dev/webhooks) page enables Webhook creation and management. ![Webhooks Dashboard](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/webhooks-page.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=6c38b372b5cebeb4c6a2e50d272ea41a) [​](https://docs.honcho.dev/v3/documentation/reference/platform#9-organization-member-access) 9\. Organization Member Access ------------------------------------------------------------------------------------------------------------------------------- The [Members](https://app.honcho.dev/members) page provides organization administration to manage your team’s access to Honcho with the ability to grant admin permissions. ![Members Dashboard](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/members-dashboard.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=54d5b957c7452caa3c52f4493e9bb9a2) [​](https://docs.honcho.dev/v3/documentation/reference/platform#go-further) Go Further ----------------------------------------------------------------------------------------- View the [Architecture](https://docs.honcho.dev/v3/documentation/core-concepts/architecture) to see how Honcho works under the hood. Dive into our [API Reference](https://docs.honcho.dev/v3/api-reference) to explore all available endpoints. [​](https://docs.honcho.dev/v3/documentation/reference/platform#next-steps) Next Steps ----------------------------------------------------------------------------------------- Sign up to Honcho Platform -------------------------- Get started with managed Honcho instances Join our Discord ---------------- Connect with 1000+ developers building with Honcho Contribute to Honcho -------------------- View our guidelines and explore the codebase Explore Examples ---------------- See Honcho in action with real examples [File Uploads](https://docs.honcho.dev/v3/documentation/features/advanced/file-uploads) [SDK Reference](https://docs.honcho.dev/v3/documentation/reference/sdk) ⌘I --- # Get Document - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-document#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation documents Get Document [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const document = await client.apps.users.collections.documents.get( 'app_id', 'user_id', 'collection_id', 'document_id', ); console.log(document.id); } main(); 200 422 { "id": "", "content": "", "created_at": "2023-11-07T05:31:56Z", "collection_id": "", "app_id": "", "user_id": "", "metadata": {} } GET http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / collections / {collection\_id} / documents / {document\_id} Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const document = await client.apps.users.collections.documents.get( 'app_id', 'user_id', 'collection_id', 'document_id', ); console.log(document.id); } main(); 200 422 { "id": "", "content": "", "created_at": "2023-11-07T05:31:56Z", "collection_id": "", "app_id": "", "user_id": "", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-document#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-document#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-document#parameter-user-id) user\_id string required ID of the user [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-document#parameter-collection-id) collection\_id string required ID of the collection [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-document#parameter-document-id) document\_id string required ID of the document to retrieve #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-document#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-document#response-content) content string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-document#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-document#response-collection-id) collection\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-document#response-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-document#response-user-id) user\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-document#response-metadata) metadata Metadata · object [Create Document](https://docs.honcho.dev/v1/api-reference/endpoint/documents/create-document) [Update Document](https://docs.honcho.dev/v1/api-reference/endpoint/documents/update-document) ⌘I --- # Create Key - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/keys/create-key#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation keys Create Key [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const key = await client.keys.create(); console.log(key); } main(); 422 { "detail": [\ {\ "loc": [\ ""\ ],\ "msg": "",\ "type": ""\ }\ ] } POST http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / keys Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const key = await client.keys.create(); console.log(key); } main(); 422 { "detail": [\ {\ "loc": [\ ""\ ],\ "msg": "",\ "type": ""\ }\ ] } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/keys/create-key#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Query Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/keys/create-key#parameter-one-of-0) app\_id string | null ID of the app to scope the key to [​](https://docs.honcho.dev/v1/api-reference/endpoint/keys/create-key#parameter-one-of-0) user\_id string | null ID of the user to scope the key to [​](https://docs.honcho.dev/v1/api-reference/endpoint/keys/create-key#parameter-one-of-0) session\_id string | null ID of the session to scope the key to [​](https://docs.honcho.dev/v1/api-reference/endpoint/keys/create-key#parameter-one-of-0) collection\_id string | null ID of the collection to scope the key to [​](https://docs.honcho.dev/v1/api-reference/endpoint/keys/create-key#parameter-one-of-0) expires\_at string | null #### Response 200 application/json Successful Response [Update Message](https://docs.honcho.dev/v1/api-reference/endpoint/messages/update-message) [Create Metamessage](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage) ⌘I --- # Get Documents - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-documents#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation documents Get Documents [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { // Automatically fetches more pages as needed. for await (const document of client.apps.users.collections.documents.list( 'app_id', 'user_id', 'collection_id', )) { console.log(document.id); } } main(); 200 422 { "items": [\ {\ "id": "",\ "content": "",\ "created_at": "2023-11-07T05:31:56Z",\ "collection_id": "",\ "app_id": "",\ "user_id": "",\ "metadata": {}\ }\ ], "total": 1, "page": 2, "size": 2, "pages": 1 } POST http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / collections / {collection\_id} / documents / list Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { // Automatically fetches more pages as needed. for await (const document of client.apps.users.collections.documents.list( 'app_id', 'user_id', 'collection_id', )) { console.log(document.id); } } main(); 200 422 { "items": [\ {\ "id": "",\ "content": "",\ "created_at": "2023-11-07T05:31:56Z",\ "collection_id": "",\ "app_id": "",\ "user_id": "",\ "metadata": {}\ }\ ], "total": 1, "page": 2, "size": 2, "pages": 1 } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-documents#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-documents#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-documents#parameter-user-id) user\_id string required ID of the user [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-documents#parameter-collection-id) collection\_id string required ID of the collection #### Query Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-documents#parameter-one-of-0) reverse boolean | null default:false Whether to reverse the order of results [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-documents#parameter-page) page integer default:1 Page number Required range: `x >= 1` [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-documents#parameter-size) size integer default:50 Page size Required range: `1 <= x <= 100` #### Body application/json Filtering options for the documents list [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-documents#body-one-of-0-filter-one-of-0) filter Filter · object #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-documents#response-items) items Document · object\[\] required Show child attributes [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-documents#response-total) total integer required Required range: `x >= 0` [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-documents#response-page) page integer required Required range: `x >= 1` [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-documents#response-size) size integer required Required range: `x >= 1` [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-documents#response-pages) pages integer Required range: `x >= 0` [Delete Collection](https://docs.honcho.dev/v1/api-reference/endpoint/collections/delete-collection) [Create Document](https://docs.honcho.dev/v1/api-reference/endpoint/documents/create-document) ⌘I --- # Quickstart - Honcho [Skip to main content](https://docs.honcho.dev/v3/documentation/introduction/quickstart#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Introduction Quickstart [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [1\. Install the SDK](https://docs.honcho.dev/v3/documentation/introduction/quickstart#1-install-the-sdk) * [2\. Initialize the Client](https://docs.honcho.dev/v3/documentation/introduction/quickstart#2-initialize-the-client) * [3\. Create Peers](https://docs.honcho.dev/v3/documentation/introduction/quickstart#3-create-peers) * [4\. Add Messages to Sessions](https://docs.honcho.dev/v3/documentation/introduction/quickstart#4-add-messages-to-sessions) * [5\. Query for Insights](https://docs.honcho.dev/v3/documentation/introduction/quickstart#5-query-for-insights) * [Next Steps](https://docs.honcho.dev/v3/documentation/introduction/quickstart#next-steps) Let’s get started with Honcho. In this quickstart, you will: * Set up a workspace with peers (user and assistant) * Ingest messages from across multiple sessions * Query the reasoning Honcho produces to get synthesized insights about the user Running the code below requires an API key. Create and account and get your API key at [app.honcho.dev](https://app.honcho.dev/) under “API KEYS”.Every new tenant gets $100.00 in free credits on sign up. The code below costs ~$0.04 to run, so don’t worry—still plenty of free credits for iterating. #### [​](https://docs.honcho.dev/v3/documentation/introduction/quickstart#1-install-the-sdk) 1\. Install the SDK Python (uv) Python (pip) TypeScript (npm) TypeScript (yarn) TypeScript (pnpm) uv add honcho-ai #### [​](https://docs.honcho.dev/v3/documentation/introduction/quickstart#2-initialize-the-client) 2\. Initialize the Client The Honcho client is the main entry point for interacting with Honcho’s API. It uses a workspace called `default` unless specified, so let’s create a `first-honcho-test` workspace for this quickstart. Python TypeScript from honcho import Honcho # Initialize client honcho = Honcho(workspace_id="first-honcho-test", api_key=HONCHO_API_KEY) #### [​](https://docs.honcho.dev/v3/documentation/introduction/quickstart#3-create-peers) 3\. Create Peers Python TypeScript user = honcho.peer("user") assistant = honcho.peer("assistant") #### [​](https://docs.honcho.dev/v3/documentation/introduction/quickstart#4-add-messages-to-sessions) 4\. Add Messages to Sessions We’ve generated an example conversation dataset with 14 messages across 4 sessions. At a high level, the conversation contains a user chatting with an assistant to get help debugging software infrastructure problems for work _and_ jam strategy on a side project they’re working on. Spoiler alert—the user is way more interested in their side project. Create a file called `conversation.json` and add the content in the accordion below. Then we’ll loop through the sessions and messages in that file and write them to Honcho.Example conversation.json Example Conversation { "sessions": [\ {\ "id": "session_1",\ "messages": [\ {\ "role": "user",\ "content": "containers getting OOM killed in CI after someone on my team updated the base image. quick fix?"\ },\ {\ "role": "assistant",\ "content": "OOM kills after a base image update usually means the new image has higher memory requirements. Quick fix: bump the memory limit in your CI config. If you need to unblock fast, you could also pin back to the previous base image version temporarily."\ }\ ]\ },\ {\ "id": "session_2",\ "messages": [\ {\ "role": "user",\ "content": "hey, been playing with honcho for a side project. do you know if there's a limit on how many users i can have?"\ },\ {\ "role": "assistant",\ "content": "Honcho's free tier is based on context ingested, not number of users - so you can have as many users as you want, you're just limited by how much content you're processing. What are you building?"\ },\ {\ "role": "user",\ "content": "ok so basically it's a personal finance assistant that actually remembers your situation - like it knows you're saving for a house, that you hate subscriptions, that you always regret impulse buys over $50. i've been thinking a lot about the UX, like when should it proactively bring up past context vs wait for you to ask? and how do you balance feeling \"known\" vs feeling surveilled? i have a whole notion doc on this lol"\ },\ {\ "role": "assistant",\ "content": "That's a really thoughtful approach to the personalization problem! The \"known vs surveilled\" tension is exactly right - the best experiences feel like talking to a friend who remembers, not a system that tracks. Proactive context works best when it's in service of the user's stated goals."\ }\ ]\ },\ {\ "id": "session_3",\ "messages": [\ {\ "role": "user",\ "content": "do i need to update docker-compose too or just the CI yaml for that memory thing"\ },\ {\ "role": "assistant",\ "content": "Just the CI yaml for the memory limit - docker-compose is separate and only matters if you're hitting the same OOM issue locally."\ },\ {\ "role": "user",\ "content": "k. oh btw 3 friends are using the finance app now, they keep asking when they can pay me lol. one of them said it's the first budgeting thing that \"gets\" her"\ },\ {\ "role": "assistant",\ "content": "That's awesome - \"when can I pay you\" is the best kind of validation. And that quote about it being the first thing that \"gets\" her is exactly the value prop of personalized memory. Sounds like you're onto something real."\ }\ ]\ },\ {\ "id": "session_4",\ "messages": [\ {\ "role": "user",\ "content": "if i wanted to charge like $5/mo for the finance app, would honcho's pricing still make sense at that price point? trying to figure out unit economics early"\ },\ {\ "role": "assistant",\ "content": "You should be fine at that price point. Unlike other memory frameworks that charge you to access your own data, Honcho only charges for the reasoning layer - ingestion and inference. Storage and retrieval are free. So your unit economics are mostly about how often you're synthesizing insights, not how much history you're keeping."\ },\ {\ "role": "user",\ "content": "ok interesting. wish i had more time to work on this"\ },\ {\ "role": "assistant",\ "content": "Yeah, sounds like you've got something worth making time for. The early traction is real."\ }\ ]\ }\ ] } Python TypeScript import json # Load conversation data with open("conversation.json", "r") as f: data = json.load(f) # Process each session for session_data in data["sessions"]: session = honcho.session(session_data["id"]) session.add_peers([user, assistant]) # Add messages with correct roles messages = [] for msg in session_data["messages"]: if msg["role"] == "user": messages.append(user.message(msg["content"])) elif msg["role"] == "assistant": messages.append(assistant.message(msg["content"])) session.add_messages(messages) #### [​](https://docs.honcho.dev/v3/documentation/introduction/quickstart#5-query-for-insights) 5\. Query for Insights Now ask Honcho what it’s learned—this is where the magic happens: Python TypeScript response = user.chat("What should I know about this user? 3 sentences max") print(response) Honcho needs a short amount of time to process messages you write to it. There are several utilities to [check the status](https://docs.honcho.dev/v3/documentation/features/advanced/queue-status) of the queue. Honcho also offers numerous ways to query reasoning to fit latency needs: see the [Get Context](https://docs.honcho.dev/v3/documentation/features/get-context) page. The response will look something like this: > User is a personal finance app developer building a personalized finance assistant that’s generating real demand (friends are already asking when they can pay). They’re notably thoughtful about product design, carefully considering the UX balance between making users feel “known” versus “surveilled” when their app proactively surfaces remembered context like savings goals and spending regrets. They’re business-minded and working through unit economics early, exploring a $5/month subscription model with usage-based cost structure focused on insight generation frequency rather than data storage—though they wish they had more time to dedicate to the project. Honcho synthesizes signal by reasoning about the user to draw conclusions beyond what was explicitly stated. It identifies the user as “notably thoughtful about product design”, “business-minded” from the discussion of unit economics, and surfaces the signal that they desire to work on the project more. This is rich personal context for domain-specific agents to do what they want with. * A life coach agent might see “they wish they had more time to dedicate to the project” and “friends are already asking when they can pay” and ask “have you thought about what it would take to go full-time?” * A productivity agent might see the same pattern and say “let’s protect your weekend time for the finance app.” * A financial advisor agent might see it and ask “what runway would you need to make the leap?” Honcho acts almost like a detective—it reasons about new and existing evidence in order to form conclusions that can be used to make a _case_. These conclusions wait to be composed dynamically based on how you, the ~judge~ developer, query it. This approach is what drives our [pareto-frontier](https://evals.honcho.dev/) performance on memory benchmarks, and our custom models allow us to optimize speed and cost. [​](https://docs.honcho.dev/v3/documentation/introduction/quickstart#next-steps) Next Steps ---------------------------------------------------------------------------------------------- You just saw how Honcho reasons about data to build rich peer representations. In this quickstart, you: * Set up a workspace with peers (user and assistant) * Ingested messages across multiple sessions * Queried the reasoning to get synthesized insights about the user Here’s the full working code if you want to run it yourself:Full Scripts Python Typescript # uv sync # uv run python test.py import json import time import uuid from honcho import Honcho from dotenv import load_dotenv load_dotenv() # Initialize Honcho client with a unique workspace workspace_id = f"docs-example-{uuid.uuid4().hex[:8]}" honcho = Honcho(environment="production", workspace_id=workspace_id) # Create peers to represent the user and assistant user = honcho.peer("user") assistant = honcho.peer("assistant") # Load conversation data from JSON file with open("conversation.json", "r") as f: conversation_data = json.load(f) # Import historical conversation sessions for session_data in conversation_data["sessions"]: session = honcho.session(session_data["id"]) session.add_peers([user, assistant]) # Convert messages to peer messages with correct attribution messages = [] for msg in session_data["messages"]: if msg["role"] == "user": messages.append(user.message(msg["content"])) elif msg["role"] == "assistant": messages.append(assistant.message(msg["content"])) session.add_messages(messages) # Query insights about the user based on conversation history response = user.chat("What should I know about this user? 3 sentences max") print(response) From here, you can explore how to use Honcho’s features in your own applications: Get Context ----------- Learn how to fetch the right context for your agent’s next response Architecture ------------ Deep dive into how Honcho’s primitives fit together Chat Endpoint ------------- Chat with Honcho about your users Guides ------ Integration patterns and advanced use cases [Overview](https://docs.honcho.dev/v3/documentation/introduction/overview) [Agentic Development](https://docs.honcho.dev/v3/documentation/introduction/vibecoding) ⌘I --- # The Honcho Dashboard - Honcho [Skip to main content](https://docs.honcho.dev/v2/documentation/reference/platform#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Reference The Honcho Dashboard [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [1\. Go to app.honcho.dev](https://docs.honcho.dev/v2/documentation/reference/platform#1-go-to-app-honcho-dev) * [2\. Activate your Honcho instance](https://docs.honcho.dev/v2/documentation/reference/platform#2-activate-your-honcho-instance) * [3\. Manage API Keys](https://docs.honcho.dev/v2/documentation/reference/platform#3-manage-api-keys) * [4\. Test with API Playground](https://docs.honcho.dev/v2/documentation/reference/platform#4-test-with-api-playground) * [Step-by-Step:](https://docs.honcho.dev/v2/documentation/reference/platform#step-by-step) * [Example Usage](https://docs.honcho.dev/v2/documentation/reference/platform#example-usage) * [5\. Workspaces](https://docs.honcho.dev/v2/documentation/reference/platform#5-workspaces) * [6\. Peer Dashboard & Utilities](https://docs.honcho.dev/v2/documentation/reference/platform#6-peer-dashboard-%26-utilities) * [7\. Session Dashboard & Utilities](https://docs.honcho.dev/v2/documentation/reference/platform#7-session-dashboard-%26-utilities) * [8\. Performance Monitoring & Analytics](https://docs.honcho.dev/v2/documentation/reference/platform#8-performance-monitoring-%26-analytics) * [9\. Webhooks Integration](https://docs.honcho.dev/v2/documentation/reference/platform#9-webhooks-integration) * [10\. Organization Member Access](https://docs.honcho.dev/v2/documentation/reference/platform#10-organization-member-access) * [Go Further](https://docs.honcho.dev/v2/documentation/reference/platform#go-further) * [Next Steps](https://docs.honcho.dev/v2/documentation/reference/platform#next-steps) Sign up to start using Honcho! ------------------------------ Start using the platform to manage Honcho instances for your workspace or app. The quickest way to begin using Honcho in production is with the [Honcho Cloud Platform](https://app.honcho.dev/) . Sign up, generate an API key, and start building with Honcho. [​](https://docs.honcho.dev/v2/documentation/reference/platform#1-go-to-app-honcho-dev) 1\. Go to [app.honcho.dev](https://app.honcho.dev/) ----------------------------------------------------------------------------------------------------------------------------------------------- Create an account to start using Honcho. If a teammate already uses Honcho, ask them to invite you to their organization. Otherwise, you’ll see a banner prompting you to create a new one. ![Honcho Platform Dashboard](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/welcome-to-honcho.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=701f22a18abfe069a09cbce488098ad4) Once you’ve created an organization, you’ll be taken to the welcome dashboard. ![Honcho Dashboard Getting Started](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/get-started-copy.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=3e40132eb420f5b4d4361919909687c1) Each organization has dedicated infrastructure running to isolate your workloads. Once you add a valid payment method under the [Billing](https://app.honcho.dev/billing) page, your instance will turn on. [​](https://docs.honcho.dev/v2/documentation/reference/platform#2-activate-your-honcho-instance) 2\. Activate your Honcho instance ------------------------------------------------------------------------------------------------------------------------------------- With credits and a payment method on file (managed via the [Billing](https://app.honcho.dev/billing) page), your Honcho instance will be provisioned and ready to use. Monitor your machine status, and check for version upgrades on the [Instance Status](https://app.honcho.dev/status) page. ![Instance Status Page](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/status-page.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=e199758f189cdd793e1542d2c2cf6438) If there is an upgrade available you will see an indicator like this: ![Upgrade Honcho](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/upgrade-honcho.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=94baab874fca159106fe30c5dac7c419) Upgrading your machines may take a few minutes and you can monitor progress. If for any reason your machine goes offline, you will see a red status indicator. Navigate to the [Instance Status](https://app.honcho.dev/status) page and try to trigger a refresh of your machines. [​](https://docs.honcho.dev/v2/documentation/reference/platform#3-manage-api-keys) 3\. Manage API Keys --------------------------------------------------------------------------------------------------------- The [API Keys](https://app.honcho.dev/api-keys) page allows you to create and manage authentication tokens for different environments. You can create admin-level keys with full instance access or scope keys to specific `Workspaces`, `Peers`, or `Sessions`. ![API Key Management Dashboard](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/api-keys.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=c9196ebf1ee6d9da9b533ad31940a831) [​](https://docs.honcho.dev/v2/documentation/reference/platform#4-test-with-api-playground) 4\. Test with API Playground --------------------------------------------------------------------------------------------------------------------------- The [API Playground](https://app.honcho.dev/playground) provides a developer-friendly interface to quickly iterate and test queries, explore endpoints, and validate your integration directly from your browser—no code required. ![API Playground Interface](https://mintcdn.com/plasticlabs/6O7xRufE052olsvb/images/app-screenshots/api-playground.png?w=2500&fit=max&auto=format&n=6O7xRufE052olsvb&q=85&s=10a3b2ad44c842628268d4e33353c85e) The playground automatically loads all available API endpoints to match your Honcho instance version. Endpoints can be filtered by category at the top of the list. If you prefer, you can set up your queries in the UI and copy to cURL for help with building scripts or general terminal use. ### [​](https://docs.honcho.dev/v2/documentation/reference/platform#step-by-step) Step-by-Step: **1\. Select an Endpoint**: Choose your desired endpoint from the available list. **2\. Choose Path Parameters**: For fields like Workspace, Session, or Peer, select options from dropdown menus—no need to manually enter IDs. **3\. Add Request Body Data**: Complete any required fields for POST/PUT requests. **4\. Execute or Copy Request**: Run it directly or copy as cURL to use elsewhere (just add your API key). ### [​](https://docs.honcho.dev/v2/documentation/reference/platform#example-usage) Example Usage Build a complete conversation flow without ever leaving the playground: 1. **Create a Workspace**: select `POST Get or Create Workspace` and type workspace name into the request body → Returns workspace ID 2. **Create new Peer(s)**: select `POST Get or Create Peer,` choose your workspace from the dropdown, and type peer name into the request body. (repeat for each peer) → Returns peer ID 3. **POST Get or Create Session** `POST /sessions` selecting your workspace from the dropdown then type session name into the request body → Returns session ID and adds to dropdown 4. **POST Create Messages for Session** `POST /messages` selecting your workspace & session from the dropdown then type peer id(s) and message content into the request body → Adds message(s) to the session [​](https://docs.honcho.dev/v2/documentation/reference/platform#5-workspaces) 5\. Workspaces ----------------------------------------------------------------------------------------------- The [Explore](https://app.honcho.dev/explore) page provides comprehensive `Workspace` management where you can create workspaces and begin exploring the platform. Each `Workspace` serves as a container for organizing your Honcho data. ![Workspace Table](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/explore-honcho.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=88e78ac31581b8373c07c7db76ade4be) Click into any workspace to access a general overview of `Peers` and `Sessions`. Here you can quickly create `Peers`, `Sessions`, and add multiple `Peers` to any `Session`. Edit the metadata and configuration for a `Workspace` with the Edit Config button. Click into any entity to navigate to their respective utilities pages or click the expand icon to view Workspace-wide `Peers` and `Sessions` data tables with more details. ![Workspace Dashboard Overview](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/workspace-dash.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=10b5d58b5cb81e07ceb8e948398336ec) [​](https://docs.honcho.dev/v2/documentation/reference/platform#6-peer-dashboard-&-utilities) 6\. Peer Dashboard & Utilities ------------------------------------------------------------------------------------------------------------------------------- Expand the `Peers` list from the `Workspace` dashboard to see a detailed view of `Peers`. ![Peer Dashboard](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/peer-dash.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=b5f859ec19097a9f7dc11bd62c099b00) Click into any peer to navigate to their respective utilities page. Next to the `Peer` name you can edit the [Global Peer Configuration](https://docs.honcho.dev/v2/documentation/core-concepts/configuration) , and in the tabs below, explore all utilities for the `Peer`. ![Peer Management Dashboard](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/peer-utilities.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=f5aee393f48a871837df8896683aaa80) Utilities include: * **Message search** across all sessions for a `Peer` * **Dialectic Chat** to query `Peer` representations globally or session-scoped (results vary dependant on the `Peer`’s configuration) ![Chat Endpoint](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/chat-endpoint.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=7cd9e0b597db9df32aa970d768b2c676) * **Session logs** view which `Sessions` the `Peer` is active * **Peer configuration and metadata management** including [Session-Peer Configuration](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#session-peer-configuration) ![Peer Management Dashboard](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/peer-utilities.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=f5aee393f48a871837df8896683aaa80) [​](https://docs.honcho.dev/v2/documentation/reference/platform#7-session-dashboard-&-utilities) 7\. Session Dashboard & Utilities ------------------------------------------------------------------------------------------------------------------------------------- Click into the sessions view within a workspace to see a table of all of your `Sessions` data. ![Sessions Table](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/session-dash.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=f524d4bb9ca462fff7ea78dcd190d4f7) Click into a `Session` to open its utilities page. ![Session Utilities](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/session-utilities.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=0dfccbdd96ea094f5f44645d1bc6f82b) Here you can: * **View and add Messages** within the `Session`; filter messages by `Peer` * **Advanced search** across `Session` messages * **Peer management** for adding/removing `Peers` and editing a `Peer`’s Session-level configuration * **Get Context** to generate LLM-ready context with customizable token limits ![Get Context](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/get-context.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=8be43a9459ac3059be295c4fbc4cbe2e) [​](https://docs.honcho.dev/v2/documentation/reference/platform#8-performance-monitoring-&-analytics) 8\. Performance Monitoring & Analytics ----------------------------------------------------------------------------------------------------------------------------------------------- The **Performance** page offers comprehensive monitoring tools, including usage metrics, health analytics, API response times, and endpoint usage across Honcho. ![Performance Analytics Dashboard](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/performance-analytics.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=95f123fe43b59cc2f98ec2ad632de1d4) [​](https://docs.honcho.dev/v2/documentation/reference/platform#9-webhooks-integration) 9\. Webhooks Integration ------------------------------------------------------------------------------------------------------------------- The [Webhooks](https://app.honcho.dev/webhooks) page allows managing and creation of webhooks for Honcho. React to events in real-time—such as message delivery, session updates, peer state changes, and more—by sending event payloads via HTTP POST requests to your provided endpoints. ![Webhooks Dashboard](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/webhooks-page.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=6c38b372b5cebeb4c6a2e50d272ea41a) ![Create New Webhook](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/webhooks-create.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=967a79b671e010ffdcf6205eaf608978) [​](https://docs.honcho.dev/v2/documentation/reference/platform#10-organization-member-access) 10\. Organization Member Access --------------------------------------------------------------------------------------------------------------------------------- The [Members](https://app.honcho.dev/members) page provides organization administration to manage your team’s access to Honcho with the ability to grant admin permissions. ![Members Dashboard](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/app-screenshots/members-dashboard.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=54d5b957c7452caa3c52f4493e9bb9a2) [​](https://docs.honcho.dev/v2/documentation/reference/platform#go-further) Go Further ----------------------------------------------------------------------------------------- View the [Architecture](https://docs.honcho.dev/v2/documentation/core-concepts/architecture) to see how Honcho works under the hood. Dive into our [API Reference](https://docs.honcho.dev/v2/api-reference) to explore all available endpoints. [​](https://docs.honcho.dev/v2/documentation/reference/platform#next-steps) Next Steps ----------------------------------------------------------------------------------------- Sign up to Honcho Platform -------------------------- Get started with managed Honcho instances Join our Discord ---------------- Connect with 1000+ developers building with Honcho Contribute to Honcho -------------------- View our guidelines and explore the codebase Explore Examples ---------------- See Honcho in action with real examples We’re excited to see what you’ll build with Honcho Platform. Let’s create smarter, more personalized AI experiences together! * * * _Ready to build personally aligned AI? [Get started with Honcho →](https://app.honcho.dev/) _ [Terminology](https://docs.honcho.dev/v2/documentation/core-concepts/glossary) [SDK Reference](https://docs.honcho.dev/v2/documentation/reference/sdk) ⌘I --- # Query Documents - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/documents/query-documents#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation documents Query Documents [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const documents = await client.apps.users.collections.documents.query( 'app_id', 'user_id', 'collection_id', { query: 'x' }, ); console.log(documents); } main(); 200 422 [\ {\ "id": "",\ "content": "",\ "created_at": "2023-11-07T05:31:56Z",\ "collection_id": "",\ "app_id": "",\ "user_id": "",\ "metadata": {}\ }\ ] POST http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / collections / {collection\_id} / documents / query Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const documents = await client.apps.users.collections.documents.query( 'app_id', 'user_id', 'collection_id', { query: 'x' }, ); console.log(documents); } main(); 200 422 [\ {\ "id": "",\ "content": "",\ "created_at": "2023-11-07T05:31:56Z",\ "collection_id": "",\ "app_id": "",\ "user_id": "",\ "metadata": {}\ }\ ] #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/query-documents#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/query-documents#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/query-documents#parameter-user-id) user\_id string required ID of the user [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/query-documents#parameter-collection-id) collection\_id string required ID of the collection #### Body application/json Query parameters for document search [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/query-documents#body-query) query string required Required string length: `1 - 1000` [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/query-documents#body-filter-one-of-0) filter Filter · object [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/query-documents#body-top-k) top\_k integer default:5 Required range: `1 <= x <= 50` #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/query-documents#response-items-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/query-documents#response-items-content) content string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/query-documents#response-items-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/query-documents#response-items-collection-id) collection\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/query-documents#response-items-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/query-documents#response-items-user-id) user\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/query-documents#response-items-metadata) metadata Metadata · object [Delete Document](https://docs.honcho.dev/v1/api-reference/endpoint/documents/delete-document) ⌘I --- # Update Message - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/messages/update-message#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation messages Update Message [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const message = await client.apps.users.sessions.messages.update( 'app_id', 'user_id', 'session_id', 'message_id', { metadata: { foo: 'bar' } }, ); console.log(message.id); } main(); 200 422 { "id": "", "content": "", "is_user": true, "session_id": "", "created_at": "2023-11-07T05:31:56Z", "app_id": "", "user_id": "", "metadata": {} } PUT http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / sessions / {session\_id} / messages / {message\_id} Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const message = await client.apps.users.sessions.messages.update( 'app_id', 'user_id', 'session_id', 'message_id', { metadata: { foo: 'bar' } }, ); console.log(message.id); } main(); 200 422 { "id": "", "content": "", "is_user": true, "session_id": "", "created_at": "2023-11-07T05:31:56Z", "app_id": "", "user_id": "", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/update-message#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/update-message#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/update-message#parameter-user-id) user\_id string required ID of the user [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/update-message#parameter-session-id) session\_id string required ID of the session [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/update-message#parameter-message-id) message\_id string required ID of the message to update #### Body application/json Updated message parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/update-message#body-metadata) metadata Metadata · object required #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/update-message#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/update-message#response-content) content string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/update-message#response-is-user) is\_user boolean required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/update-message#response-session-id) session\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/update-message#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/update-message#response-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/update-message#response-user-id) user\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/update-message#response-metadata) metadata Metadata · object [Get Message](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-message) [Create Key](https://docs.honcho.dev/v1/api-reference/endpoint/keys/create-key) ⌘I --- # Update Document - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/documents/update-document#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation documents Update Document [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const document = await client.apps.users.collections.documents.update( 'app_id', 'user_id', 'collection_id', 'document_id', ); console.log(document.id); } main(); 200 422 { "id": "", "content": "", "created_at": "2023-11-07T05:31:56Z", "collection_id": "", "app_id": "", "user_id": "", "metadata": {} } PUT http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / collections / {collection\_id} / documents / {document\_id} Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const document = await client.apps.users.collections.documents.update( 'app_id', 'user_id', 'collection_id', 'document_id', ); console.log(document.id); } main(); 200 422 { "id": "", "content": "", "created_at": "2023-11-07T05:31:56Z", "collection_id": "", "app_id": "", "user_id": "", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/update-document#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/update-document#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/update-document#parameter-user-id) user\_id string required ID of the user [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/update-document#parameter-collection-id) collection\_id string required ID of the collection [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/update-document#parameter-document-id) document\_id string required ID of the document to update #### Body application/json Updated document parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/update-document#body-metadata-one-of-0) metadata Metadata · object [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/update-document#body-content-one-of-0) content string | null Required string length: `1 - 100000` #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/update-document#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/update-document#response-content) content string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/update-document#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/update-document#response-collection-id) collection\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/update-document#response-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/update-document#response-user-id) user\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/documents/update-document#response-metadata) metadata Metadata · object [Get Document](https://docs.honcho.dev/v1/api-reference/endpoint/documents/get-document) [Delete Document](https://docs.honcho.dev/v1/api-reference/endpoint/documents/delete-document) ⌘I --- # Delete Session - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/delete-session#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation sessions Delete Session [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const session = await client.apps.users.sessions.delete('app_id', 'user_id', 'session_id'); console.log(session); } main(); 422 { "detail": [\ {\ "loc": [\ ""\ ],\ "msg": "",\ "type": ""\ }\ ] } DELETE http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / sessions / {session\_id} Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const session = await client.apps.users.sessions.delete('app_id', 'user_id', 'session_id'); console.log(session); } main(); 422 { "detail": [\ {\ "loc": [\ ""\ ],\ "msg": "",\ "type": ""\ }\ ] } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/delete-session#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/delete-session#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/delete-session#parameter-user-id) user\_id string required ID of the user [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/delete-session#parameter-session-id) session\_id string required ID of the session to delete #### Response 200 application/json Successful Response [Update Session](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/update-session) [Chat](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/chat) ⌘I --- # Clone Session - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/clone-session#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation sessions Clone Session [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const session = await client.apps.users.sessions.clone('app_id', 'user_id', 'session_id'); console.log(session.id); } main(); 200 422 { "id": "", "is_active": true, "user_id": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } GET http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / sessions / {session\_id} / clone Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const session = await client.apps.users.sessions.clone('app_id', 'user_id', 'session_id'); console.log(session.id); } main(); 200 422 { "id": "", "is_active": true, "user_id": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/clone-session#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/clone-session#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/clone-session#parameter-user-id) user\_id string required ID of the user [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/clone-session#parameter-session-id) session\_id string required ID of the session to clone #### Query Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/clone-session#parameter-one-of-0) message\_id string | null Message ID to cut off the clone at [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/clone-session#parameter-deep-copy) deep\_copy boolean default:false Whether to deep copy metamessages #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/clone-session#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/clone-session#response-is-active) is\_active boolean required [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/clone-session#response-user-id) user\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/clone-session#response-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/clone-session#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/clone-session#response-metadata) metadata Metadata · object [Chat](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/chat) [Get Users](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-users) ⌘I --- # Create Session - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/create-session#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation sessions Create Session [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const session = await client.apps.users.sessions.create('app_id', 'user_id'); console.log(session.id); } main(); 200 422 { "id": "", "is_active": true, "user_id": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } POST http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / sessions Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const session = await client.apps.users.sessions.create('app_id', 'user_id'); console.log(session.id); } main(); 200 422 { "id": "", "is_active": true, "user_id": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/create-session#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/create-session#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/create-session#parameter-user-id) user\_id string required ID of the user #### Body application/json Session creation parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/create-session#body-metadata) metadata Metadata · object #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/create-session#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/create-session#response-is-active) is\_active boolean required [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/create-session#response-user-id) user\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/create-session#response-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/create-session#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/create-session#response-metadata) metadata Metadata · object [Get Sessions](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-sessions) [Get Session](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-session) ⌘I --- # Dreaming - Honcho [Skip to main content](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Advanced Dreaming [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [What Dreaming Does](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#what-dreaming-does) * [1\. Deduction](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#1-deduction) * [2\. Induction](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#2-induction) * [When Dreams Are Scheduled](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#when-dreams-are-scheduled) * [Conditions](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#conditions) * [Idle timeout](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#idle-timeout) * [Manual scheduling](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#manual-scheduling) * [Scope](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#scope) * [Deduplication and Safety](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#deduplication-and-safety) * [Configuration](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#configuration) Dreaming is an experimental feature under active development. The scheduling heuristics, specialist behavior, and configuration options described here are subject to change as we iterate on the approach. Honcho’s reasoning system extracts conclusions from every message as it arrives. Over time, this produces a large body of knowledge—some of which is redundant, outdated, or missing higher-order patterns that only become visible across many interactions. **Dreaming** is the process that addresses this: an autonomous, periodic consolidation cycle that refines the peer representation by reasoning over existing conclusions. Think of it like sleep for a memory system. The “waking” reasoning process captures what happened. The dreaming process reflects on what it all means. [​](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#what-dreaming-does) What Dreaming Does ----------------------------------------------------------------------------------------------------------------- A dream cycle runs two specialized agents in sequence: ### [​](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#1-deduction) 1\. Deduction The deduction specialist performs logical inference over existing conclusions. It autonomously explores the observation space and looks for: * **Knowledge updates**: When the same fact has changed over time (e.g., “works at Company A” followed later by “works at Company B”), it deletes the outdated conclusion and creates a new one reflecting the current state. * **Logical implications**: Conclusions that follow necessarily from existing premises but weren’t captured during real-time processing. * **Contradictions**: Conflicting conclusions that need resolution. * **Peer card updates**: Key biographical facts (name, location, occupation) that should be recorded on the peer card for quick access. ### [​](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#2-induction) 2\. Induction The induction specialist identifies patterns across multiple conclusions. It looks for: * **Behavioral tendencies**: Recurring behaviors observed across different contexts (e.g., “tends to reschedule meetings when stressed”). * **Preferences**: Consistent choices that indicate underlying preferences. * **Personality traits**: Stable characteristics inferred from multiple data points. * **Correlations**: Relationships between different aspects of behavior. Inductive conclusions require evidence from at least two source conclusions—patterns need more than a single data point. Each pattern is assigned a confidence level based on the number of supporting observations. [​](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#when-dreams-are-scheduled) When Dreams Are Scheduled ------------------------------------------------------------------------------------------------------------------------------- Dreams are triggered automatically based on a set of heuristics designed to balance freshness with efficiency: ### [​](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#conditions) Conditions All of the following must be true for a dream to be scheduled: 1. **Document threshold**: At least 50 new conclusions have been created since the last dream for that peer representation. 2. **Minimum cooldown**: At least 8 hours have passed since the last dream for that peer representation. 3. **Dreaming is enabled**: The workspace and/or session configuration has `dream.enabled` set to `true` (the default). ### [​](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#idle-timeout) Idle timeout When the threshold conditions are met, a dream is **not** immediately executed. Instead, a timer is set (default: 60 minutes) that waits for user inactivity. If new messages arrive during the waiting period, the pending dream is cancelled and the timer resets. This prevents dreaming while the user is actively interacting, ensuring the system consolidates only after the conversation has settled. Once the idle timeout expires without interruption, the dream task is enqueued for processing. ### [​](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#manual-scheduling) Manual scheduling You can also trigger a dream explicitly via the API: Python TypeScript honcho.workspaces.schedule_dream( observer="user-peer-name", observed="user-peer-name", ) Manual dreams bypass the threshold and cooldown checks, but are still subject to deduplication—if a dream is already pending or in progress for the same peer representation, the request is a no-op. [​](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#scope) Scope --------------------------------------------------------------------------------------- Dreams operate at the **peer representation** level—specifically, a (workspace, observer, observed) tuple. This means: * A dream consolidates conclusions for a specific observer’s view of a specific observed peer. * In the common case of self-observation (where the observer and observed are the same peer), the dream consolidates that peer’s own representation. * Dreams do not span across workspaces or across different peer pairs. [​](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#deduplication-and-safety) Deduplication and Safety ----------------------------------------------------------------------------------------------------------------------------- The system includes several safeguards to prevent wasted work: * **No concurrent dreams**: If a dream is already being processed for a given peer representation, a new one will not be enqueued. * **No duplicate pending dreams**: If a dream is already queued and waiting, a second enqueue request is skipped. * **Cancellation on new activity**: When new messages arrive for a peer, any pending (not yet started) dream for that peer is cancelled. This ensures the dream always runs on the most up-to-date set of conclusions. [​](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming#configuration) Configuration ------------------------------------------------------------------------------------------------------- Dreams can be enabled or disabled at the workspace or session level: Python TypeScript # Disable dreams for a workspace honcho.set_configuration({ "dream": {"enabled": False} }) # Disable dreams for a specific session session = honcho.session("my-session", config={ "dream": {"enabled": False} }) Dreaming is automatically disabled if reasoning itself is disabled, since there would be no conclusions to consolidate. Reasoning --------- Learn how Honcho reasons over messages to produce conclusions Configuration ------------- Full configuration reference for reasoning, summaries, and dreams Queue Status ------------ Monitor dream tasks alongside other background processing Schedule Dream API ------------------ API reference for manually triggering dreams [Representation Scopes](https://docs.honcho.dev/v3/documentation/features/advanced/representation-scopes) [Queue Status](https://docs.honcho.dev/v3/documentation/features/advanced/queue-status) ⌘I --- # Get Messages - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-messages#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation messages Get Messages [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { // Automatically fetches more pages as needed. for await (const message of client.apps.users.sessions.messages.list('app_id', 'user_id', 'session_id')) { console.log(message.id); } } main(); 200 422 { "items": [\ {\ "id": "",\ "content": "",\ "is_user": true,\ "session_id": "",\ "created_at": "2023-11-07T05:31:56Z",\ "app_id": "",\ "user_id": "",\ "metadata": {}\ }\ ], "total": 1, "page": 2, "size": 2, "pages": 1 } POST http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / sessions / {session\_id} / messages / list Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { // Automatically fetches more pages as needed. for await (const message of client.apps.users.sessions.messages.list('app_id', 'user_id', 'session_id')) { console.log(message.id); } } main(); 200 422 { "items": [\ {\ "id": "",\ "content": "",\ "is_user": true,\ "session_id": "",\ "created_at": "2023-11-07T05:31:56Z",\ "app_id": "",\ "user_id": "",\ "metadata": {}\ }\ ], "total": 1, "page": 2, "size": 2, "pages": 1 } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-messages#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-messages#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-messages#parameter-user-id) user\_id string required ID of the user [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-messages#parameter-session-id) session\_id string required ID of the session #### Query Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-messages#parameter-one-of-0) reverse boolean | null default:false Whether to reverse the order of results [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-messages#parameter-page) page integer default:1 Page number Required range: `x >= 1` [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-messages#parameter-size) size integer default:50 Page size Required range: `1 <= x <= 100` #### Body application/json Filtering options for the messages list [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-messages#body-one-of-0-filter-one-of-0) filter Filter · object #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-messages#response-items) items Message · object\[\] required Show child attributes [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-messages#response-total) total integer required Required range: `x >= 0` [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-messages#response-page) page integer required Required range: `x >= 1` [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-messages#response-size) size integer required Required range: `x >= 1` [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-messages#response-pages) pages integer Required range: `x >= 0` [Update User](https://docs.honcho.dev/v1/api-reference/endpoint/users/update-user) [Create Message For Session](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-message-for-session) ⌘I --- # Get Message - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-message#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation messages Get Message [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const message = await client.apps.users.sessions.messages.get( 'app_id', 'user_id', 'session_id', 'message_id', ); console.log(message.id); } main(); 200 422 { "id": "", "content": "", "is_user": true, "session_id": "", "created_at": "2023-11-07T05:31:56Z", "app_id": "", "user_id": "", "metadata": {} } GET http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / sessions / {session\_id} / messages / {message\_id} Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const message = await client.apps.users.sessions.messages.get( 'app_id', 'user_id', 'session_id', 'message_id', ); console.log(message.id); } main(); 200 422 { "id": "", "content": "", "is_user": true, "session_id": "", "created_at": "2023-11-07T05:31:56Z", "app_id": "", "user_id": "", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-message#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-message#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-message#parameter-user-id) user\_id string required ID of the user [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-message#parameter-session-id) session\_id string required ID of the session [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-message#parameter-message-id) message\_id string required ID of the message to retrieve #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-message#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-message#response-content) content string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-message#response-is-user) is\_user boolean required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-message#response-session-id) session\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-message#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-message#response-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-message#response-user-id) user\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-message#response-metadata) metadata Metadata · object [Create Batch Messages For Session](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-batch-messages-for-session) [Update Message](https://docs.honcho.dev/v1/api-reference/endpoint/messages/update-message) ⌘I --- # Design Patterns - Honcho [Skip to main content](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Core Concepts Design Patterns [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Quick Reference](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#quick-reference) * [Workspace Design](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#workspace-design) * [Peer Design](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#peer-design) * [Session Design](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#session-design) * [Application Patterns](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#application-patterns) * [AI Companions](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#ai-companions) * [Coding Agents](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#coding-agents) * [Games](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#games) * [Common Mistakes](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#common-mistakes) * [Next Steps](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#next-steps) If you’re using a coding agent (Claude Code, Cursor, etc.), the **`/honcho-integration` skill** walks you through these decisions interactively. It explores your codebase, interviews you about peers and sessions, and generates the integration code. The patterns below are the same ones the skill uses. [​](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#quick-reference) Quick Reference -------------------------------------------------------------------------------------------------------------- | Decision | Recommendation | | --- | --- | | How many workspaces? | One per application. Separate per-agent if you need hard data isolation. | | Who should be a peer? | Any entity you want Honcho to reason about — users, agents, NPCs, students, customers. | | How should I scope sessions? | Flexible — per-conversation, per-channel, per-scene, etc. See [Session Design](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#session-design)
below. | | Should I set `observe_me: false`? | Yes, for any peer you don’t need Honcho to build a representation of — typically assistants or bots with deterministic behavior. | | Do I need `observe_others`? | Only when different peers need distinct views of the same participant (e.g., games, multi-agent). Most apps can leave it at the default (false). | [​](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#workspace-design) Workspace Design ---------------------------------------------------------------------------------------------------------------- Workspaces are the top-level container. Everything inside a workspace (peers, sessions, messages, and all reasoning) is fully isolated from other workspaces. **One workspace per application** is the most common pattern. Use separate workspaces when you need hard isolation: | Pattern | When to use | | --- | --- | | Single workspace | Most applications. One product, one environment. | | Per-tenant | Multi-tenant SaaS where each customer’s data must be completely isolated. | If you are using the SDK, it will create a workspace called `default` if no name is specified for `workspace_id` * * * [​](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#peer-design) Peer Design ------------------------------------------------------------------------------------------------------ A peer is any entity that participates in a session. Observation settings control which ones Honcho reasons about. **What makes a good peer?** * It participates in sessions (a user, an agent, a character, an NPC) * It persists across sessions * It changes over time (preferences shift, knowledge grows), or it produces messages you want Honcho to see **Naming conventions** Give peers stable, unique identifiers scoped to your application: Python TypeScript # Prefix with the source platform for multi-channel apps peer = honcho.peer("discord_491827364") peer = honcho.peer("slack_U04ABCDEF") # Use your own user IDs for backend integrations peer = honcho.peer("user_abc123") # Use descriptive names for agents/assistants peer = honcho.peer("assistant") peer = honcho.peer("dungeon-master") If your Peer represents an entity that may go by multiple different names, such as nicknames indicate that in the Peer Card: Python TypeScript peer = honcho.peer("user_abc123") peer.set_card([\ "Name: Alice. Also known as 'Ali' and 'A'.",\ "College student, prefers casual tone.",\ ]) **When to disable reasoning** Not every peer needs a representation. Set `observe_me: false` on peers that behave deterministically. Python TypeScript from honcho.api_types import PeerConfig # The assistant doesn't need a representation assistant = honcho.peer("assistant", configuration=PeerConfig(observe_me=False)) # The user does--this is who you want to understand user = honcho.peer("user-123", configuration=PeerConfig(observe_me=True)) * * * [​](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#session-design) Session Design ------------------------------------------------------------------------------------------------------------ Sessions define the temporal boundaries of an interaction. How you scope sessions directly affects how summaries are generated and how context is retrieved. **Common session patterns** | Pattern | Session scoped to | Example | | --- | --- | --- | | Per-conversation | Each new chat thread | ChatGPT-style UI where each thread is a session | | Per-channel | A persistent channel or room | Discord channel, Slack thread | | Per-interaction | A bounded task or encounter | A support ticket, a game encounter | | Per-import | A batch of external data | Importing emails or documents for a single peer | **When to create new sessions vs reuse** * **New session** when the context resets (new conversation, new day, new topic) * **Reuse session** when context should accumulate (ongoing channel, persistent thread) * * * [​](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#application-patterns) Application Patterns ------------------------------------------------------------------------------------------------------------------------ ### [​](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#ai-companions) AI Companions An assistant that remembers the user across sessions and platforms. The [Honcho plugin for OpenClaw](https://docs.honcho.dev/v3/guides/integrations/openclaw) is a production example—one assistant with memory across WhatsApp, Telegram, Discord, and Slack. Python TypeScript from honcho import Honcho from honcho.api_types import PeerConfig, SessionPeerConfig honcho = Honcho(workspace_id="my-companion-app") owner = honcho.peer("owner") agent = honcho.peer("agent-main", configuration=PeerConfig(observe_me=False)) # Session key = thread + platform → separate histories, shared user memory session = honcho.session("general-discord") session.add_peers([\ (owner, SessionPeerConfig(observe_me=True, observe_others=False)),\ (agent, SessionPeerConfig(observe_me=True, observe_others=True)),\ ]) session.add_messages([\ owner.message("I've been stressed about the move to Portland next month"),\ agent.message("Moving is a big deal. What's weighing on you the most?"),\ owner.message("Honestly just leaving my friend group behind"),\ ]) # Query from any session or platform response = owner.chat("What's going on in this user's life right now?") **Key decisions (from the [OpenClaw plugin](https://docs.honcho.dev/v3/guides/integrations/openclaw) ):** * **Session key = thread + platform** — `general-discord` and `general-telegram` are separate sessions but share a single owner representation, so Honcho learns from every channel * **Dynamic agent peers** — each agent gets its own peer (`agent-{id}`), resolved via a workspace-level map. Renaming an agent recovers the peer by metadata lookup * **Subagent hierarchy** — when a primary agent spawns a subagent, the parent joins the child’s session as a silent observer (`observe_me: false, observe_others: true`), giving Honcho visibility into the full agent tree * **Asymmetric observation** — both owner and agent are observed, but with different scopes: owner has `observe_others: false` (default view), while the agent has `observe_others: true` so it can build its own representation of the owner. Subagents get lighter context (peer card only, no session summary) See the [OpenClaw integration guide](https://docs.honcho.dev/v3/guides/integrations/openclaw) for the full plugin setup. * * * ### [​](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#coding-agents) Coding Agents Coding agents survive terminal restarts, editor switches, and project hops. The [Honcho plugin for Claude Code](https://docs.honcho.dev/v3/guides/integrations/claude-code) is a production example of this pattern. Python TypeScript from honcho import Honcho from honcho.api_types import PeerConfig honcho = Honcho(workspace_id="claude_code") # Developer is observed; agent is not developer = honcho.peer("user") agent = honcho.peer("claude", configuration=PeerConfig(observe_me=False)) # Session per project directory -- stable across restarts session = honcho.session("user-honcho-repo") session.add_peers([developer, agent]) session.add_messages([\ developer.message("refactor the auth module to use dependency injection"),\ agent.message("I'll extract the auth dependencies into a provider pattern..."),\ developer.message("actually let's keep it simpler, just pass the config directly"),\ ]) # In a future session, query what Honcho learned context = developer.chat("What are this developer's preferences for code architecture?") # Honcho knows: prefers simplicity, reverses decisions when simpler approach exists **Key decisions (from the Claude Code plugin):** * **One workspace per tool** — Claude Code and Cursor each get their own workspace, with optional cross-linking for read access * **Asymmetric peers** — developer is observed (memory formation), agent is not observed but still stores messages so Honcho sees both sides * **Session-per-directory** by default — each project accumulates its own memory. Prefix with peer name (`user-honcho-repo`) so multiple developers on the same workspace don’t collide. Alternative strategies: `git-branch` (session switches on branch change) or `chat-instance` (clean slate each time) * **Filter what you store** — user messages go in real-time; agent messages are filtered to skip trivial tool output and keep substantive explanations * **Import external data** with single-peer sessions to ingest READMEs, architecture docs, or commit history into a developer’s representation See the [Claude Code integration guide](https://docs.honcho.dev/v3/guides/integrations/claude-code) for the full plugin setup. * * * ### [​](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#games) Games Games introduce multi-peer scenarios where **information asymmetry matters**. An NPC should only know what it has witnessed, not the full game state. Python TypeScript from honcho import Honcho from honcho.api_types import SessionPeerConfig honcho = Honcho(workspace_id="my-rpg") # Every character is a peer player = honcho.peer("player-one") merchant = honcho.peer("merchant-grim") thief = honcho.peer("thief-shadow") # Scene 1: Player talks to the merchant tavern = honcho.session("tavern-scene") tavern.add_peers([player, merchant]) # Enable the merchant to build its own representation of the player tavern.set_peer_configuration(merchant, SessionPeerConfig(observe_others=True)) tavern.add_messages([\ player.message("I'm looking for a rare gemstone. Money is no object."),\ merchant.message("I may know of one... but it won't come cheap."),\ ]) # Scene 2: Player talks to the thief (merchant isn't here) alley = honcho.session("dark-alley") alley.add_peers([player, thief]) alley.set_peer_configuration(thief, SessionPeerConfig(observe_others=True)) alley.add_messages([\ player.message("I need that gemstone stolen from the merchant. Quietly."),\ thief.message("Consider it done. Half up front."),\ ]) # The merchant's view of the player: wealthy buyer seeking a gemstone merchant_view = merchant.chat("What do I know about this player?", target="player-one") # The thief's view: someone willing to steal from the merchant thief_view = thief.chat("What do I know about this player?", target="player-one") # Honcho's global view: knows both sides of the story full_view = player.chat("What is this player up to?") **Key decisions:** * Every character (player, NPC) is a peer * `observe_others: true` lets NPCs build their own representations of the player based only on what they’ve witnessed * Session-per-scene or session-per-encounter so context scopes to specific interactions * Use `target` when querying to get a specific NPC’s perspective rather than Honcho’s omniscient view * See [Representation Scopes](https://docs.honcho.dev/v3/documentation/features/advanced/representation-scopes) for the full details * * * [​](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#common-mistakes) Common Mistakes -------------------------------------------------------------------------------------------------------------- * **Leaving `observe_me` on for assistants** — Wastes reasoning compute on a peer you control. Deterministic behavior doesn’t need to be modeled. * **Not storing messages** — Honcho reasons about messages asynchronously. If you don’t call `add_messages()`, there’s nothing to reason about — no messages means no memory. See [Storing Data](https://docs.honcho.dev/v3/documentation/features/storing-data) for details. * **Creating a new workspace per user** — Use peers within a single workspace instead. Workspaces are for isolation between applications, not between users. * **Too many tiny sessions** — Summaries and `session.context()` are scoped to a single session. If you split a continuous conversation across many sessions, context is fragmented and each session is too short to summarize. Reuse a session when context should flow continuously. * **Blocking on processing** — Messages are processed asynchronously in the background. Don’t poll or wait for reasoning to complete before continuing your application flow. [​](https://docs.honcho.dev/v3/documentation/core-concepts/design-patterns#next-steps) Next Steps ---------------------------------------------------------------------------------------------------- Get Context ----------- Retrieve formatted context from sessions for your LLM Chat Endpoint ------------- Query Honcho about your peers with natural language Reasoning Configuration ----------------------- Fine-tune what gets reasoned about and how Representation Scopes --------------------- Directional representations for multi-peer scenarios [Representations](https://docs.honcho.dev/v3/documentation/core-concepts/representation) [Storing Data](https://docs.honcho.dev/v3/documentation/features/storing-data) ⌘I --- # Chat - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/chat#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation sessions Chat [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const dialecticResponse = await client.apps.users.sessions.chat('app_id', 'user_id', 'session_id', { queries: 'string', }); console.log(dialecticResponse.content); } main(); 200 422 { "content": "" } POST http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / sessions / {session\_id} / chat Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const dialecticResponse = await client.apps.users.sessions.chat('app_id', 'user_id', 'session_id', { queries: 'string', }); console.log(dialecticResponse.content); } main(); 200 422 { "content": "" } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/chat#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/chat#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/chat#parameter-user-id) user\_id string required ID of the user [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/chat#parameter-session-id) session\_id string required ID of the session #### Body application/json Dialectic Endpoint Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/chat#body-queries-one-of-0) queries stringstring\[\]stringstring\[\] required [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/chat#body-stream) stream boolean default:false #### Response 200 application/json Response to a question informed by Honcho's User Representation [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/chat#response-content) content string required [Delete Session](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/delete-session) [Clone Session](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/clone-session) ⌘I --- # Get Metamessages - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessages#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation metamessages Get Metamessages [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { // Automatically fetches more pages as needed. for await (const metamessage of client.apps.users.metamessages.list('app_id', 'user_id')) { console.log(metamessage.id); } } main(); 200 422 { "items": [\ {\ "id": "",\ "label": "",\ "content": "",\ "user_id": "",\ "app_id": "",\ "session_id": "",\ "message_id": "",\ "created_at": "2023-11-07T05:31:56Z",\ "metamessage_type": "",\ "metadata": {}\ }\ ], "total": 1, "page": 2, "size": 2, "pages": 1 } POST http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / metamessages / list Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { // Automatically fetches more pages as needed. for await (const metamessage of client.apps.users.metamessages.list('app_id', 'user_id')) { console.log(metamessage.id); } } main(); 200 422 { "items": [\ {\ "id": "",\ "label": "",\ "content": "",\ "user_id": "",\ "app_id": "",\ "session_id": "",\ "message_id": "",\ "created_at": "2023-11-07T05:31:56Z",\ "metamessage_type": "",\ "metadata": {}\ }\ ], "total": 1, "page": 2, "size": 2, "pages": 1 } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessages#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessages#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessages#parameter-user-id) user\_id string required ID of the user #### Query Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessages#parameter-one-of-0) reverse boolean | null default:false Whether to reverse the order of results [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessages#parameter-page) page integer default:1 Page number Required range: `x >= 1` [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessages#parameter-size) size integer default:50 Page size Required range: `1 <= x <= 100` #### Body application/json Filtering options for the metamessages list [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessages#body-one-of-0-metamessage-type-one-of-0) metamessage\_type string | null [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessages#body-one-of-0-session-id-one-of-0) session\_id string | null [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessages#body-one-of-0-message-id-one-of-0) message\_id string | null [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessages#body-one-of-0-filter-one-of-0) filter Filter · object #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessages#response-items) items Metamessage · object\[\] required Show child attributes [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessages#response-total) total integer required Required range: `x >= 0` [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessages#response-page) page integer required Required range: `x >= 1` [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessages#response-size) size integer required Required range: `x >= 1` [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessages#response-pages) pages integer Required range: `x >= 0` [Create Metamessage](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage) [Get Metamessage](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessage) ⌘I --- # Configure Reasoning - Honcho [Skip to main content](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Core Concepts Configure Reasoning [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [Configuration Hierarchy](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#configuration-hierarchy) * [Configuration Options](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#configuration-options) * [Deriver Configuration](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#deriver-configuration) * [Peer Card Configuration](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#peer-card-configuration) * [Summary Configuration](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#summary-configuration) * [Dream Configuration](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#dream-configuration) * [Peer Configuration](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#peer-configuration) * [Session Configuration](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#session-configuration) * [Message Configuration](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#message-configuration) * [Session-Peer Configuration](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#session-peer-configuration) * [Observation and Peer Join Order](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#observation-and-peer-join-order) * [Full Configuration Schema Reference](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#full-configuration-schema-reference) * [Workspace & Session Configuration](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#workspace-%26-session-configuration) * [Message Configuration](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#message-configuration-2) Honcho’s reasoning engine (the “deriver”) can be configured at multiple levels to control how it processes messages, generates facts, creates summaries, and builds peer representations. Configuration follows a hierarchy: **message > session > workspace > global defaults**. Settings at lower levels override those at higher levels, giving you fine-grained control over behavior. [​](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#configuration-hierarchy) Configuration Hierarchy ---------------------------------------------------------------------------------------------------------------------------- Honcho uses a hierarchical configuration system where more specific settings override more general ones: 1. **Global Defaults**: Built-in system defaults 2. **Workspace Configuration**: Settings that apply to all sessions in a workspace 3. **Session Configuration**: Settings that apply to all messages in a session 4. **Message Configuration**: Settings that apply to a specific message All configuration fields are optional. If not specified, the value is inherited from the next level up in the hierarchy. [​](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#configuration-options) Configuration Options ------------------------------------------------------------------------------------------------------------------------ ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#deriver-configuration) Deriver Configuration Controls the core reasoning engine that extracts facts and insights from messages. | Field | Type | Description | | --- | --- | --- | | `enabled` | `bool` | Whether to enable deriver functionality. When disabled, no facts or representations are generated. | Python TypeScript from honcho import Honcho honcho = Honcho() # Disable deriver at session level session = honcho.session("private-session", config={ "deriver": {"enabled": False} }) ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#peer-card-configuration) Peer Card Configuration Controls how peer cards (concise summaries of what’s known about a peer) are generated and used. | Field | Type | Description | | --- | --- | --- | | `use` | `bool` | Whether to use peer cards during the deriver process. | | `create` | `bool` | Whether to generate peer cards based on message content. | Python TypeScript # Disable peer card generation but still use existing cards session = honcho.session("my-session", config={ "peer_card": {"create": False, "use": True} }) ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#summary-configuration) Summary Configuration Controls automatic conversation summarization. Available at workspace and session levels only. | Field | Type | Description | | --- | --- | --- | | `enabled` | `bool` | Whether to enable summary functionality. | | `messages_per_short_summary` | `int` | Number of messages between short summaries. Must be ≥ 10. | | `messages_per_long_summary` | `int` | Number of messages between long summaries. Must be ≥ 20 and greater than `messages_per_short_summary`. | Python TypeScript # Customize summary frequency session = honcho.session("verbose-session", config={ "summary": { "enabled": True, "messages_per_short_summary": 15, "messages_per_long_summary": 45 } }) ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#dream-configuration) Dream Configuration Controls the “dreaming” process that consolidates and refines representations. Available at workspace and session levels only. | Field | Type | Description | | --- | --- | --- | | `enabled` | `bool` | Whether to enable dream functionality. Automatically disabled if deriver is disabled. | Python TypeScript # Disable dreams for a workspace # (done via API when creating/updating workspace) * * * [​](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#peer-configuration) Peer Configuration ------------------------------------------------------------------------------------------------------------------ By default, all peers are “observed” by Honcho. This means that Honcho will derive facts from messages sent by the peer and generate a representation of them. In most cases, this is why you use Honcho! However, sometimes an application requires a peer that should not be observed: for example, an assistant or game NPC that your program will never need to ask questions about. You may therefore disable observation of a peer by setting the `observe_me` flag in their configuration to `false`. If the peer has a session-level configuration, it will override this configuration. If the flag is not set, or is set to `true`, the peer will be observed. Python TypeScript from honcho import Honcho # Initialize client honcho = Honcho() # Create peer with configuration peer = honcho.peer("my-peer", config={"observe_me": False}) # Change peer's configuration peer.set_config({"observe_me": True}) # Note: creating the same peer again will also replace the configuration peer = honcho.peer("my-peer", config={"observe_me": False}) [​](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#session-configuration) Session Configuration ------------------------------------------------------------------------------------------------------------------------ Sessions support the full configuration schema. You can disable the deriver entirely for a session, customize summary behavior, or adjust peer card settings. Python TypeScript from honcho import Honcho # Initialize client honcho = Honcho() # Create session with deriver disabled session = honcho.session("my-session", config={ "deriver": {"enabled": False} }) # Create session with custom summary settings session = honcho.session("detailed-session", config={ "summary": { "messages_per_short_summary": 10, "messages_per_long_summary": 30 } }) [​](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#message-configuration) Message Configuration ------------------------------------------------------------------------------------------------------------------------ Individual messages can override session and workspace configuration for fine-grained control. This is useful for excluding specific messages from processing or adjusting behavior on a per-message basis. Python TypeScript from honcho import Honcho honcho = Honcho() session = honcho.session("my-session") user = honcho.peer("user") # Create a message that skips deriver processing session.add_messages([\ user.message("This message won't be analyzed", config={\ "deriver": {"enabled": False}\ })\ ]) # Create a message with custom peer card settings session.add_messages([\ user.message("Use existing card but don't update it", config={\ "peer_card": {"use": True, "create": False}\ })\ ]) [​](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#session-peer-configuration) Session-Peer Configuration ---------------------------------------------------------------------------------------------------------------------------------- Configuration at the session-peer level controls how peers observe each other within a specific session. This is the most common use case for enabling “local representations” — where one peer forms a model of another peer based only on what they observe in that session. There are two flags that can be set at the session-peer level: * `observe_me`: Whether this peer should _be observed_ by others in the session. By default, this is `true`. This overrides the peer-level `observe_me` flag. * `observe_others`: Whether this peer should produce local representations of others in the session. By default, this is `false`. Other peers will only be observed if their `observe_me` flag is `true`. You can combine these flags across multiple peers to arrange any possible permutation of directional observation. Note that in the default case, no local representations are produced. To produce local representations, you must set the `observe_others` flag to `true` for at least one peer in the session and at least one other peer must have their `observe_me` flag set to `true`. Many applications will work best without local representations, preferring to chat with Honcho’s top-down representation of each peer. Only enable local representations via the `observe_others` flag if you are doing advanced reasoning on user perspectives. ![Peer Representations](https://mintcdn.com/plasticlabs/lVyHfvNDd8wveJyM/images/local-vs-global-reps.png?w=2500&fit=max&auto=format&n=lVyHfvNDd8wveJyM&q=85&s=99eae99847a6919fd8b4db0594b7a144) You can dynamically change the configuration of a session-peer by calling `set_peer_config` on the session with the peer and the configuration you want to set. Python TypeScript from honcho import Honcho, SessionPeerConfig # Initialize client honcho = Honcho() # Create session session = honcho.session("my-session") # Create peers alice = honcho.peer("alice") bob = honcho.peer("bob") # Add peers to session with default configuration session.add_peers([alice, bob]) # Add another peer to the session with a custom configuration charlie = honcho.peer("charlie") session.add_peers([(charlie, SessionPeerConfig(observe_me=False, observe_others=True))]) # Set session-peer configuration session.set_peer_config(alice, SessionPeerConfig(observe_others=True)) session.set_peer_config(bob, SessionPeerConfig(observe_me=False)) # Get session-peer configuration charlie_config = session.get_peer_config(charlie) print(charlie_config) ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#observation-and-peer-join-order) Observation and Peer Join Order Reasoning tasks are scheduled at the time a message is created, based on which peers are in the session **at that moment**. Honcho does not retroactively schedule reasoning for peers that join later. This means: * If Peer C joins a session **after** messages from Peer A and Peer B have already been sent, Peer C will **not** receive reasoning tasks for those earlier messages—even if Peer C has `observe_others` enabled. * Peer C will only begin observing new messages sent after they join the session. * Similarly, if a peer leaves a session, they stop being included as an observer for any messages sent after their departure. There is no retroactive reasoning. If your application needs an observer peer to reason about prior conversation history, add the peer to the session **before** messages are sent. Alternatively use the .chat() endpoint to include the conversation history in the agent’s context, regardless of if they were reasoned against or not [​](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#full-configuration-schema-reference) Full Configuration Schema Reference ---------------------------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#workspace-&-session-configuration) Workspace & Session Configuration { "deriver": { "enabled": true }, "peer_card": { "use": true, "create": true }, "summary": { "enabled": true, "messages_per_short_summary": 20, "messages_per_long_summary": 60 }, "dream": { "enabled": true } } ### [​](https://docs.honcho.dev/v2/documentation/core-concepts/configuration#message-configuration-2) Message Configuration { "deriver": { "enabled": true }, "peer_card": { "use": true, "create": true } } Message configuration only supports `deriver` and `peer_card` settings. Summary and dream configurations are session/workspace-level only. [Local vs Global Representations](https://docs.honcho.dev/v2/documentation/core-concepts/features/local-vs-global) [Summarizer](https://docs.honcho.dev/v2/documentation/core-concepts/summarizer) ⌘I --- # Discord Bots with Honcho - Honcho [Skip to main content](https://docs.honcho.dev/v3/guides/discord#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Tutorials Discord Bots with Honcho [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Events](https://docs.honcho.dev/v3/guides/discord#events) * [Helper Functions](https://docs.honcho.dev/v3/guides/discord#helper-functions) * [Message Validation](https://docs.honcho.dev/v3/guides/discord#message-validation) * [Message Sanitization](https://docs.honcho.dev/v3/guides/discord#message-sanitization) * [Peer ID Generation](https://docs.honcho.dev/v3/guides/discord#peer-id-generation) * [LLM Integration](https://docs.honcho.dev/v3/guides/discord#llm-integration) * [Message Sending](https://docs.honcho.dev/v3/guides/discord#message-sending) * [Honcho Integration](https://docs.honcho.dev/v3/guides/discord#honcho-integration) * [Slash Commands](https://docs.honcho.dev/v3/guides/discord#slash-commands) * [Setup and Configuration](https://docs.honcho.dev/v3/guides/discord#setup-and-configuration) * [Recap](https://docs.honcho.dev/v3/guides/discord#recap) > Example code is available on [GitHub](https://github.com/plastic-labs/discord-python-starter) Any application interface that defines logic based on events and supports special commands can work easily with Honcho. Here’s how to use Honcho with **Discord** as an interface. If you’re not familiar with Discord bot application logic, the [py-cord](https://pycord.dev/) docs would be a good place to start. [​](https://docs.honcho.dev/v3/guides/discord#events) Events --------------------------------------------------------------- Most Discord bots have async functions that listen for specific events, the most common one being messages. We can use Honcho to store messages by user and session based on an interface’s event logic. Take the following function definition for example: @bot.event async def on_message(message): """ Receive a message from Discord and respond with a message from our LLM assistant. """ if not validate_message(message): return input = sanitize_message(message) # If the message is empty after sanitizing, ignore it if not input: return peer = honcho_client.peer(id=get_peer_id_from_discord(message)) session = honcho_client.session(id=str(message.channel.id)) async with message.channel.typing(): response = llm(session, input) await send_discord_message(message, response) # Save both the user's message and the bot's response to the session session.add_messages( [\ peer.message(input),\ assistant.message(response),\ ] ) Let’s break down what this code is doing… @bot.event async def on_message(message): if not validate_message(message): return This is how you define an event function in `py-cord` that listens for messages. We use a helper function `validate_message()` to check if the message should be processed. [​](https://docs.honcho.dev/v3/guides/discord#helper-functions) Helper Functions ----------------------------------------------------------------------------------- The code uses several helper functions to keep the main logic clean and readable. Let’s examine each one: ### [​](https://docs.honcho.dev/v3/guides/discord#message-validation) Message Validation def validate_message(message) -> bool: """ Determine if the message is valid for the bot to respond to. Return True if it is, False otherwise. Currently, the bot will only respond to messages that tag it with an @mention in a public channel and are not from the bot itself. """ if message.author == bot.user: # ensure the bot does not reply to itself return False if isinstance(message.channel, discord.DMChannel): return False if not bot.user.mentioned_in(message): return False return True This function centralizes all the logic for determining whether the bot should respond to a message. It checks that: * The message isn’t from the bot itself * The message isn’t in a DM channel * The bot is mentioned in the message ### [​](https://docs.honcho.dev/v3/guides/discord#message-sanitization) Message Sanitization def sanitize_message(message) -> str | None: """Remove the bot's mention from the message content if present""" content = message.content.replace(f"<@{bot.user.id}>", "").strip() if not content: return None return content This helper removes the bot’s mention from the message content, leaving just the actual user input. ### [​](https://docs.honcho.dev/v3/guides/discord#peer-id-generation) Peer ID Generation def get_peer_id_from_discord(message): """Get a Honcho peer ID for the message author""" return f"discord_{str(message.author.id)}" This creates a unique peer identifier for each Discord user by prefixing their Discord ID. ### [​](https://docs.honcho.dev/v3/guides/discord#llm-integration) LLM Integration def llm(session, prompt) -> str: """ Call the LLM with the given prompt and chat history. You should expand this function with custom logic, prompts, etc. """ messages: list[dict[str, object]] = session.context().to_openai( assistant=assistant ) messages.append({"role": "user", "content": prompt}) try: completion = openai.chat.completions.create( model=MODEL_NAME, messages=messages, ) return completion.choices[0].message.content except Exception as e: print(e) return f"Error: {e}" This function handles the LLM interaction. It uses Honcho’s built-in `to_openai()` method to automatically convert the session context into the format expected by OpenAI’s chat completions API. ### [​](https://docs.honcho.dev/v3/guides/discord#message-sending) Message Sending async def send_discord_message(message, response_content: str): """Send a message to the Discord channel""" if len(response_content) > 1500: # Split response into chunks at newlines, keeping under 1500 chars chunks = [] current_chunk = "" for line in response_content.splitlines(keepends=True): if len(current_chunk) + len(line) > 1500: chunks.append(current_chunk) current_chunk = line else: current_chunk += line if current_chunk: chunks.append(current_chunk) for chunk in chunks: await message.channel.send(chunk) else: await message.channel.send(response_content) This function handles sending messages to Discord, automatically splitting long responses into multiple messages to stay within Discord’s character limits. [​](https://docs.honcho.dev/v3/guides/discord#honcho-integration) Honcho Integration --------------------------------------------------------------------------------------- The new Honcho peer/session API makes integration much simpler: peer = honcho_client.peer(id=get_peer_id_from_discord(message)) session = honcho_client.session(id=str(message.channel.id)) Here we create a peer object for the user and a session object using the Discord channel ID. This automatically handles user and session management. # Save both the user's message and the bot's response to the session session.add_messages( [\ peer.message(input),\ assistant.message(response),\ ] ) After generating the response, we save both the user’s input and the bot’s response to the session using the `add_messages()` method. The `peer.message()` creates a message from the user, while `assistant.message()` creates a message from the assistant. [​](https://docs.honcho.dev/v3/guides/discord#slash-commands) Slash Commands ------------------------------------------------------------------------------- Discord bots also offer slash command functionality. Here’s an example using Honcho’s chat endpoint feature: @bot.slash_command( name="chat", description="Chat with Honcho about a peer.", ) async def chat(ctx, query: str): await ctx.defer() try: peer = honcho_client.peer(id=get_peer_id_from_discord(ctx)) session = honcho_client.session(id=str(ctx.channel.id)) response = peer.chat( query=query, session_id=session.id, ) if response: await ctx.followup.send(response) else: await ctx.followup.send( f"I don't know anything about {ctx.author.name} because we haven't talked yet!" ) except Exception as e: logger.error(f"Error calling Dialectic API: {e}") await ctx.followup.send( f"Sorry, there was an error processing your request: {str(e)}" ) This slash command uses Honcho’s chat endpoint functionality to answer questions about the user based on their conversation history. [​](https://docs.honcho.dev/v3/guides/discord#setup-and-configuration) Setup and Configuration ------------------------------------------------------------------------------------------------- The bot requires several environment variables and setup: honcho_client = Honcho() assistant = honcho_client.peer(id="assistant", config={"observe_me": False}) openai = OpenAI(base_url="https://openrouter.ai/api/v1", api_key=MODEL_API_KEY) * `honcho_client`: The main Honcho client * `assistant`: A peer representing the bot/assistant * `openai`: OpenAI client configured to use OpenRouter [​](https://docs.honcho.dev/v3/guides/discord#recap) Recap ------------------------------------------------------------- The new Honcho peer/session API makes Discord bot integration much simpler and more intuitive. Key patterns we learned: * **Peer/Session Model**: Users are represented as peers, conversations as sessions * **Automatic Context Management**: `session.context().to_openai()` automatically formats chat history * **Message Storage**: `session.add_messages()` stores both user and assistant messages * **Representation Queries**: `peer.chat()` enables querying conversation history * **Helper Functions**: Clean code organization with focused helper functions This approach provides a clean, maintainable structure for building Discord bots with conversational memory and context management. [Paperclip](https://docs.honcho.dev/v3/guides/integrations/paperclip) [Granola](https://docs.honcho.dev/v3/guides/granola) ⌘I --- # AI-Powered Honcho Setup - Honcho [Skip to main content](https://docs.honcho.dev/v2/documentation/introduction/vibecoding#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v2.5.1 Search... ⌘K Search... Navigation Introduction AI-Powered Honcho Setup [Documentation](https://docs.honcho.dev/v2/documentation/introduction/overview) [Spellbooks](https://docs.honcho.dev/v2/guides/overview) [API Reference](https://docs.honcho.dev/v2/api-reference/introduction) [Contributing](https://docs.honcho.dev/v2/contributing/guidelines) On this page * [🚀 Universal Starter Prompt](https://docs.honcho.dev/v2/documentation/introduction/vibecoding#-universal-starter-prompt) These docs are designed to be easily consumable for LLMs. Each page has a button the lets you copy the page as Markdown or paste directly into ChatGPT or Claude. Additionally, we follow the llms.txt standard. There are both an llms.txt and llms-full.txt available. * [llms.txt](https://docs.honcho.dev/llms.txt) * [llms-full.txt](https://docs.honcho.dev/llms-full.txt) Additionally, we provide a starter prompt to paste into a coding assistant to quickly get started building with Honcho. [​](https://docs.honcho.dev/v2/documentation/introduction/vibecoding#-universal-starter-prompt) 🚀 Universal Starter Prompt ------------------------------------------------------------------------------------------------------------------------------ I want to start building with Honcho - a memory and personalization platform for AI applications. ## Honcho Resources **Documentation:** - Main docs: https://docs.honcho.dev - API Reference: https://docs.honcho.dev/v2/api-reference/introduction - Quickstart: https://docs.honcho.dev/v2/documentation/introduction/quickstart - Architecture: https://docs.honcho.dev/v2/documentation/reference/architecture **Code & Examples:** - Core repo: https://github.com/plastic-labs/honcho - Python SDK: https://github.com/plastic-labs/honcho-python - TypeScript SDK: https://github.com/plastic-labs/honcho-node - Discord bot starter: https://github.com/plastic-labs/discord-python-starter - Telegram bot example: https://github.com/plastic-labs/telegram-python-starter **What Honcho Does:** Honcho provides persistent memory and personalization for AI apps. It automatically: - Stores conversation history across sessions - Learns facts about users from conversations - Builds user representations for personalized responses - Manages multi-user sessions with theory of mind - Provides context injection for any LLM **Architecture Overview:** - Core primitives: Workspaces contain Peers (users/agents) and Sessions (conversations) - Peers can observe other peers in sessions (configurable with observe_me_observe_others) - Background deriver processes messages to extract facts and update representations - Dialectic API provides personalized responses based on learned context - Supports any LLM (OpenAI, Anthropic, open source) - Can use demo server or self-host Please assess the resources above and ask me relevant questions to help build a well-structured application using Honcho. Consider asking about: - What I'm trying to build - My technical preferences and stack - Whether I want to use the demo server or self-host - My experience level with the technologies involved - Specific features I need (multi-user, voice, web UI, etc.) Once you understand my needs, help me create a working implementation with proper memory persistence. [Quickstart](https://docs.honcho.dev/v2/documentation/introduction/quickstart) [Architecture](https://docs.honcho.dev/v2/documentation/core-concepts/architecture) ⌘I --- # Create Message For Session - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-message-for-session#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation messages Create Message For Session [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const message = await client.apps.users.sessions.messages.create('app_id', 'user_id', 'session_id', { content: 'content', is_user: true, }); console.log(message.id); } main(); 200 422 { "id": "", "content": "", "is_user": true, "session_id": "", "created_at": "2023-11-07T05:31:56Z", "app_id": "", "user_id": "", "metadata": {} } POST http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / sessions / {session\_id} / messages Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const message = await client.apps.users.sessions.messages.create('app_id', 'user_id', 'session_id', { content: 'content', is_user: true, }); console.log(message.id); } main(); 200 422 { "id": "", "content": "", "is_user": true, "session_id": "", "created_at": "2023-11-07T05:31:56Z", "app_id": "", "user_id": "", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-message-for-session#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-message-for-session#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-message-for-session#parameter-user-id) user\_id string required ID of the user [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-message-for-session#parameter-session-id) session\_id string required ID of the session #### Body application/json Message creation parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-message-for-session#body-content) content string required Maximum string length: `50000` [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-message-for-session#body-is-user) is\_user boolean required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-message-for-session#body-metadata) metadata Metadata · object #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-message-for-session#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-message-for-session#response-content) content string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-message-for-session#response-is-user) is\_user boolean required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-message-for-session#response-session-id) session\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-message-for-session#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-message-for-session#response-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-message-for-session#response-user-id) user\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-message-for-session#response-metadata) metadata Metadata · object [Get Messages](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-messages) [Create Batch Messages For Session](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-batch-messages-for-session) ⌘I --- # Create Batch Messages For Session - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-batch-messages-for-session#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation messages Create Batch Messages For Session [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const messages = await client.apps.users.sessions.messages.batch('app_id', 'user_id', 'session_id', { messages: [{ content: 'content', is_user: true }], }); console.log(messages); } main(); 200 422 [\ {\ "id": "",\ "content": "",\ "is_user": true,\ "session_id": "",\ "created_at": "2023-11-07T05:31:56Z",\ "app_id": "",\ "user_id": "",\ "metadata": {}\ }\ ] POST http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / sessions / {session\_id} / messages / batch Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const messages = await client.apps.users.sessions.messages.batch('app_id', 'user_id', 'session_id', { messages: [{ content: 'content', is_user: true }], }); console.log(messages); } main(); 200 422 [\ {\ "id": "",\ "content": "",\ "is_user": true,\ "session_id": "",\ "created_at": "2023-11-07T05:31:56Z",\ "app_id": "",\ "user_id": "",\ "metadata": {}\ }\ ] #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-batch-messages-for-session#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-batch-messages-for-session#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-batch-messages-for-session#parameter-user-id) user\_id string required ID of the user [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-batch-messages-for-session#parameter-session-id) session\_id string required ID of the session #### Body application/json Batch of messages to create [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-batch-messages-for-session#body-messages) messages MessageCreate · object\[\] required Maximum array length: `100` Show child attributes #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-batch-messages-for-session#response-items-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-batch-messages-for-session#response-items-content) content string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-batch-messages-for-session#response-items-is-user) is\_user boolean required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-batch-messages-for-session#response-items-session-id) session\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-batch-messages-for-session#response-items-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-batch-messages-for-session#response-items-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-batch-messages-for-session#response-items-user-id) user\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-batch-messages-for-session#response-items-metadata) metadata Metadata · object [Create Message For Session](https://docs.honcho.dev/v1/api-reference/endpoint/messages/create-message-for-session) [Get Message](https://docs.honcho.dev/v1/api-reference/endpoint/messages/get-message) ⌘I --- # Get Metamessage - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessage#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation metamessages Get Metamessage [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const metamessage = await client.apps.users.metamessages.get('app_id', 'user_id', 'metamessage_id'); console.log(metamessage.id); } main(); 200 422 { "id": "", "label": "", "content": "", "user_id": "", "app_id": "", "session_id": "", "message_id": "", "created_at": "2023-11-07T05:31:56Z", "metamessage_type": "", "metadata": {} } GET http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / metamessages / {metamessage\_id} Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const metamessage = await client.apps.users.metamessages.get('app_id', 'user_id', 'metamessage_id'); console.log(metamessage.id); } main(); 200 422 { "id": "", "label": "", "content": "", "user_id": "", "app_id": "", "session_id": "", "message_id": "", "created_at": "2023-11-07T05:31:56Z", "metamessage_type": "", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessage#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessage#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessage#parameter-user-id) user\_id string required ID of the user [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessage#parameter-metamessage-id) metamessage\_id string required ID of the metamessage to retrieve #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessage#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessage#response-label) label string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessage#response-content) content string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessage#response-user-id) user\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessage#response-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessage#response-session-id-one-of-0) session\_id string | null required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessage#response-message-id-one-of-0) message\_id string | null required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessage#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessage#response-metamessage-type) metamessage\_type string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessage#response-metadata) metadata Metadata · object [Get Metamessages](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessages) [Update Metamessage](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage) ⌘I --- # Get Session - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-session#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation sessions Get Session [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const session = await client.apps.users.sessions.get('app_id', 'user_id'); console.log(session.id); } main(); 200 422 { "id": "", "is_active": true, "user_id": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } GET http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / sessions Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const session = await client.apps.users.sessions.get('app_id', 'user_id'); console.log(session.id); } main(); 200 422 { "id": "", "is_active": true, "user_id": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-session#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-session#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-session#parameter-user-id) user\_id string required ID of the user #### Query Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-session#parameter-one-of-0) session\_id string | null Session ID to retrieve. If not provided, uses JWT #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-session#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-session#response-is-active) is\_active boolean required [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-session#response-user-id) user\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-session#response-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-session#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-session#response-metadata) metadata Metadata · object [Create Session](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/create-session) [Update Session](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/update-session) ⌘I --- # Create Metamessage - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation metamessages Create Metamessage [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const metamessage = await client.apps.users.metamessages.create('app_id', 'user_id', { content: 'content', metamessage_type: 'x', }); console.log(metamessage.id); } main(); 200 422 { "id": "", "label": "", "content": "", "user_id": "", "app_id": "", "session_id": "", "message_id": "", "created_at": "2023-11-07T05:31:56Z", "metamessage_type": "", "metadata": {} } POST http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / metamessages Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const metamessage = await client.apps.users.metamessages.create('app_id', 'user_id', { content: 'content', metamessage_type: 'x', }); console.log(metamessage.id); } main(); 200 422 { "id": "", "label": "", "content": "", "user_id": "", "app_id": "", "session_id": "", "message_id": "", "created_at": "2023-11-07T05:31:56Z", "metamessage_type": "", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage#parameter-user-id) user\_id string required ID of the user #### Body application/json Metamessage creation parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage#body-metamessage-type) metamessage\_type string required Required string length: `1 - 50` [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage#body-content) content string required Maximum string length: `50000` [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage#body-session-id-one-of-0) session\_id string | null [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage#body-message-id-one-of-0) message\_id string | null [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage#body-metadata) metadata Metadata · object #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage#response-label) label string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage#response-content) content string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage#response-user-id) user\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage#response-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage#response-session-id-one-of-0) session\_id string | null required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage#response-message-id-one-of-0) message\_id string | null required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage#response-metamessage-type) metamessage\_type string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/create-metamessage#response-metadata) metadata Metadata · object [Create Key](https://docs.honcho.dev/v1/api-reference/endpoint/keys/create-key) [Get Metamessages](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessages) ⌘I --- # Queue Status - Honcho [Skip to main content](https://docs.honcho.dev/v3/documentation/features/advanced/queue-status#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Advanced Queue Status [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Tracked task types](https://docs.honcho.dev/v3/documentation/features/advanced/queue-status#tracked-task-types) Whenever messages are stored in Honcho, background processes kick off to [reason](https://docs.honcho.dev/v3/documentation/core-concepts/reasoning) about the conversation and generate insights. Reasoning is an asynchronous process and will not immediately generate insights for the latest message you’ve sent. This is by design: we want to reason efficiently over batches of messages rather than assessing each message in a vacuum. Honcho provides several utilities to check the status of the queue. Python typescript from honcho import Honcho honcho = Honcho() status = honcho.queue_status() Output types Python TypeScript class QueueStatus(BaseModel): completed_work_units: int """Completed work units""" in_progress_work_units: int """Work units currently being processed""" pending_work_units: int """Work units waiting to be processed""" total_work_units: int """Total work units""" sessions: Optional[Dict[str, Sessions]] = None """Per-session status when not filtered by session""" Whenever a message is sent it will generate several tasks. These could be tasks such as generating insights, cleaning up a representation, summarizing a conversation etc. These tasks are defined based on who is sending the message, what session the message is in, and potentially who is observing the message. We call the combination of these parameters a `work_unit` This has a few different implications. * tasks within the same work\_unit are processed sequentially, but multiple work\_units will be processed in parallel * If local representations are turned in a Session then a message will generate an additional work unit for every peer that has `observe_others=True` ### [​](https://docs.honcho.dev/v3/documentation/features/advanced/queue-status#tracked-task-types) Tracked task types The queue status endpoint reports on the following task types: | Task Type | Description | | --- | --- | | **representation** | Memory formation — the deriver processes messages and extracts observations about peers | | **summary** | Session summarization — creates short and long summaries at configurable message intervals | | **dream** | Memory consolidation — explores and consolidates observations to improve memory quality | Internal infrastructure tasks (such as webhook delivery, resource deletion, and vector reconciliation) are **not** included in queue status counts. **Completed counts are not lifetime totals.** Honcho periodically cleans up processed queue items to keep the queue table lean. As a result, `completed_work_units` reflects items completed since the last cleanup cycle, not the total number of items ever processed. The `queue_status` method can take additional parameters to scope the status to a specific work unit: Python TypeScript def queue_status( self, observer_id: str | None = None, sender_id: str | None = None, session_id: str | None = None, ) -> QueueStatus: Additionally, there are queue status methods available on the session objects in each of the SDKs. **Do not wait for the queue to be empty.** The queue is a continuous processing system—new messages may arrive at any time, and “completion” is not a meaningful state. Design your application to work without assuming the queue will ever be fully drained. Use `queueStatus()` for observability and debugging, not for synchronization. Below are the function signatures for the session level queue status method: python TypeScript @validate_call def queue_status( self, observer_id: str | None = None, sender_id: str | None = None, ) -> QueueStatus: [Dreaming](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming) [Search](https://docs.honcho.dev/v3/documentation/features/advanced/search) ⌘I --- # Update Metamessage - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation metamessages Update Metamessage [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const metamessage = await client.apps.users.metamessages.update('app_id', 'user_id', 'metamessage_id'); console.log(metamessage.id); } main(); 200 422 { "id": "", "label": "", "content": "", "user_id": "", "app_id": "", "session_id": "", "message_id": "", "created_at": "2023-11-07T05:31:56Z", "metamessage_type": "", "metadata": {} } PUT http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / metamessages / {metamessage\_id} Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const metamessage = await client.apps.users.metamessages.update('app_id', 'user_id', 'metamessage_id'); console.log(metamessage.id); } main(); 200 422 { "id": "", "label": "", "content": "", "user_id": "", "app_id": "", "session_id": "", "message_id": "", "created_at": "2023-11-07T05:31:56Z", "metamessage_type": "", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage#parameter-user-id) user\_id string required ID of the user [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage#parameter-metamessage-id) metamessage\_id string required ID of the metamessage to update #### Body application/json Updated metamessage parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage#body-session-id-one-of-0) session\_id string | null [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage#body-message-id-one-of-0) message\_id string | null [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage#body-metamessage-type-one-of-0) metamessage\_type string | null [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage#body-metadata-one-of-0) metadata Metadata · object #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage#response-label) label string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage#response-content) content string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage#response-user-id) user\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage#response-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage#response-session-id-one-of-0) session\_id string | null required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage#response-message-id-one-of-0) message\_id string | null required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage#response-metamessage-type) metamessage\_type string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/update-metamessage#response-metadata) metadata Metadata · object [Get Metamessage](https://docs.honcho.dev/v1/api-reference/endpoint/metamessages/get-metamessage) [Get Collections](https://docs.honcho.dev/v1/api-reference/endpoint/collections/get-collections) ⌘I --- # Model Context Protocol (MCP) - Honcho [Skip to main content](https://docs.honcho.dev/v3/guides/integrations/mcp#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Integrations Model Context Protocol (MCP) [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Client Setup](https://docs.honcho.dev/v3/guides/integrations/mcp#client-setup) * [Claude Desktop](https://docs.honcho.dev/v3/guides/integrations/mcp#claude-desktop) * [Claude Code](https://docs.honcho.dev/v3/guides/integrations/mcp#claude-code) * [Codex](https://docs.honcho.dev/v3/guides/integrations/mcp#codex) * [Cursor](https://docs.honcho.dev/v3/guides/integrations/mcp#cursor) * [Windsurf](https://docs.honcho.dev/v3/guides/integrations/mcp#windsurf) * [VS Code (Copilot Chat)](https://docs.honcho.dev/v3/guides/integrations/mcp#vs-code-copilot-chat) * [Cline](https://docs.honcho.dev/v3/guides/integrations/mcp#cline) * [Zed](https://docs.honcho.dev/v3/guides/integrations/mcp#zed) * [Optional Configuration](https://docs.honcho.dev/v3/guides/integrations/mcp#optional-configuration) * [Available Tools](https://docs.honcho.dev/v3/guides/integrations/mcp#available-tools) * [Verify It Works](https://docs.honcho.dev/v3/guides/integrations/mcp#verify-it-works) * [Troubleshooting](https://docs.honcho.dev/v3/guides/integrations/mcp#troubleshooting) The Honcho MCP server gives any MCP-compatible AI tool persistent memory and personalization. Connect it once and your AI assistant learns who you are, remembers your preferences, and gets better over time — across every conversation. **Server URL:** `https://mcp.honcho.dev` You’ll need an API key from [app.honcho.dev](https://app.honcho.dev/) to use the hosted MCP server. [​](https://docs.honcho.dev/v3/guides/integrations/mcp#client-setup) Client Setup ------------------------------------------------------------------------------------ Pick your client below and add the config. After adding, **restart the client fully** for changes to take effect. ### [​](https://docs.honcho.dev/v3/guides/integrations/mcp#claude-desktop) Claude Desktop * macOS * Windows Edit `~/Library/Application Support/Claude/claude_desktop_config.json`: Edit `%APPDATA%\Claude\claude_desktop_config.json`: { "mcpServers": { "honcho": { "command": "npx", "args": [\ "mcp-remote",\ "https://mcp.honcho.dev",\ "--header",\ "Authorization:${AUTH_HEADER}",\ "--header",\ "X-Honcho-User-Name:${USER_NAME}"\ ], "env": { "AUTH_HEADER": "Bearer hch-your-key-here", "USER_NAME": "YourName" } } } } After saving, fully quit and relaunch Claude Desktop. The Honcho tools should appear in the tool picker. For best results, create a project and paste these [instructions](https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md) into the “Project Instructions” field so Claude knows how to use the memory tools. ### [​](https://docs.honcho.dev/v3/guides/integrations/mcp#claude-code) Claude Code claude mcp add honcho \ --transport http \ --url "https://mcp.honcho.dev" \ --header "Authorization: Bearer hch-your-key-here" \ --header "X-Honcho-User-Name: YourName" Or if you prefer the [Claude Code Honcho plugin](https://docs.honcho.dev/v3/guides/integrations/claudecode) for a deeper integration with persistent memory, git awareness, and agent skills: /plugin marketplace add plastic-labs/claude-honcho ### [​](https://docs.honcho.dev/v3/guides/integrations/mcp#codex) Codex Add to `~/.codex/config.toml`: [mcp_servers.honcho] command = "npx" args = [\ "mcp-remote",\ "https://mcp.honcho.dev",\ "--header",\ "Authorization:Bearer hch-your-key-here",\ "--header",\ "X-Honcho-User-Name:YourName"\ ] Codex only supports stdio transport, so it uses `mcp-remote` as a bridge. Restart both the Codex CLI and VS Code extension after editing. ### [​](https://docs.honcho.dev/v3/guides/integrations/mcp#cursor) Cursor Cursor supports MCP servers natively via HTTP. Add to your global config at `~/.cursor/mcp.json` or per-project at `.cursor/mcp.json`: { "mcpServers": { "honcho": { "url": "https://mcp.honcho.dev", "headers": { "Authorization": "Bearer hch-your-key-here", "X-Honcho-User-Name": "YourName" } } } } Alternatively, go to **Cursor Settings → MCP** and add a new HTTP server with the URL and headers above. ### [​](https://docs.honcho.dev/v3/guides/integrations/mcp#windsurf) Windsurf Add to `~/.codeium/windsurf/mcp_config.json`: { "mcpServers": { "honcho": { "serverUrl": "https://mcp.honcho.dev", "headers": { "Authorization": "Bearer hch-your-key-here", "X-Honcho-User-Name": "YourName" } } } } Windsurf uses `serverUrl` instead of `url`. ### [​](https://docs.honcho.dev/v3/guides/integrations/mcp#vs-code-copilot-chat) VS Code (Copilot Chat) Add to your workspace `.vscode/mcp.json`: { "servers": { "honcho": { "type": "http", "url": "https://mcp.honcho.dev", "headers": { "Authorization": "Bearer hch-your-key-here", "X-Honcho-User-Name": "YourName" } } } } Or add to your User Settings JSON (`Cmd+Shift+P` → “Preferences: Open User Settings (JSON)”): { "mcp": { "servers": { "honcho": { "type": "http", "url": "https://mcp.honcho.dev", "headers": { "Authorization": "Bearer hch-your-key-here", "X-Honcho-User-Name": "YourName" } } } } } ### [​](https://docs.honcho.dev/v3/guides/integrations/mcp#cline) Cline Cline supports remote MCP servers natively. Open Cline’s MCP settings at: * macOS * Windows `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json` { "mcpServers": { "honcho": { "url": "https://mcp.honcho.dev", "headers": { "Authorization": "Bearer hch-your-key-here", "X-Honcho-User-Name": "YourName" } } } } Or add it via the Cline sidebar: click the MCP Servers icon → **Configure** → **Remote Servers**. ### [​](https://docs.honcho.dev/v3/guides/integrations/mcp#zed) Zed Add to `~/.config/zed/settings.json`: { "context_servers": { "honcho": { "url": "https://mcp.honcho.dev", "headers": { "Authorization": "Bearer hch-your-key-here", "X-Honcho-User-Name": "YourName" } } } } Zed uses `context_servers` instead of `mcpServers`. Native HTTP support requires Zed v0.214.5 or later. * * * [​](https://docs.honcho.dev/v3/guides/integrations/mcp#optional-configuration) Optional Configuration -------------------------------------------------------------------------------------------------------- You can customize the assistant name and workspace ID by adding extra headers. Both are optional. | Header | Default | Description | | --- | --- | --- | | `Authorization` | _required_ | `Bearer hch-your-key-here` | | `X-Honcho-User-Name` | _required_ | What the AI should call you | | `X-Honcho-Assistant-Name` | `"Assistant"` | Name for the AI peer | | `X-Honcho-Workspace-ID` | `"default"` | Isolate memory per project | Example with all headers (Claude Desktop format): { "mcpServers": { "honcho": { "command": "npx", "args": [\ "mcp-remote",\ "https://mcp.honcho.dev",\ "--header",\ "Authorization:${AUTH_HEADER}",\ "--header",\ "X-Honcho-User-Name:${USER_NAME}",\ "--header",\ "X-Honcho-Assistant-Name:${ASSISTANT_NAME}",\ "--header",\ "X-Honcho-Workspace-ID:${WORKSPACE_ID}"\ ], "env": { "AUTH_HEADER": "Bearer hch-your-key-here", "USER_NAME": "YourName", "ASSISTANT_NAME": "Claude", "WORKSPACE_ID": "my-project" } } } } * * * [​](https://docs.honcho.dev/v3/guides/integrations/mcp#available-tools) Available Tools ------------------------------------------------------------------------------------------ The recommended flow for a standard conversation uses `create_session` + `add_messages_to_session` + `chat`. See the [full instructions](https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md) for a complete walkthrough. **Workspace** — `inspect_workspace`, `list_workspaces`, `search`, `get_metadata`, `set_metadata` **Peers** — `create_peer`, `list_peers`, `chat`, `get_peer_card`, `set_peer_card`, `get_peer_context`, `get_representation` **Sessions** — `create_session`, `list_sessions`, `delete_session`, `clone_session`, `add_peers_to_session`, `remove_peers_from_session`, `get_session_peers`, `inspect_session`, `add_messages_to_session`, `get_session_messages`, `get_session_message`, `get_session_context` **Conclusions** — `list_conclusions`, `query_conclusions`, `create_conclusions`, `delete_conclusion` **System** — `schedule_dream`, `get_queue_status` * * * [​](https://docs.honcho.dev/v3/guides/integrations/mcp#verify-it-works) Verify It Works ------------------------------------------------------------------------------------------ After setup, try asking your AI assistant: > “What do you know about me?” On the first conversation there won’t be much — but after a few exchanges, Honcho’s background reasoning will start building a representation of you. Ask again after a couple of conversations and you’ll see the difference. * * * [​](https://docs.honcho.dev/v3/guides/integrations/mcp#troubleshooting) Troubleshooting ------------------------------------------------------------------------------------------ | Problem | Fix | | --- | --- | | Tools don’t show up | Make sure you fully restarted the client after adding the config. | | Authorization errors | Check your API key at [app.honcho.dev](https://app.honcho.dev/)
. It should start with `hch-`. | | `npx` not found | Install Node.js — your AI assistant can help with this. | | ”No personalization insights found” | Normal for new users. Honcho needs a few conversations to build context. | | Connection timeouts | Check that `https://mcp.honcho.dev` is accessible from your network. | Need help? Join us on [Discord](https://discord.gg/honcho) or open an issue on [GitHub](https://github.com/plastic-labs/honcho/tree/main/mcp) . [LangGraph](https://docs.honcho.dev/v3/guides/integrations/langgraph) [n8n](https://docs.honcho.dev/v3/guides/integrations/n8n) ⌘I --- # Get Or Create User - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-or-create-user#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation users Get Or Create User [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const user = await client.apps.users.getOrCreate('app_id', 'name'); console.log(user.id); } main(); 200 422 { "id": "", "name": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } GET http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / get\_or\_create / {name} Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const user = await client.apps.users.getOrCreate('app_id', 'name'); console.log(user.id); } main(); 200 422 { "id": "", "name": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-or-create-user#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-or-create-user#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-or-create-user#parameter-name) name string required Name of the user to get or create #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-or-create-user#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-or-create-user#response-name) name string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-or-create-user#response-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-or-create-user#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-or-create-user#response-metadata) metadata Metadata · object [Get User](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-user) [Update User](https://docs.honcho.dev/v1/api-reference/endpoint/users/update-user) ⌘I --- # Create User - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/users/create-user#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation users Create User [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const user = await client.apps.users.create('app_id', { name: 'x' }); console.log(user.id); } main(); 200 422 { "id": "", "name": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } POST http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const user = await client.apps.users.create('app_id', { name: 'x' }); console.log(user.id); } main(); 200 422 { "id": "", "name": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/create-user#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/create-user#parameter-app-id) app\_id string required ID of the app #### Body application/json User creation parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/create-user#body-name) name string required Required string length: `1 - 100` [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/create-user#body-metadata) metadata Metadata · object #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/create-user#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/create-user#response-name) name string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/create-user#response-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/create-user#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/create-user#response-metadata) metadata Metadata · object [Get Users](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-users) [Get User By Name](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-user-by-name) ⌘I --- # Get User By Name - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-user-by-name#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation users Get User By Name [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const user = await client.apps.users.getByName('app_id', 'name'); console.log(user.id); } main(); 200 422 { "id": "", "name": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } GET http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / name / {name} Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { const user = await client.apps.users.getByName('app_id', 'name'); console.log(user.id); } main(); 200 422 { "id": "", "name": "", "app_id": "", "created_at": "2023-11-07T05:31:56Z", "metadata": {} } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-user-by-name#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-user-by-name#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-user-by-name#parameter-name) name string required Name of the user to retrieve #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-user-by-name#response-id) id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-user-by-name#response-name) name string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-user-by-name#response-app-id) app\_id string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-user-by-name#response-created-at) created\_at string required [​](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-user-by-name#response-metadata) metadata Metadata · object [Create User](https://docs.honcho.dev/v1/api-reference/endpoint/users/create-user) [Get User](https://docs.honcho.dev/v1/api-reference/endpoint/users/get-user) ⌘I --- # Claude Code - Honcho [Skip to main content](https://docs.honcho.dev/v3/guides/integrations/claude-code#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Integrations Claude Code [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [Quick Start](https://docs.honcho.dev/v3/guides/integrations/claude-code#quick-start) * [Step 1: Get Your Honcho API Key](https://docs.honcho.dev/v3/guides/integrations/claude-code#step-1-get-your-honcho-api-key) * [Step 2: Set Environment Variables](https://docs.honcho.dev/v3/guides/integrations/claude-code#step-2-set-environment-variables) * [Step 3: Install the Plugin](https://docs.honcho.dev/v3/guides/integrations/claude-code#step-3-install-the-plugin) * [Step 4: Restart Claude Code](https://docs.honcho.dev/v3/guides/integrations/claude-code#step-4-restart-claude-code) * [Step 5: (Optional) Kickstart with an Interview](https://docs.honcho.dev/v3/guides/integrations/claude-code#step-5-optional-kickstart-with-an-interview) * [What You Get](https://docs.honcho.dev/v3/guides/integrations/claude-code#what-you-get) * [Configuration](https://docs.honcho.dev/v3/guides/integrations/claude-code#configuration) * [Session Strategies](https://docs.honcho.dev/v3/guides/integrations/claude-code#session-strategies) * [Host-Aware Configuration](https://docs.honcho.dev/v3/guides/integrations/claude-code#host-aware-configuration) * [Linking Hosts for Cross-Tool Context](https://docs.honcho.dev/v3/guides/integrations/claude-code#linking-hosts-for-cross-tool-context) * [Global Override](https://docs.honcho.dev/v3/guides/integrations/claude-code#global-override) * [Building with Teammates](https://docs.honcho.dev/v3/guides/integrations/claude-code#building-with-teammates) * [Logging](https://docs.honcho.dev/v3/guides/integrations/claude-code#logging) * [MCP Tools](https://docs.honcho.dev/v3/guides/integrations/claude-code#mcp-tools) * [Skills (Slash Commands)](https://docs.honcho.dev/v3/guides/integrations/claude-code#skills-slash-commands) * [The Interview](https://docs.honcho.dev/v3/guides/integrations/claude-code#the-interview) * [Environment Variables](https://docs.honcho.dev/v3/guides/integrations/claude-code#environment-variables) * [Using a local Honcho instance](https://docs.honcho.dev/v3/guides/integrations/claude-code#using-a-local-honcho-instance) * [Using Honcho with Claude Desktop](https://docs.honcho.dev/v3/guides/integrations/claude-code#using-honcho-with-claude-desktop) * [Step 1: Get Your API Key](https://docs.honcho.dev/v3/guides/integrations/claude-code#step-1-get-your-api-key) * [Step 2: Configure Claude Desktop](https://docs.honcho.dev/v3/guides/integrations/claude-code#step-2-configure-claude-desktop) * [Step 3: Restart Claude Desktop](https://docs.honcho.dev/v3/guides/integrations/claude-code#step-3-restart-claude-desktop) * [Step 4: Add Instructions](https://docs.honcho.dev/v3/guides/integrations/claude-code#step-4-add-instructions) * [Next Steps](https://docs.honcho.dev/v3/guides/integrations/claude-code#next-steps) Give Claude Code long-term memory that survives context wipes, session restarts, and `ctrl+c`. Claude remembers what you’re working on, your preferences, and what it was doing across all your projects. [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#quick-start) Quick Start ------------------------------------------------------------------------------------------ ### [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#step-1-get-your-honcho-api-key) Step 1: Get Your Honcho API Key 1. Go to **[app.honcho.dev](https://app.honcho.dev/) ** 2. Sign up or log in 3. Copy your API key (starts with `hch-`) ### [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#step-2-set-environment-variables) Step 2: Set Environment Variables Add these to your shell config (`~/.zshrc`, `~/.bashrc`, or `~/.profile`): # Required export HONCHO_API_KEY="hch-your-api-key-here" # Optional (defaults shown) export HONCHO_PEER_NAME="$USER" # Your name/identity Then reload your shell: source ~/.zshrc # or ~/.bashrc ### [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#step-3-install-the-plugin) Step 3: Install the Plugin This plugin requires [Bun](https://bun.sh/) . If you don’t have it: `curl -fsSL https://bun.sh/install | bash` Open Claude Code and run: /plugin marketplace add plastic-labs/claude-honcho Then install: /plugin install honcho@honcho ### [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#step-4-restart-claude-code) Step 4: Restart Claude Code # Exit Claude Code (ctrl+c or /exit) # Start it again claude **That’s it!** You should see the Honcho pixel art and memory loading on startup. ### [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#step-5-optional-kickstart-with-an-interview) Step 5: (Optional) Kickstart with an Interview /honcho:interview Claude will interview you about your personal preferences to kickstart a representation of you. What it learns will be saved in Honcho and remembered forever. The interview is specific to the peer name you chose — it carries across different projects! [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#what-you-get) What You Get -------------------------------------------------------------------------------------------- * **Persistent Memory** — Claude remembers your preferences, projects, and context across sessions * **Survives Context Wipes** — Even when Claude’s context window resets, memory persists * **Git Awareness** — Detects branch switches, commits, and changes made outside Claude * **Flexible Sessions** — Map sessions per directory, per git branch, or per chat instance * **AI Self-Awareness** — Claude knows what it was working on, even after restarts * **Cross-Tool Context** — Link workspaces across Claude Code, Cursor, and other hosts so context flows between tools * **Team Support** — Multiple people can share a workspace and build context together * **MCP Tools** — Search memory, query knowledge about you, and save insights [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#configuration) Configuration ---------------------------------------------------------------------------------------------- All configuration lives in a single global file at `~/.honcho/config.json`. You can edit it directly, use the `/honcho:config` skill interactively, or use the `set_config` MCP tool. Environment variables work for initial setup but the config file takes precedence once it exists. { // Required "apiKey": "hch-v2-...", // Identity "peerName": "alice", // Your name (default: $USER) // Host-specific settings — each tool gets its own workspace and AI peer "hosts": { "claude_code": { "workspace": "claude_code", // Workspace for Claude Code sessions "aiPeer": "claude", // AI identity in this workspace "linkedHosts": ["cursor"] // Read context from other hosts (optional) }, "cursor": { "workspace": "cursor", "aiPeer": "cursor" } }, // Session mapping "sessionStrategy": "per-directory", // "per-directory" | "git-branch" | "chat-instance" "sessionPeerPrefix": true, // Prefix session names with peerName (default: true) // Message handling "saveMessages": true, "messageUpload": { "maxUserTokens": null, // Truncate user messages (null = no limit) "maxAssistantTokens": null, // Truncate assistant messages (null = no limit) "summarizeAssistant": false // Summarize instead of sending full assistant text }, // Context retrieval "contextRefresh": { "messageThreshold": 30, // Refresh context every N messages "ttlSeconds": 300, // Cache TTL for context "skipDialectic": false // Skip dialectic chat() calls in user-prompt hook }, // Endpoint "endpoint": { "environment": "production" // "production" | "local" // or: "baseUrl": "http://your-server:8000/v3" }, // Miscellaneous "localContext": { "maxEntries": 50 }, "enabled": true, "logging": true, // Advanced: force all hosts to use the same workspace "globalOverride": false } ### [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#session-strategies) Session Strategies Session strategy controls how Honcho maps your conversations to sessions: | Strategy | Behavior | Best for | | --- | --- | --- | | `per-directory` (default) | One session per project directory. Stable across restarts. | Most users — each project accumulates its own memory | | `git-branch` | Session name includes the current git branch. Switching branches switches sessions. | Feature-branch workflows where context per branch matters | | `chat-instance` | Each Claude Code chat gets its own session. No continuity between restarts. | Ephemeral usage or when you want a clean slate each time | Session names are prefixed with your `peerName` by default (e.g., `alice-my-project`). Set `sessionPeerPrefix: false` if you’re the only user and want shorter names. ### [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#host-aware-configuration) Host-Aware Configuration The plugin auto-detects which tool is running it (Claude Code, Cursor, etc.) and reads the matching block from `hosts`. Each host gets its own workspace and AI peer name, so data stays separated by default. **Host detection priority:** 1. `HONCHO_HOST` env var (explicit override) 2. `cursor_version` in hook stdin (Cursor detected) 3. `CURSOR_PROJECT_DIR` env var (Cursor child process) 4. Default: `claude_code` ### [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#linking-hosts-for-cross-tool-context) Linking Hosts for Cross-Tool Context If you use both Claude Code and Cursor, you can link them so context from one is readable in the other. Writes always stay in the current host’s workspace — linking only adds read access. { "hosts": { "claude_code": { "workspace": "claude_code", "aiPeer": "claude", "linkedHosts": ["cursor"] // Claude Code can read Cursor's context }, "cursor": { "workspace": "cursor", "aiPeer": "cursor", "linkedHosts": ["claude_code"] // Cursor can read Claude Code's context } } } Or use `/honcho:config` and select **Workspace > Linking** to set this up interactively. ### [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#global-override) Global Override If you want all hosts to share a single workspace (instead of per-host isolation), set `globalOverride: true` and a flat `workspace` field: { "globalOverride": true, "workspace": "shared", "hosts": { "claude_code": { "aiPeer": "claude" }, "cursor": { "aiPeer": "cursor" } } } All tools will read and write to the `shared` workspace. Each tool still uses its own AI peer name. [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#building-with-teammates) Building with Teammates ------------------------------------------------------------------------------------------------------------------ Multiple people can share context by pointing to the same workspace. Each person uses their own `peerName` as identity, and sessions are automatically prefixed with it to avoid collisions. **Person A** (`~/.honcho/config.json`): { "apiKey": "hch-v2-team-key...", "peerName": "alice", "hosts": { "claude_code": { "workspace": "team-acme", "aiPeer": "claude" } } } **Person B** (`~/.honcho/config.json`): { "apiKey": "hch-v2-team-key...", "peerName": "bob", "hosts": { "claude_code": { "workspace": "team-acme", "aiPeer": "claude" } } } Both Alice and Bob write to the `team-acme` workspace. Their sessions are namespaced (e.g., `alice-my-project`, `bob-my-project`) so data doesn’t collide, but Honcho’s dialectic reasoning can draw on context from both users. [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#logging) Logging ---------------------------------------------------------------------------------- The plugin logs activity to `~/.honcho/` and to Claude Code’s verbose mode, so you can see exactly how Honcho is being used — what context is loaded at session start, what messages are saved, and what context is injected into Claude’s prompts. Set `logging` to `false` in your config (or `HONCHO_LOGGING=false`) to disable file logging. [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#mcp-tools) MCP Tools -------------------------------------------------------------------------------------- The plugin provides these tools via MCP: | Tool | Description | | --- | --- | | `search` | Semantic search across session messages | | `chat` | Query Honcho’s knowledge about the user | | `create_conclusion` | Save insights about the user to memory | | `get_config` | View current configuration and status | | `set_config` | Change any configuration field programmatically | [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#skills-slash-commands) Skills (Slash Commands) ---------------------------------------------------------------------------------------------------------------- | Command | Description | | --- | --- | | `/honcho:status` | Show current memory status and connection info | | `/honcho:config` | Interactive configuration menu | | `/honcho:setup` | First-time setup — validate API key and create config | | `/honcho:interview` | Interview to capture stable, cross-project user preferences | ### [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#the-interview) The Interview The `/honcho:interview` skill conducts a short interview to learn stable, cross-project aspects about you: * **Communication style** — Concise answers, detailed explanations, or a mix * **Tone** — Direct and professional or conversational * **Structure** — Bullet points, step-by-step, or narrative * **Technical depth** — Beginner, intermediate, or expert * **Code quality focus** — Clarity, performance, tests, or minimal changes * **Collaboration style** — Make changes directly, propose options, or ask first Each answer is saved as a conclusion in Honcho memory and persists across all your projects. [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#environment-variables) Environment Variables -------------------------------------------------------------------------------------------------------------- Environment variables work for initial bootstrap (before a config file exists). Once `~/.honcho/config.json` is written, the config file takes precedence for host-specific fields like `workspace`. | Variable | Required | Default | Description | | --- | --- | --- | --- | | `HONCHO_API_KEY` | **Yes** | — | Your Honcho API key from [app.honcho.dev](https://app.honcho.dev/) | | `HONCHO_PEER_NAME` | No | `$USER` | Your identity in the memory system | | `HONCHO_WORKSPACE` | No | `claude_code` | Workspace name (used only when no config file exists) | | `HONCHO_AI_PEER` | No | `claude` | AI peer name | | `HONCHO_HOST` | No | auto-detected | Force host detection: `claude_code`, `cursor`, or `obsidian` | | `HONCHO_ENDPOINT` | No | `production` | `production`, `local`, or a full URL | | `HONCHO_ENABLED` | No | `true` | Set to `false` to disable | | `HONCHO_SAVE_MESSAGES` | No | `true` | Set to `false` to stop saving messages | | `HONCHO_LOGGING` | No | `true` | Set to `false` to disable file logging to `~/.honcho/` | ### [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#using-a-local-honcho-instance) Using a local Honcho instance Via config file: { "endpoint": { "environment": "local" } } Or via env var: export HONCHO_ENDPOINT="local" # Uses http://localhost:8000/v3 * * * [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#using-honcho-with-claude-desktop) Using Honcho with Claude Desktop ------------------------------------------------------------------------------------------------------------------------------------ You can also use Honcho with the Claude Desktop app via MCP. This lets Claude manage its own memory in the native desktop experience. ### [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#step-1-get-your-api-key) Step 1: Get Your API Key Get an API key from [app.honcho.dev](https://app.honcho.dev/) . ### [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#step-2-configure-claude-desktop) Step 2: Configure Claude Desktop This requires [Node.js](https://nodejs.org/) . Claude Desktop or Claude Code can help you install it! Navigate to Claude Desktop’s custom MCP servers settings and add Honcho: { "mcpServers": { "honcho": { "command": "npx", "args": [\ "mcp-remote",\ "https://mcp.honcho.dev",\ "--header",\ "Authorization:${AUTH_HEADER}",\ "--header",\ "X-Honcho-User-Name:${USER_NAME}"\ ], "env": { "AUTH_HEADER": "Bearer ", "USER_NAME": "" } } } } **Optional customization** — You can also set a custom assistant name and workspace ID: { "mcpServers": { "honcho": { "command": "npx", "args": [\ "mcp-remote",\ "https://mcp.honcho.dev",\ "--header",\ "Authorization:${AUTH_HEADER}",\ "--header",\ "X-Honcho-User-Name:${USER_NAME}",\ "--header",\ "X-Honcho-Assistant-Name:${ASSISTANT_NAME}",\ "--header",\ "X-Honcho-Workspace-ID:${WORKSPACE_ID}"\ ], "env": { "AUTH_HEADER": "Bearer ", "USER_NAME": "", "ASSISTANT_NAME": "", "WORKSPACE_ID": "" } } } } ### [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#step-3-restart-claude-desktop) Step 3: Restart Claude Desktop Upon relaunch, Honcho should start and the tools will be available. ### [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#step-4-add-instructions) Step 4: Add Instructions The Desktop app doesn’t allow system prompts directly, but you can create a project and paste [these instructions](https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md) into the “Project Instructions” field. Claude will then query for insights before responding and write your messages to storage! * * * [​](https://docs.honcho.dev/v3/guides/integrations/claude-code#next-steps) Next Steps ---------------------------------------------------------------------------------------- GitHub Repository ----------------- Source code, issues, and README. Honcho Architecture ------------------- Learn about peers, sessions, and dialectic reasoning. [Overview](https://docs.honcho.dev/v3/guides/overview) [CrewAI](https://docs.honcho.dev/v3/guides/integrations/crewai) ⌘I --- # Peer Card - Honcho [Skip to main content](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Advanced Peer Card [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [What Goes in a Peer Card](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#what-goes-in-a-peer-card) * [How Peer Cards Are Created](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#how-peer-cards-are-created) * [Directional Peer Cards](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#directional-peer-cards) * [Where Peer Cards Are Used](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#where-peer-cards-are-used) * [In the Dialectic (Chat Endpoint)](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#in-the-dialectic-chat-endpoint) * [In Context Retrieval](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#in-context-retrieval) * [During Dreaming](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#during-dreaming) * [Limits](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#limits) * [Configuration](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#configuration) * [Best Practices](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#best-practices) A **peer card** is a list of stable, biographical facts about a peer—name, occupation, preferences, standing instructions—that acts as a quick-reference profile. While the full [representation](https://docs.honcho.dev/v3/documentation/core-concepts/representation) contains all of Honcho’s reasoning (conclusions, summaries, semantic search results), the peer card captures the grounding facts that should never be forgotten. Think of it as the front of a contact card: the information an agent needs at a glance to know who it’s talking to. [​](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#what-goes-in-a-peer-card) What Goes in a Peer Card ------------------------------------------------------------------------------------------------------------------------------ Peer cards are designed for **durable, biographical information**—things that remain true across sessions and contexts. Each fact is stored as a single string in a list. | Category | Examples | | --- | --- | | Identity | `"Name: Alice"`, `"Age: 28"`, `"Location: Portland, OR"` | | Occupation | `"Works as a senior engineer at Acme Corp"` | | Relationships | `"Has a dog named Max"`, `"Married to Bob"` | | Instructions | `"INSTRUCTION: Always address as Dr. Chen"` | | Preferences | `"PREFERENCE: Prefers concise responses"` | | Traits | `"TRAIT: Detail-oriented, prefers data over anecdotes"` | Peer cards are **not** for transient information like current mood, recent conversation topics, or reasoning traces. Those belong in conclusions and summaries. [​](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#how-peer-cards-are-created) How Peer Cards Are Created ---------------------------------------------------------------------------------------------------------------------------------- Peer cards are populated through two paths: **1\. Automatic (via Dreaming)** When [dreaming](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming) runs, the deduction and induction specialists extract stable biographical facts from existing conclusions and write them to the peer card. This happens without any manual intervention—Honcho identifies facts like names, occupations, and preferences from conversation history and records them automatically. **2\. Manual (via SDK or API)** You can set a peer card directly. This is useful for bootstrapping a peer with known information before any conversation has occurred, or for correcting facts that Honcho hasn’t yet discovered. Python TypeScript from honcho import Honcho honcho = Honcho() peer = honcho.peer("user-123") # Set the peer card peer.set_card([\ "Name: Alice. Also known as 'Ali'.",\ "College student at MIT, studying computer science.",\ "PREFERENCE: Prefers casual tone.",\ "INSTRUCTION: Never mention her ex-boyfriend.",\ ]) # Retrieve the peer card card = peer.get_card() print(card) # ["Name: Alice. Also known as 'Ali'.", "College student at MIT...", ...] [​](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#directional-peer-cards) Directional Peer Cards -------------------------------------------------------------------------------------------------------------------------- Peer cards follow the same observer-observed model as [representations](https://docs.honcho.dev/v3/documentation/features/advanced/representation-scopes) . When `observe_others` is enabled, a peer can have a **different** card for each peer it observes. For example, if Alice and Bob are in a session together and Alice has `observe_others: true`, Alice will build her own peer card for Bob—separate from Honcho’s peer card for Bob. You can read and write these directional cards using the `target` parameter. Python TypeScript alice = honcho.peer("alice") # Get Alice's own peer card (Honcho's view of Alice) alice_card = alice.get_card() # Get Alice's card for Bob (Alice's view of Bob) alice_bob_card = alice.get_card(target="bob") # Set Alice's card for Bob alice.set_card( ["Bob mentioned he's allergic to peanuts."], target="bob" ) [​](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#where-peer-cards-are-used) Where Peer Cards Are Used -------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#in-the-dialectic-chat-endpoint) In the Dialectic (Chat Endpoint) When you call [`peer.chat()`](https://docs.honcho.dev/v3/documentation/features/chat) , Honcho automatically injects the relevant peer cards into the system prompt. The dialectic agent sees both the observer’s own card and the observed peer’s card, giving it immediate grounding without needing to search memory. ### [​](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#in-context-retrieval) In Context Retrieval The [`session.context()`](https://docs.honcho.dev/v3/documentation/features/get-context) method includes the peer card when you specify a `peer_target`: Python TypeScript context = session.context( tokens=2000, peer_target="user-123" ) # Access the peer card alongside the representation print(context.peer_card) # List of peer card facts print(context.peer_representation) # Full representation text ### [​](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#during-dreaming) During Dreaming The [dreaming](https://docs.honcho.dev/v3/documentation/features/advanced/dreaming) process reads the current peer card before consolidation, then updates it with any new stable facts discovered during the deduction and induction phases. [​](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#limits) Limits ------------------------------------------------------------------------------------------ | Constraint | Value | | --- | --- | | Maximum facts per card | **40** | | Data type | `list[str]` (each fact is a string) | When the dreaming process or a manual update pushes the card beyond 40 facts, it is automatically truncated to the first 40 entries. Keep facts concise and deduplicated to stay within the limit. If you manually set a peer card, it **replaces** the entire card—it does not merge with existing facts. Make sure to include all facts you want to keep when calling `set_card()`. [​](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#configuration) Configuration -------------------------------------------------------------------------------------------------------- Peer card behavior is controlled through the [configuration hierarchy](https://docs.honcho.dev/v3/documentation/features/advanced/reasoning-configuration) . You can independently toggle whether agents **use** existing peer cards and whether they **create/update** them. Python TypeScript # Disable peer card updates but still use existing cards during reasoning session = honcho.session("my-session", config={ "peer_card": {"create": False, "use": True} }) # Disable peer cards entirely session = honcho.session("no-cards", config={ "peer_card": {"create": False, "use": False} }) | Field | Type | Default | Description | | --- | --- | --- | --- | | `use` | `bool` | `true` | Whether agents read the peer card during reasoning and chat | | `create` | `bool` | `true` | Whether agents can create or update peer cards | Configuration can be set at the workspace, session, or message level. See [Reasoning Configuration](https://docs.honcho.dev/v3/documentation/features/advanced/reasoning-configuration) for the full hierarchy. [​](https://docs.honcho.dev/v3/documentation/features/advanced/peer-card#best-practices) Best Practices ---------------------------------------------------------------------------------------------------------- 1. **Bootstrap with known facts.** If you already know the user’s name or preferences at signup, set the peer card immediately. This gives the agent grounding from the very first interaction instead of waiting for dreaming to discover it. 2. **Use structured prefixes.** Prefixing facts with `INSTRUCTION:`, `PREFERENCE:`, or `TRAIT:` makes it easier for the agent to distinguish categories and act on them appropriately. 3. **Keep facts atomic.** Each string should contain one fact. Avoid combining multiple pieces of information into a single entry—`"Name: Alice"` and `"Location: Portland"` are better than `"Alice lives in Portland and works at Acme"`. 4. **Let dreaming handle updates.** For most applications, you don’t need to manually manage the peer card after bootstrapping. The dreaming process will discover and record new facts as conversations progress. 5. **Use `set_card` for corrections.** If the automatic system has recorded something incorrect, manually set the card with the corrected facts. Remember this replaces the entire card. Representations --------------- Understand the full representation system that peer cards complement Dreaming -------- Learn how dreaming automatically populates peer cards Configuration ------------- Configure peer card behavior at workspace, session, or message level Get Peer Card API ----------------- API reference for retrieving peer cards [Summarizer](https://docs.honcho.dev/v3/documentation/features/advanced/summarizer) [Representation Scopes](https://docs.honcho.dev/v3/documentation/features/advanced/representation-scopes) ⌘I --- # Get Sessions - Honcho [Skip to main content](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-sessions#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v1.1.0 Search... ⌘K Search... Navigation sessions Get Sessions [Documentation](https://docs.honcho.dev/v1/getting-started/introduction) [Spellbooks and Tutorials](https://docs.honcho.dev/v1/guides/overview) [API Reference](https://docs.honcho.dev/v1/api-reference/introduction) JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { // Automatically fetches more pages as needed. for await (const session of client.apps.users.sessions.list('app_id', 'user_id')) { console.log(session.id); } } main(); 200 422 { "items": [\ {\ "id": "",\ "is_active": true,\ "user_id": "",\ "app_id": "",\ "created_at": "2023-11-07T05:31:56Z",\ "metadata": {}\ }\ ], "total": 1, "page": 2, "size": 2, "pages": 1 } POST http://localhost:8000https://demo.honcho.devhttps://api.honcho.dev / v1 / apps / {app\_id} / users / {user\_id} / sessions / list Try it JavaScript JavaScript import Honcho from 'honcho-ai'; const client = new Honcho({ apiKey: process.env['HONCHO_API_KEY'], // This is the default and can be omitted }); async function main() { // Automatically fetches more pages as needed. for await (const session of client.apps.users.sessions.list('app_id', 'user_id')) { console.log(session.id); } } main(); 200 422 { "items": [\ {\ "id": "",\ "is_active": true,\ "user_id": "",\ "app_id": "",\ "created_at": "2023-11-07T05:31:56Z",\ "metadata": {}\ }\ ], "total": 1, "page": 2, "size": 2, "pages": 1 } #### Authorizations [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-sessions#authorization-authorization) Authorization string header required Bearer authentication header of the form `Bearer `, where `` is your auth token. #### Path Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-sessions#parameter-app-id) app\_id string required ID of the app [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-sessions#parameter-user-id) user\_id string required ID of the user #### Query Parameters [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-sessions#parameter-one-of-0) reverse boolean | null default:false Whether to reverse the order of results [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-sessions#parameter-page) page integer default:1 Page number Required range: `x >= 1` [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-sessions#parameter-size) size integer default:50 Page size Required range: `1 <= x <= 100` #### Body application/json Filtering and pagination options for the sessions list [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-sessions#body-one-of-0-filter-one-of-0) filter Filter · object [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-sessions#body-one-of-0-is-active) is\_active boolean default:false #### Response 200 application/json Successful Response [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-sessions#response-items) items Session · object\[\] required Show child attributes [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-sessions#response-total) total integer required Required range: `x >= 0` [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-sessions#response-page) page integer required Required range: `x >= 1` [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-sessions#response-size) size integer required Required range: `x >= 1` [​](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/get-sessions#response-pages) pages integer Required range: `x >= 0` [Get Or Create App](https://docs.honcho.dev/v1/api-reference/endpoint/apps/get-or-create-app) [Create Session](https://docs.honcho.dev/v1/api-reference/endpoint/sessions/create-session) ⌘I --- # CrewAI - Honcho [Skip to main content](https://docs.honcho.dev/v3/guides/integrations/crewai#content-area) [Honcho home page![light logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-dark.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=5ea9abc83421c35574fc8baf38d67172)![dark logo](https://mintcdn.com/plasticlabs/Tnh_xfGaSgXYiKRy/logo/honcho-light.svg?fit=max&auto=format&n=Tnh_xfGaSgXYiKRy&q=85&s=44f6093c094ec1438eddfa6d6cf6412a)](https://docs.honcho.dev/) v3.0.5 Search... ⌘K Search... Navigation Integrations CrewAI [Documentation](https://docs.honcho.dev/v3/documentation/introduction/overview) [Guides](https://docs.honcho.dev/v3/guides/overview) [Open Source](https://docs.honcho.dev/v3/contributing/self-hosting) [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) [Changelog](https://docs.honcho.dev/changelog/introduction) On this page * [What We’re Building](https://docs.honcho.dev/v3/guides/integrations/crewai#what-we%E2%80%99re-building) * [Setup](https://docs.honcho.dev/v3/guides/integrations/crewai#setup) * [CrewAI Honcho Storage](https://docs.honcho.dev/v3/guides/integrations/crewai#crewai-honcho-storage) * [Search with Filters](https://docs.honcho.dev/v3/guides/integrations/crewai#search-with-filters) * [CrewAI Tool Integration](https://docs.honcho.dev/v3/guides/integrations/crewai#crewai-tool-integration) * [Tool-Based vs Automatic Memory](https://docs.honcho.dev/v3/guides/integrations/crewai#tool-based-vs-automatic-memory) * [Next Steps](https://docs.honcho.dev/v3/guides/integrations/crewai#next-steps) * [Related Resources](https://docs.honcho.dev/v3/guides/integrations/crewai#related-resources) Integrate Honcho with CrewAI to build AI agents that maintain memory across sessions. This guide shows you how to use Honcho’s memory layer with CrewAI’s agent orchestration framework. The full code is available on [GitHub](https://github.com/plastic-labs/honcho/tree/main/examples/crewai) with examples in [Python](https://github.com/plastic-labs/honcho/tree/main/examples/crewai/python/examples) [​](https://docs.honcho.dev/v3/guides/integrations/crewai#what-we%E2%80%99re-building) What We’re Building ------------------------------------------------------------------------------------------------------------- We’ll create AI agents that remember and reason over past conversations. Here’s how the pieces fit together: * **CrewAI** orchestrates agent behavior and task execution * **Honcho** stores messages and retrieves relevant context The key benefit: CrewAI automatically retrieves relevant conversation history from Honcho without you needing to manually manage context, token limits, or message formatting. This tutorial demonstrates single-agent setup to show how Honcho integrates with CrewAI. For production applications, you can extend this to multi-agent crews with shared or individual memory using Honcho’s `peer` system. [​](https://docs.honcho.dev/v3/guides/integrations/crewai#setup) Setup ------------------------------------------------------------------------- Install required packages: Python (uv) Python (pip) uv add honcho-crewai crewai python-dotenv Use any LLM provider for your Crew. Create a `.env` file with your API keys: OPENAI_API_KEY=your_openai_key This tutorial uses the Honcho demo server at [https://demo.honcho.dev](https://demo.honcho.dev/) which runs a small instance of Honcho on the latest version. For production, get your Honcho API key at [app.honcho.dev](https://app.honcho.dev/) . For local development, use `environment="local"`. [​](https://docs.honcho.dev/v3/guides/integrations/crewai#crewai-honcho-storage) CrewAI Honcho Storage --------------------------------------------------------------------------------------------------------- The `honcho_crewai` package provides `HonchoStorage`, a storage provider that implements CrewAI’s `Storage` interface using Honcho’s session-based memory. Before proceeding, it’s important to understand Honcho’s core concepts (`Peers` and `Sessions`). Review the [Honcho Architecture](https://docs.honcho.dev/v3/documentation/core-concepts/architecture) to familiarize yourself with these primitives. `HonchoStorage` implements CrewAI’s `Storage` interface using Honcho’s `peer` and `session` primitives. storage = HonchoStorage( user_id="demo-user", # Required: Honcho `peer` ID for the user session_id=None, # Optional: Specific `session` ID (auto-generated UUID if None) honcho_client=None, # Optional: Pre-configured Honcho client instance ) The `HonchoStorage` class implements three key methods: * **`save()`** - Stores messages in Honcho’s `session`, associating them with the appropriate `peer` (user or assistant) * **`search()`** - Performs semantic vector search using `session.search()` to find messages most relevant to the query. Supports optional `filters` parameter for fine-grained scoping. * **`reset()`** - Creates a new `session` to start fresh conversations CrewAI automatically calls these methods when agents need to store or retrieve memory, creating a seamless integration. ### [​](https://docs.honcho.dev/v3/guides/integrations/crewai#search-with-filters) Search with Filters The `search()` method supports an optional `filters` parameter for fine-grained scoping of search results: # Search with peer_id filter (only messages from a specific peer) results = storage.search("query", filters={"peer_id": "user123"}) # Search with metadata filter results = storage.search("query", filters={"metadata": {"priority": "high"}}) # Search with time range filter results = storage.search("query", filters={"created_at": {"gte": "2024-01-01"}}) # Complex filter with logical operators results = storage.search("query", filters={ "AND": [\ {"peer_id": "user123"},\ {"metadata": {"topic": "python"}}\ ] }) For the full filter syntax including logical operators (AND, OR, NOT), comparison operators, and metadata filtering, see the [Using Filters](https://docs.honcho.dev/v3/documentation/features/advanced/using-filters) documentation. For comprehensive details about CrewAI’s memory system, see the [official CrewAI Memory documentation](https://docs.crewai.com/en/concepts/memory) . Let’s create a basic example showing how CrewAI agents use Honcho’s memory automatically: Python from dotenv import load_dotenv from crewai import Agent, Task, Crew, Process from crewai.memory.external.external_memory import ExternalMemory from honcho_crewai import HonchoStorage load_dotenv() storage = HonchoStorage(user_id="simple-demo-user") external_memory = ExternalMemory(storage=storage) messages = [\ ("user", "I'm learning Python programming"),\ ("assistant", "Great! Python is an excellent language to learn."),\ ("user", "I'm particularly interested in web development"),\ ] for role, message in messages: external_memory.save(message, metadata={"agent": role}) agent = Agent( role="Programming Mentor", goal="Help users learn programming by remembering their interests and progress", backstory=( "You are a patient programming mentor who remembers what students " "have told you about their learning journey and interests." ), verbose=True, allow_delegation=False ) task = Task( description=( "Based on what you know about the user's interests, " "suggest a simple web development project they could build to practice Python." ), expected_output="A specific project suggestion with brief explanation", agent=agent ) crew = Crew( agents=[agent], tasks=[task], process=Process.sequential, external_memory=external_memory, verbose=True ) result = crew.kickoff() print(result.raw) [​](https://docs.honcho.dev/v3/guides/integrations/crewai#crewai-tool-integration) CrewAI Tool Integration ------------------------------------------------------------------------------------------------------------- Honcho provides specialized tools that give CrewAI agents explicit control over memory retrieval: * **`HonchoGetContextTool`** - Retrieves comprehensive conversation history with token limits. Use for tasks needing broad conversation understanding. * **`HonchoDialecticTool`** - Queries representations about `peer`s. Use for understanding user preferences and characteristics without full message history. * **`HonchoSearchTool`** - Performs semantic search for specific information. Supports optional `filters` parameter for fine-grained scoping. Use for targeted queries like “what did the user say about budget?” Agents can use multiple tools in sequence: search for topics, query dialectic for preferences, then get full context for generation. Here’s an example demonstrating all three tools: Python from dotenv import load_dotenv from crewai import Agent, Task, Crew, Process from honcho import Honcho from honcho_crewai import ( HonchoGetContextTool, HonchoDialecticTool, HonchoSearchTool, ) load_dotenv() honcho = Honcho() user_id = "demo-user-45" session_id = "tools-demo-session" user = honcho.peer(user_id) session = honcho.session(session_id) messages = [\ "I'm planning a trip to Japan in March",\ "I love trying authentic local cuisine, especially ramen and sushi",\ "My budget is around $3000 for a 10-day trip",\ "I'm interested in visiting both Tokyo and Kyoto",\ "I prefer staying in traditional ryokans over hotels",\ ] for msg in messages: session.add_messages([user.message(msg)]) context_tool = HonchoGetContextTool( honcho=honcho, session_id=session_id, peer_id=user_id ) dialectic_tool = HonchoDialecticTool( honcho=honcho, session_id=session_id, peer_id=user_id ) search_tool = HonchoSearchTool(honcho=honcho, session_id=session_id) # Note: The search tool supports optional filters for fine-grained scoping # Agents can use filters like {"peer_id": "user123"} or {"metadata": {"priority": "high"}} travel_agent = Agent( role="Travel Planning Specialist", goal="Create personalized travel recommendations using memory tools", backstory=( "You are an expert travel planner with access to conversation memory tools. " "Use the tools to understand the user's preferences before making recommendations." ), tools=[context_tool, dialectic_tool, search_tool], verbose=True, allow_delegation=False ) task = Task( description=( "Create a personalized 3-day Tokyo itinerary. " "Use the memory tools to understand:\n" " • Food preferences (use search_tool for 'cuisine' or 'food')\n" " • Travel style and budget (use dialectic_tool to query user knowledge)\n" " • Recent context (use context_tool to get conversation history)\n" "Then create a detailed plan matching their interests." ), expected_output=( "A 3-day Tokyo itinerary with:\n" " • Daily activities matching user interests\n" " • Restaurant recommendations\n" " • Accommodation suggestions\n" " • Budget considerations" ), agent=travel_agent ) crew = Crew( agents=[travel_agent], tasks=[task], process=Process.sequential, verbose=True ) crew.kickoff() [​](https://docs.honcho.dev/v3/guides/integrations/crewai#tool-based-vs-automatic-memory) Tool-Based vs Automatic Memory --------------------------------------------------------------------------------------------------------------------------- **Use `HonchoStorage`** for automatic memory - CrewAI handles everything transparently. Best for simple conversational flows. **Use Honcho Tools** for strategic control - agents decide when and how to query memory. Best for multi-step reasoning, when different query types are needed, or multi-agent systems. You can combine both: automatic memory for baseline context, tools for specific queries. See the [hybrid memory example](https://github.com/plastic-labs/honcho/blob/main/examples/crewai/python/examples/hybrid_memory_example.py) for a complete implementation. **Multi-Agent Memory:** Use Honcho tools with different `peer_id` values to give each agent distinct memory and identity. [​](https://docs.honcho.dev/v3/guides/integrations/crewai#next-steps) Next Steps ----------------------------------------------------------------------------------- Now that you have a working CrewAI integration with Honcho, you can: * **Create specialized agents** with domain-specific memory and context * **Use CrewAI’s advanced features** like hierarchical processes, tool delegation, and conditional task execution * **Leverage logical reasoning** via the Dialectic API for deep `peer` understanding * **Implement custom tools** to give agents explicit control over memory retrieval [​](https://docs.honcho.dev/v3/guides/integrations/crewai#related-resources) Related Resources ------------------------------------------------------------------------------------------------- Honcho Architecture ------------------- Understand Honcho’s peer-based model and core primitives Get Context ----------- Learn about retrieving and formatting conversation context Chat API -------- Query `peer` representations for deeper understanding LangGraph Integration --------------------- Build stateful agents with LangGraph and Honcho [Claude Code](https://docs.honcho.dev/v3/guides/integrations/claude-code) [LangGraph](https://docs.honcho.dev/v3/guides/integrations/langgraph) ⌘I ---