{
"markdown": "\n\n\n\n---\n\n\n[](https://pypi.org/project/honcho-ai/)\n[](https://npmjs.org/package/@honcho-ai/sdk)\n[](https://pypi.org/project/honcho-cli/)\n[](https://discord.gg/honcho)\n\n**Honcho is memory infrastructure for building stateful agents that understand changing people, agents, groups, projects, and ideas over time.**\n\nStore messages and events, let Honcho reason in the background, then query peer representations, session context, search results, or natural-language insights from any model or framework. Use it managed at [api.honcho.dev](https://api.honcho.dev), run a local stack with [`honcho start`](#cli), or self-host the FastAPI server yourself.\n\nUsing Honcho as your memory system will earn your agents higher retention, more trust, and help you build data moats to out-compete incumbents.\n\n> 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://honcho.dev/evals/), and read the [blog post](https://blog.plasticlabs.ai/research/Benchmarking-Honcho) for more detail.\n\n## Contents\n\n- [Start Here](#start-here)\n- [Why Honcho](#why-honcho)\n- [The Honcho Loop](#the-honcho-loop)\n- [Quickstart](#quickstart)\n- [What Honcho Gives You](#what-honcho-gives-you)\n- [Integrations](#integrations)\n- [CLI](#cli)\n- [Core Concepts](#core-concepts)\n- [Benchmarks & Evals](#benchmarks--evals)\n- [Self-hosting](#self-hosting)\n- [Configuration](#configuration)\n- [Architecture](#architecture)\n- [SDKs](#sdks)\n- [Learn More](#learn-more)\n- [Contributing](#contributing)\n- [License](#license)\n\nThe Honcho project is split between several repositories, with this one hosting the core service logic — implemented as a FastAPI server. Client SDKs for Python and TypeScript live in the [`sdks/`](./sdks) directory. The [`honcho-cli`](./honcho-cli) package lives here too.\n\n## Start Here\n\n| I want to... | Path | Get started |\n| -------------------------------------- | ---------------------------------------------------------- | ----------------------------- |\n| Give my coding agent persistent memory | Claude Code, OpenCode, OpenClaw, Hermes, or any MCP client | [Integrations](#integrations) |\n| Add memory to my product | Python or TypeScript SDK | [Quickstart](#quickstart) |\n| Run Honcho locally | Install CLI, then `honcho start --setup` | [CLI](#cli) |\n| Inspect a deployment | `honcho workspace inspect`, `honcho doctor` | [CLI](#cli) |\n| Self-host from source | Docker Compose or local development | [Self-hosting](#self-hosting) |\n\n## Why Honcho\n\n| Capability | What it means |\n| ----------------------- | ------------------------------------------------------------------------------------ |\n| Reasoning-first memory | Extracts conclusions from conversations and events, not just matching chunks. |\n| Peer-centric model | Tracks users, agents, groups, projects, and ideas as entities that change over time. |\n| Multi-peer perspective | Models what one peer knows about another when configured. |\n| Managed or self-hosted | Use `api.honcho.dev`, `honcho start` locally, or run the FastAPI server yourself. |\n| Agent-tool integrations | MCP, Claude Code, OpenCode, OpenClaw, Hermes, Cursor-compatible clients. |\n\n## The Honcho Loop\n\n1. **Store** conversations, events, documents, or tool traces as messages on a session.\n2. **Reason** — Honcho processes the queue in the background and updates peer representations.\n3. **Query** — ask Honcho for context, search results, peer representations, or a natural-language answer.\n4. **Inject** — drop the result into any LLM call or agent framework.\n\nConcretely: workspaces hold peers, peers participate in sessions, messages live on sessions, and Honcho builds a per-peer representation that you query through the [Chat Endpoint](https://honcho.dev/docs/v3/documentation/features/chat) or directly.\n\n## Quickstart\n\nGet an API key at [app.honcho.dev](https://app.honcho.dev) — when you sign up you'll be prompted to join an organization, which gets its own dedicated Honcho instance and $100 free credits. Or install the CLI and run [`honcho start --setup`](#cli), then point the SDK at `http://localhost:8000`.\n\n### Python\n\n```bash\npip install honcho-ai\n# or: uv add honcho-ai\n# or: poetry add honcho-ai\n```\n\n```python\nimport os\nfrom honcho import Honcho\n\n# Managed service uses api.honcho.dev by default. For self-hosted, pass\n# base_url=\"http://localhost:8000\" or set HONCHO_URL.\nhoncho = Honcho(\n workspace_id=\"my-app-testing\",\n api_key=os.environ[\"HONCHO_API_KEY\"],\n)\n\n# 1. Store: peers and messages on a session\nalice = honcho.peer(\"alice\")\ntutor = honcho.peer(\"tutor\")\nsession = honcho.session(\"session-1\")\nsession.add_messages([\n alice.message(\"Hey there — can you help me with my math homework?\"),\n tutor.message(\"Absolutely. Send me your first problem!\"),\n])\n\n# 2. Reason: happens asynchronously in the background.\n\n# 3. Query: ask Honcho what it knows, or pull prompt-ready context.\nanswer = alice.chat(\"What learning styles does the user respond to best?\")\ncontext = session.context(summary=True, tokens=10_000)\n\n# 4. Inject: hand the context to your model of choice.\nfrom openai import OpenAI\nclient = OpenAI()\ncompletion = client.chat.completions.create(\n model=os.environ.get(\"OPENAI_MODEL\", \"gpt-4o-mini\"),\n messages=context.to_openai(assistant=tutor),\n)\n```\n\n### TypeScript\n\n```bash\nnpm install @honcho-ai/sdk\n# or: bun add @honcho-ai/sdk\n```\n\n```typescript\nimport { Honcho } from \"@honcho-ai/sdk\";\nimport OpenAI from \"openai\";\n\nconst honcho = new Honcho({\n workspaceId: \"my-app-testing\",\n apiKey: process.env.HONCHO_API_KEY,\n});\n\nconst alice = await honcho.peer(\"alice\");\nconst tutor = await honcho.peer(\"tutor\");\nconst session = await honcho.session(\"session-1\");\nawait session.addMessages([\n alice.message(\"Hey there — can you help me with my math homework?\"),\n tutor.message(\"Absolutely. Send me your first problem!\"),\n]);\n\nconst answer = await alice.chat(\n \"What learning styles does the user respond to best?\",\n);\nconst context = await session.context({ summary: true, tokens: 10_000 });\n\nconst openai = new OpenAI();\nconst completion = await openai.chat.completions.create({\n model: process.env.OPENAI_MODEL ?? \"gpt-4o-mini\",\n messages: context.toOpenAI({ assistant: tutor }),\n});\n```\n\n> **Note:** background reasoning is asynchronous. Newly-added messages may take a moment to be reflected in chat/representation responses; for low-latency reads, use the [`representation`](https://honcho.dev/docs/v3/documentation/features/representation) endpoint.\n\n## What Honcho Gives You\n\n| Need | API |\n| ---------------------------------- | --------------------------------------------------------------- |\n| Save interaction history | `session.add_messages(...)` |\n| Ask what Honcho knows about a peer | `peer.chat(...)` |\n| Get prompt-ready context | `session.context(...).to_openai(...)` / `.to_anthropic(...)` |\n| Hybrid search (BM25 + vector) | `peer.search(...)`, `session.search(...)`, `honcho.search(...)` |\n| Low-latency static representations | `peer.representation(...)`, `session.representation(...)` |\n| Import documents | `session.upload_file(...)` |\n| Inspect background processing | `honcho.queue_status(...)` |\n\nSee the full [SDK Reference](https://honcho.dev/docs/v3/documentation/reference/sdk) and [API Reference](https://honcho.dev/docs/v3/api-reference/introduction).\n\n## Integrations\n\nHoncho ships a first-party memory plugin for every major coding agent. They all read the same\n`~/.honcho/config.json`, so one key configures all of them — and pointing two at the same `workspace`\ngives them one shared memory.\n\n| Agent | Install | Source |\n| ---------------- | ------------------------------------------------------- | ------------------------------------------------------------------ |\n| Claude Code | `/plugin marketplace add plastic-labs/claude-honcho` | [claude-honcho](https://github.com/plastic-labs/claude-honcho) |\n| Codex | `npm install -g @honcho-ai/codex-honcho` | [codex-honcho](https://github.com/plastic-labs/codex-honcho) |\n| Cursor | `curl -fsSL .../cursor-honcho/main/install.sh \\| bash` | [cursor-honcho](https://github.com/plastic-labs/cursor-honcho) |\n| DeepSeek Harness | `dsh plugin --profile add @honcho-ai/dsh-honcho` | [dsh-honcho](https://github.com/plastic-labs/dsh-honcho) |\n| OpenCode | `opencode plugin \"@honcho-ai/opencode-honcho\" --global` | [opencode-honcho](https://github.com/plastic-labs/opencode-honcho) |\n| OpenClaw | `openclaw plugins install @honcho-ai/openclaw-honcho` | [openclaw-honcho](https://github.com/plastic-labs/openclaw-honcho) |\n| Hermes | `hermes memory setup` | built in upstream |\n| Any MCP client | `claude mcp add honcho --transport http ...` | [MCP guide](https://honcho.dev/docs/v3/guides/integrations/mcp) |\n\nGet a key at [app.honcho.dev](https://app.honcho.dev), then `honcho init` (or `uv tool install honcho-cli && honcho init`) writes it to `~/.honcho/config.json` once for every integration.\n\n### Claude Code\n\nTwo ways, depending on how deep you want to go:\n\n**Plugin (richer integration — recommended for Claude Code users):**\n\n```text\n/plugin marketplace add plastic-labs/claude-honcho\n/plugin install honcho@honcho\n```\n\n**Raw MCP (works in any MCP client — Cursor, Cline, Windsurf, etc.):**\n\n```bash\nclaude mcp add honcho \\\n --transport http \\\n --url \"https://mcp.honcho.dev\" \\\n --header \"Authorization: Bearer hch-your-key-here\" \\\n --header \"X-Honcho-User-Name: YourName\"\n```\n\nDetails: [Claude Code guide](https://honcho.dev/docs/v3/guides/integrations/claude-code) · [MCP guide](https://honcho.dev/docs/v3/guides/integrations/mcp) · [repo](https://github.com/plastic-labs/claude-honcho).\n\n### Codex\n\n```bash\nnpm install -g @honcho-ai/codex-honcho\ncodex-honcho install # registers hooks + MCP + skill in ~/.codex\n```\n\nRestart Codex to load the hooks. Details: [Codex guide](https://honcho.dev/docs/v3/guides/integrations/codex) · [repo](https://github.com/plastic-labs/codex-honcho).\n\n### Cursor\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/plastic-labs/cursor-honcho/main/install.sh | bash\n```\n\nWindows (PowerShell): `irm https://raw.githubusercontent.com/plastic-labs/cursor-honcho/main/install.ps1 | iex`. The installer wires global hooks and MCP config. Details: [cursor-honcho](https://github.com/plastic-labs/cursor-honcho).\n\n### DeepSeek Harness\n\n```bash\ndsh plugin --profile add @honcho-ai/dsh-honcho\n```\n\nA native Cordis plugin. It injects memory into the system prompt and captures new information from the session event feed. The model gets three tools — honcho_search, honcho_chat, and honcho_remember — and you can run /honcho to check status.\nDetails: [DeepSeek Harness guide](https://honcho.dev/docs/v3/guides/integrations/deepseek-harness) · [repo](https://github.com/plastic-labs/dsh-honcho).\n\n### OpenCode\n\n```bash\nopencode plugin \"@honcho-ai/opencode-honcho\" --global\n```\n\nDetails: [OpenCode guide](https://honcho.dev/docs/v3/guides/integrations/opencode) · [repo](https://github.com/plastic-labs/opencode-honcho).\n\n### OpenClaw\n\n```bash\nopenclaw plugins install @honcho-ai/openclaw-honcho\nopenclaw honcho setup\nopenclaw gateway --force\n```\n\n`openclaw honcho setup` prompts for your API key, writes the config, and optionally migrates legacy `MEMORY.md` / `USER.md` / `IDENTITY.md` files into Honcho (non-destructive — originals are never deleted). Details: [OpenClaw guide](https://honcho.dev/docs/v3/guides/integrations/openclaw) · [repo](https://github.com/plastic-labs/openclaw-honcho).\n\n### Hermes\n\n```bash\nhermes memory setup # select \"honcho\", point at api.honcho.dev or your local server\n```\n\nDetails: [Hermes guide](https://honcho.dev/docs/v3/guides/integrations/hermes).\n\n### Add Honcho to your own codebase (agent skill)\n\nFor wiring the Honcho SDK into an existing application, install the integration skill — it explores your codebase, asks about integration preferences, generates the SDK setup, and verifies it works:\n\n```bash\nnpx skills add plastic-labs/honcho\n```\n\nThen invoke `/honcho-integration` in Claude Code (or `/honcho-dev:integrate` via the plugin marketplace). The same command also installs the memory skills — `honcho-memory` (concepts: the recall/record loop, session and peer strategy, plus how to connect and drive an MCP-connected Honcho) and `honcho-cli` (inspecting a deployment, or running a local stack with `honcho start`). Details: [agentic development guide](https://honcho.dev/docs/v3/documentation/introduction/vibecoding).\n\n### Other MCP clients\n\nThe same `claude mcp add` form (or its client-specific equivalent) works in any MCP-compatible client. See [MCP guide](https://honcho.dev/docs/v3/guides/integrations/mcp).\n\n## CLI\n\n[`honcho-cli`](https://pypi.org/project/honcho-cli/) inspects a Honcho deployment from the terminal, or runs a personal local stack with Docker.\n\n```bash\nuv tool install honcho-cli\nhoncho init # Honcho API key or browser login + server URL\nhoncho start --setup basic # local stack: LLM provider key + Docker\nhoncho doctor\n```\n\n`honcho init` authenticates the CLI against a Honcho server. `honcho start --setup` is a separate step: it writes the LLM provider key the local deriver needs and starts API + deriver + Postgres + Redis.\n\nFull commands and local-stack details: [CLI reference](https://honcho.dev/docs/v3/documentation/reference/cli) · [`honcho-cli/README.md`](./honcho-cli/README.md). To develop the server from source, see [Self-hosting](#self-hosting).\n\n## Core Concepts\n\nHoncho organises everything around **peers** — humans and AI agents alike are first-class entities. The peer model enables:\n\n- Multi-participant sessions with mixed human and AI agents\n- Configurable observation settings (which peers observe which others)\n- Flexible identity management for all participants\n- Support for complex multi-agent interactions\n\nPeers exchange messages within sessions; Honcho reasons over those messages to build a representation of each peer that you can query.\n\n- **Workspace** (formerly App): top-level container; isolates data between use cases.\n- **Peer** (formerly User): any participant — human user or AI agent.\n- **Session**: a conversation context; many-to-many with peers.\n- **Scope**: a named grouping of sessions that bounds recall (chat, representation, search) to those members.\n- **Message**: an atomic data unit (peer-to-peer communication or ingested document chunk).\n\nWhat you query out of Honcho:\n\n- **Conclusions** — what Honcho has extracted about a peer (deductive and inductive). Exposed via the [conclusions API](https://honcho.dev/docs/v3/api-reference/introduction).\n- **Representations** — static, low-latency snapshots of what Honcho knows about a peer (optionally session-scoped).\n- **Peer Cards** — compact identity summaries.\n- **Session context / summaries** — prompt-ready bundles for long-running conversations.\n\n\n\nInternal storage (Collections & Documents)
\n\nInternally, Honcho stores peer-related observations in **collections** of vector-embedded **documents**. Collections are keyed by `(observer, observed)` peer pairs — the same mechanism powers self-representation (`observer == observed`) and cross-peer modelling (peer X's understanding of peer Y). These primitives are not exposed directly; the Conclusions API is the public surface.\n\n \n\n\n\n\n## Benchmarks & Evals\n\nHoncho's evals span LongMemEval, LoCoMo, and other long-conversation benchmarks. See the [evals page](https://honcho.dev/evals/), the [research blog post](https://blog.plasticlabs.ai/research/Benchmarking-Honcho), and the [Pareto-frontier announcement video](https://x.com/honchodotdev/status/2002090546521911703?s=20) for methodology and reproducible results.\n\n## Self-hosting\n\nHoncho is open source under AGPL-3.0. To **run** a personal instance, install the CLI (`uv tool install honcho-cli`) and then [`honcho start --setup`](#cli). The paths below are for building from source, contributing, or deploying without the CLI.\n\n### Quick start (from source, Docker)\n\n```bash\ngit clone https://github.com/plastic-labs/honcho.git\ncd honcho\ncp docker-compose.yml.example docker-compose.yml\ncp .env.template .env # fill in LLM_GEMINI_API_KEY / LLM_ANTHROPIC_API_KEY / LLM_OPENAI_API_KEY\ndocker compose up\n```\n\nThen point the SDKs at it:\n\n```python\nhoncho = Honcho(workspace_id=\"my-app-testing\", base_url=\"http://localhost:8000\")\n# or: export HONCHO_URL=http://localhost:8000\n```\n\n\n\nLocal development without Docker
\n\nBelow is a guide on setting up a local environment for running the Honcho Server without Docker.\n\n#### Prerequisites and Dependencies\n\nHoncho is developed using [python](https://www.python.org/) and [uv](https://docs.astral.sh/uv/).\n\nThe minimum python version is `3.10`\nThe minimum uv version is `0.5.0`\n\n#### Setup\n\nOnce the dependencies are installed on the system run the following steps to get\nthe local project setup.\n\n1. **Clone the repository**\n\n```bash\ngit clone https://github.com/plastic-labs/honcho.git\n```\n\n2. **Enter the repository and install the python dependencies**\n\nWe recommend using a virtual environment to isolate the dependencies for Honcho\nfrom other projects on the same system. `uv` will create a virtual environment\nwhen you sync your dependencies in the project.\n\n```bash\ncd honcho\nuv sync\n```\n\nThis will create a virtual environment and install the dependencies for Honcho.\nThe default virtual environment will be located at `honcho/.venv`. Activate the\nvirtual environment via:\n\n```bash\nsource honcho/.venv/bin/activate\n```\n\n3. **Set up a database**\n\nHoncho utilizes [Postgres](https://www.postgresql.org/) for its database with\npgvector. An easy way to get started with a postgres database is to create a project\nwith [Supabase](https://supabase.com/)\n\nAlternatively, a `docker-compose` template is available with a sample database configuration.\nTo use Docker:\n\n```bash\ncp docker-compose.yml.example docker-compose.yml\ndocker compose up -d database\n```\n\n4. **Edit the environment variables**\n\nHoncho uses a `.env` file for managing runtime environment variables. A\n`.env.template` file is included for convenience. Several of the configurations\nare not required and are only necessary for additional logging, monitoring, and\nsecurity.\n\nBelow are the required configurations:\n\n```env\nDB_CONNECTION_URI= # Connection uri for a postgres database (with postgresql+psycopg prefix)\n\n# LLM Provider API Keys\nLLM_GEMINI_API_KEY= # API Key for Google Gemini (used for deriver, summary, and dialectic minimal/low by default)\nLLM_ANTHROPIC_API_KEY= # API Key for Anthropic (used for dialectic medium/high/max and dream by default)\nLLM_OPENAI_API_KEY= # API Key for OpenAI (used for embeddings when EMBED_MESSAGES=true)\n```\n\n> Note that the `DB_CONNECTION_URI` must have the prefix `postgresql+psycopg` to\n> function properly. This is a requirement brought by `sqlalchemy`\n\nThe template has the additional functionality disabled by default. To ensure\nthat they are disabled you can verify the following environment variables are\nset to false:\n\n```env\nAUTH_USE_AUTH=false\nSENTRY_ENABLED=false\n```\n\nIf you set `AUTH_USE_AUTH` to true you will need to generate a JWT secret. You can\ndo this with the following command:\n\n```bash\npython scripts/generate_jwt_secret.py\n```\n\nThis will generate a JWT secret and print it to the console. You can then set\nthe `AUTH_JWT_SECRET` environment variable. This is required for `AUTH_USE_AUTH`:\n\n```env\nAUTH_JWT_SECRET=\n```\n\nOnce auth is enabled, use `scripts/generate_jwt.py` to mint tokens for local\ndevelopment and scripting:\n\n```bash\n# Admin token (full access, no expiry)\nuv run python scripts/generate_jwt.py --admin\n\n# Admin token expiring in 24 hours\nuv run python scripts/generate_jwt.py --admin --expires 24h\n\n# Workspace-scoped token\nuv run python scripts/generate_jwt.py --workspace my-workspace --expires 30d\n\n# Capture a token for use in curl/scripts\nTOKEN=$(uv run python scripts/generate_jwt.py --admin --print-only)\ncurl -H \"Authorization: Bearer $TOKEN\" http://localhost:8000/v3/workspaces\n```\n\nDuration units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days), `w` (weeks), `y` (years).\n\n5. **Run database migrations**\n\nWith the database set up and environment variables configured, run the migrations\nto create the necessary tables:\n\n```bash\nuv run alembic upgrade head\n```\n\nThis will create all tables for Honcho including workspaces, peers, sessions,\nmessages, and the queue system.\n\n6. **Launch Honcho**\n\nWith everything set up, you can now launch a local instance of Honcho. In addition to the database, two\ncomponents need to be running:\n\n**Start the API server:**\n\n```bash\nuv run fastapi dev src/main.py\n```\n\nThis is a development server that will reload whenever code is changed.\n\n**Start a background worker (deriver):**\n\nIn a separate terminal, run:\n\n```bash\nuv run python -m src.deriver\n```\n\nThe deriver generates representations, summaries, peer cards, and manages dreaming tasks. You can increase the number of derivers to improve runtime efficiency.\n\n \n\n\nContributors: see [`CONTRIBUTING.md`](./CONTRIBUTING.md) for pre-commit setup. Deploying to Fly.io: see [Self-hosting docs → Deploying on Fly.io](https://honcho.dev/docs/v3/contributing/self-hosting#deploying-on-fly-io).\n\n## Configuration\n\nHoncho uses a flexible configuration system that supports both TOML files and environment variables. Configuration values are loaded in priority order: **environment variables > `.env` file > `config.toml` > defaults**.\n\nCopy the example file to get started:\n\n```bash\ncp config.toml.example config.toml\n```\n\nThe file is organized by subsystem — `[app]`, `[db]`, `[auth]`, `[cache]`, `[llm]`, `[deriver]`, `[dialectic]`, `[summary]`, `[dream]`, `[peer_card]`, `[webhook]`, `[metrics]`, `[telemetry]`, `[vector_store]`, and `[sentry]`. Any value can be overridden by an environment variable named `{SECTION}_{KEY}`, using `__` for nesting (`DIALECTIC_LEVELS__low__MODEL_CONFIG__MODEL`), or just `{KEY}` for app-level settings.\n\nSee the [configuration reference](https://honcho.dev/docs/v3/contributing/configuration) for every available option, and [`.env.template`](./.env.template) for an annotated list of environment variables.\n\n## Architecture\n\nHoncho splits into two services: **Storage** (workspaces, peers, sessions, scopes, messages, internal collections) and **Insights** (reasoning, conclusions, representations, summaries, the chat endpoint). Storage is synchronous via the API; Insights is asynchronous via a background queue consumed by the deriver worker process.\n\n**Key features:**\n\n- **Rich Reasoning System** — multiple implementation methods that extract conclusions from interactions and build comprehensive representations of peers\n- **Chat Endpoint** — reasoning-informed responses that integrate conclusions with current context\n- **Background Processing** — asynchronous processing pipeline for expensive operations like representation updates and session summarization\n- **Multi-Provider Support** — configurable LLM providers for different use cases\n\n\n\nStorage primitives in detail
\n\nHoncho contains several different primitives used for storing application and\npeer data. This data is used for managing conversations, modeling peer\nidentity, building RAG applications, and more.\n\nThe philosophy behind Honcho is to provide a platform that is peer-centric and\neasily scalable from a single user to a million.\n\nBelow is a mapping of the different primitives and their relationships.\n\n```\nWorkspaces\n├── Peers ←──────────────────┐\n│ ├── Sessions │\n│ └── (internal collections, keyed by observer/observed peer pair)\n│ │\n├── Scopes ←─────────────────┤ (many-to-many with sessions)\n│ │\n└── Sessions ←───────────────┤ (many-to-many with peers)\n ├── Peers ───────────────┘\n └── Messages (session-level)\n```\n\n**Relationship Details:**\n\n- A **Workspace** contains multiple **Peers** and **Scopes**.\n- **Peers** and **Sessions** have a many-to-many relationship (peers can participate in multiple sessions, sessions can have multiple peers).\n- **Scopes** and **Sessions** have a many-to-many relationship (a session can belong to several scopes; a scope groups many sessions).\n- **Messages** belong to a session and are labelled by their source peer.\n- **Internal collections** of vector-embedded **documents** are keyed by `(observer, observed)` peer pairs. They are not directly exposed via the API; the observations stored in them are exposed as **Conclusions**.\n\nUsers familiar with APIs such as the OpenAI Assistants API will be familiar with\nmuch of the mapping here.\n\n#### Workspaces\n\nThis is the top level construct of Honcho. Developers can register different\n`Workspaces` for different assistants, agents, AI enabled features, etc. It is a way to\nisolate data between use cases and provide multi-tenant capabilities.\n\n#### Peers\n\nWithin a `Workspace` everything revolves around a `Peer`. The `Peer` object\nrepresents any participant in the system — whether human users or AI agents.\nThis unified model enables complex multi-participant interactions.\n\n#### Sessions\n\nThe `Session` object represents a set of interactions between `Peers` within a\n`Workspace`. Other applications may refer to this as a thread or conversation.\nSessions can involve multiple peers with configurable observation settings.\nA session can optionally join one or more **Scopes** at creation, or later via\nthe scopes API.\n\n#### Scopes\n\nA `Scope` is a named grouping of sessions inside a `Workspace`. It is a\nvisibility boundary on recall: chat, representation, session context, and\nworkspace search answered through a scope see only what happened in that\nscope's member sessions. The underlying peers keep their unified\nrepresentations across everything they have participated in.\n\nDevelopers manage scopes through the scopes API (`honcho.scope(...)` /\n`honcho.scopes()`) and an optional `scopes` field on session create — not\nthrough observer/observed configuration. Adding a session that already has\nmessages copies its existing explicit conclusions into the scope (no\nre-derivation); removing one reconciles those copies back out. Query\nbackfill progress with the scope `status` endpoint.\n\nA single scope name answers from that scope's collection and card. A list of\nscopes restricts recall to the union of their member sessions. Empty scopes\nfail closed. `scope` is mutually exclusive with `session` / `filters` on the\nsame read.\n\n#### Messages\n\nThe `Message` represents an atomic data unit that exists at the session level:\ncommunication between peers within a session context. All messages are labelled\nby their source peer and can be processed asynchronously to update their\nrepresentations. This flexible design allows for both conversational interactions\nand broader data ingestion for personality modelling.\n\n \n\n\n\n\nReasoning pipeline
\n\nThe reasoning functionality of Honcho is built on top of the Storage service. As\n`Messages` and `Sessions` are created for `Peers`, Honcho will asynchronously\nreason about peer psychology to derive facts about them and store them\nin reserved internal collections.\n\nA high level summary of the pipeline is as follows:\n\n1. Messages are created via the API.\n2. Derivation tasks are enqueued for background processing, including:\n - `representation`: update representations of `Peers`.\n - `summary`: create summaries of `Sessions`.\n3. Session-based queue processing ensures proper ordering.\n4. Results are stored internally and surfaced via the Conclusions API, Representations, Peer Cards, and the Chat Endpoint.\n\n \n\n\n\n\nRetrieving data and insights
\n\nHoncho exposes several different ways to retrieve data from the system to best\nserve the needs of any given application.\n\n#### Get Context\n\nIn long-running conversations with an LLM, the context window can fill up\nquickly. To address this, Honcho provides a `context`\nendpoint that returns a combination of messages, conclusions, summaries from a\nsession up to a provided token limit.\n\nUse this to keep sessions going indefinitely. If you'd like to see this in action, try out [Honcho Chat](https://honcho.chat).\n\n#### Search\n\nThere are several search endpoints that let developers query messages at the\n`Workspace`, `Session`, or `Peer` level using a hybrid search strategy.\n\nRequests can include advanced filters to further refine\nthe results.\n\n#### Chat API\n\nThe flagship interface for using these insights is the [Chat Endpoint](https://honcho.dev/docs/v3/documentation/features/chat) (`POST /peers/{peer_id}/chat`). It takes natural-language requests to get data about a peer and returns reasoning-grounded responses. Examples:\n\n- Asking Honcho for a generic or specific insight about the peer.\n- Asking Honcho to hydrate a prompt with data about the peer's behaviour.\n- Asking Honcho for a second opinion on how to respond.\n- Getting personalised responses that incorporate long-term facts and context.\n\n#### Representations\n\nFor low-latency use cases, Honcho provides access to a `representation` endpoint that returns a static document with insights about a peer in the context of a particular session. Use this to quickly add context to a prompt without having to wait for an LLM response.\n\n \n\n\n## SDKs\n\n- **Python** — [`honcho-ai`](https://pypi.org/project/honcho-ai/) on PyPI · source in [`sdks/python/`](./sdks/python)\n- **TypeScript** — [`@honcho-ai/sdk`](https://www.npmjs.com/package/@honcho-ai/sdk) on npm · source in [`sdks/typescript/`](./sdks/typescript)\n- **CLI** — [`honcho-cli`](https://pypi.org/project/honcho-cli/) on PyPI · source in [`honcho-cli/`](./honcho-cli) · [CLI reference](https://honcho.dev/docs/v3/documentation/reference/cli)\n\nSDKs are versioned independently of the server. Current SDK versions track each other; the server badge above reflects the deployed server version.\n\nSee the [SDK Reference](https://honcho.dev/docs/v3/documentation/reference/sdk) for full API surface, the [API Reference](https://honcho.dev/docs/v3/api-reference/introduction) for the raw HTTP API, and per-SDK example folders for runnable demos.\n\n## Learn More\n\n- [Developer documentation](https://honcho.dev/docs/) — full API surface, guides, integrations.\n- [CLI reference](https://honcho.dev/docs/v3/documentation/reference/cli) — local stack, inspect/debug commands, scripting.\n- [Plastic Labs blog](https://blog.plasticlabs.ai/) — design philosophy and history of the project.\n\n## Contributing\n\nWe welcome contributions to Honcho. One thing to know before you start: **pull requests must be linked to an issue carrying the `maintainer-approved` label**, or they are closed automatically. [Browse the approved queue](https://github.com/plastic-labs/honcho/issues?q=is%3Aissue+is%3Aopen+label%3Amaintainer-approved), or make your case in [Discord](http://discord.gg/honcho) — that is where maintainers are most active.\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for the full process, an architecture walkthrough, and a map of where to change what. For vulnerabilities, see [SECURITY.md](./SECURITY.md) — note that Honcho does not operate a bug bounty.\n\n## License\n\nHoncho is licensed under the AGPL-3.0 License. Learn more at the [License file](./LICENSE).\n",
"bytes": 33679,
"sha": "5b2c7c5b05731f3139bb183720e4f383ff02ed6be838d5926537b026f8d3a77c",
"repo_slug": "plastic-labs/honcho",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_plastic_labs_honcho_c96d322d/readme"
}![\"Honcho\"](\"assets/honcho.svg\")
\n \n