plastic-labs/honcho

---

Honcho is memory infrastructure for building stateful agents that understand changing people, agents, groups, projects, and ideas over time.

Store 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, run a local stack with honcho start, or self-host the FastAPI server yourself.

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, check out our evals page, and read the blog post for more detail.

Contents

• Start Here
• Why Honcho
• The Honcho Loop
• Quickstart
• What Honcho Gives You
• Integrations
• CLI
• Core Concepts
• Benchmarks & Evals
• Self-hosting
• Configuration
• Architecture
• SDKs
• Learn More
• Contributing
• License

Start Here

| I want to... | Path | Get started | | -------------------------------------- | ---------------------------------------------------------- | ----------------------------- | | Give my coding agent persistent memory | Claude Code, OpenCode, OpenClaw, Hermes, or any MCP client | Integrations | | Add memory to my product | Python or TypeScript SDK | Quickstart | | Run Honcho locally | Install CLI, then honcho start --setup | CLI | | Inspect a deployment | honcho workspace inspect, honcho doctor | CLI | | Self-host from source | Docker Compose or local development | Self-hosting |

Why Honcho

| Capability | What it means | | ----------------------- | ------------------------------------------------------------------------------------ | | Reasoning-first memory | Extracts conclusions from conversations and events, not just matching chunks. | | Peer-centric model | Tracks users, agents, groups, projects, and ideas as entities that change over time. | | Multi-peer perspective | Models what one peer knows about another when configured. | | Managed or self-hosted | Use api.honcho.dev, honcho start locally, or run the FastAPI server yourself. | | Agent-tool integrations | MCP, Claude Code, OpenCode, OpenClaw, Hermes, Cursor-compatible clients. |

The Honcho Loop

1. Store conversations, events, documents, or tool traces as messages on a session. 2. Reason — Honcho processes the queue in the background and updates peer representations. 3. Query — ask Honcho for context, search results, peer representations, or a natural-language answer. 4. Inject — drop the result into any LLM call or agent framework.

Concretely: 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 or directly.

Quickstart

Get an API key at 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, then point the SDK at http://localhost:8000.

Python

pip install honcho-ai
or: uv add honcho-ai
or: poetry add honcho-ai

import os
from honcho import Honcho
Managed service uses api.honcho.dev by default. For self-hosted, pass
base_url="http://localhost:8000" or set HONCHO_URL.
honcho = Honcho(
    workspace_id="my-app-testing",
    api_key=os.environ["HONCHO_API_KEY"],
)
1. Store: peers and messages on a session
alice = honcho.peer("alice")
tutor = honcho.peer("tutor")
session = honcho.session("session-1")
session.add_messages([
    alice.message("Hey there — can you help me with my math homework?"),
    tutor.message("Absolutely. Send me your first problem!"),
])
2. Reason: happens asynchronously in the background.
3. Query: ask Honcho what it knows, or pull prompt-ready context.
answer = alice.chat("What learning styles does the user respond to best?")
context = session.context(summary=True, tokens=10_000)
4. Inject: hand the context to your model of choice.
from openai import OpenAI
client = OpenAI()
completion = client.chat.completions.create(
    model=os.environ.get("OPENAI_MODEL", "gpt-4o-mini"),
    messages=context.to_openai(assistant=tutor),
)

TypeScript

npm install @honcho-ai/sdk
or: bun add @honcho-ai/sdk

import { Honcho } from "@honcho-ai/sdk";
import OpenAI from "openai";
const honcho = new Honcho({
  workspaceId: "my-app-testing",
  apiKey: process.env.HONCHO_API_KEY,
});
const alice = await honcho.peer("alice");
const tutor = await honcho.peer("tutor");
const session = await honcho.session("session-1");
await session.addMessages([
  alice.message("Hey there — can you help me with my math homework?"),
  tutor.message("Absolutely. Send me your first problem!"),
]);
const answer = await alice.chat(
  "What learning styles does the user respond to best?",
);
const context = await session.context({ summary: true, tokens: 10_000 });
const openai = new OpenAI();
const completion = await openai.chat.completions.create({
  model: process.env.OPENAI_MODEL ?? "gpt-4o-mini",
  messages: context.toOpenAI({ assistant: tutor }),
});

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 endpoint.

What Honcho Gives You

| Need | API | | ---------------------------------- | --------------------------------------------------------------- | | Save interaction history | session.add_messages(...) | | Ask what Honcho knows about a peer | peer.chat(...) | | Ask across the whole workspace | honcho.chat(...) / honcho.chat_stream(...) | | Get prompt-ready context | session.context(...).to_openai(...) / .to_anthropic(...) | | Hybrid search (BM25 + vector) | peer.search(...), session.search(...), honcho.search(...) | | Low-latency static representations | peer.representation(...), session.representation(...) | | Import documents | session.upload_file(...) | | Inspect background processing | honcho.queue_status(...) |

See the full SDK Reference and API Reference.

Integrations

Honcho ships a first-party memory plugin for every major coding agent. They all read the same ~/.honcho/config.json, so one key configures all of them — and pointing two at the same workspace gives them one shared memory.

| Agent | Install | Source | | ---------------- | ------------------------------------------------------- | ------------------------------------------------------------------ | | Claude Code | /plugin marketplace add plastic-labs/claude-honcho | claude-honcho | | Codex | npm install -g @honcho-ai/codex-honcho | codex-honcho | | Cursor | curl -fsSL .../cursor-honcho/main/install.sh \| bash | cursor-honcho | | DeepSeek Harness | dsh plugin --profile add @honcho-ai/dsh-honcho | dsh-honcho | | OpenCode | opencode plugin "@honcho-ai/opencode-honcho" --global | opencode-honcho | | OpenClaw | openclaw plugins install @honcho-ai/openclaw-honcho | openclaw-honcho | | Hermes | hermes memory setup | built in upstream | | Any MCP client | claude mcp add honcho --transport http ... | MCP guide |

Get a key at app.honcho.dev, then honcho init (or uv tool install honcho-cli && honcho init) writes it to ~/.honcho/config.json once for every integration.

Claude Code

Two ways, depending on how deep you want to go:

Plugin (richer integration — recommended for Claude Code users):

/plugin marketplace add plastic-labs/claude-honcho
/plugin install honcho@honcho

Raw MCP (works in any MCP client — Cursor, Cline, Windsurf, etc.):

claude mcp add honcho \
  --transport http \
  --url "https://mcp.honcho.dev" \
  --header "Authorization: Bearer hch-your-key-here" \
  --header "X-Honcho-User-Name: YourName"

Details: Claude Code guide · MCP guide · repo.

Codex

npm install -g @honcho-ai/codex-honcho
codex-honcho install      # registers hooks + MCP + skill in ~/.codex

Restart Codex to load the hooks. Details: Codex guide · repo.

Cursor

curl -fsSL https://raw.githubusercontent.com/plastic-labs/cursor-honcho/main/install.sh | bash

Windows (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.

DeepSeek Harness

dsh plugin --profile  add @honcho-ai/dsh-honcho

A 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. Details: DeepSeek Harness guide · repo.

OpenCode

opencode plugin "@honcho-ai/opencode-honcho" --global

Details: OpenCode guide · repo.

OpenClaw

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 migrates legacy MEMORY.md / USER.md / IDENTITY.md files into Honcho (non-destructive — originals are never deleted). Details: OpenClaw guide · repo.

Hermes

hermes memory setup   # select "honcho", point at api.honcho.dev or your local server

Details: Hermes guide.

Add Honcho to your own codebase (agent skill)

For 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:

npx skills add plastic-labs/honcho

Then 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.

Other MCP clients

The same claude mcp add form (or its client-specific equivalent) works in any MCP-compatible client. See MCP guide.

CLI

honcho-cli inspects a Honcho deployment from the terminal, or runs a personal local stack with Docker.

uv tool install honcho-cli
honcho init                 # Honcho API key or browser login + server URL
honcho start --setup basic  # local stack: LLM provider key + Docker
honcho doctor

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.

Full commands and local-stack details: CLI reference · honcho-cli/README.md. To develop the server from source, see Self-hosting.

Core Concepts

Honcho organises everything around peers — humans and AI agents alike are first-class entities. The peer model enables:

• Multi-participant sessions with mixed human and AI agents
• Configurable observation settings (which peers observe which others)
• Flexible identity management for all participants
• Support for complex multi-agent interactions

• Workspace (formerly App): top-level container; isolates data between use cases.
• Peer (formerly User): any participant — human user or AI agent.
• Session: a conversation context; many-to-many with peers.
• Scope: a named grouping of sessions that bounds recall (chat, representation, search) to those members.
• Message: an atomic data unit (peer-to-peer communication or ingested document chunk).

• Conclusions — what Honcho has extracted about a peer (deductive and inductive). Exposed via the conclusions API.
• Representations — static, low-latency snapshots of what Honcho knows about a peer (optionally session-scoped).
• Peer Cards — compact identity summaries.
• Session context / summaries — prompt-ready bundles for long-running conversations.

Benchmarks & Evals

Honcho's evals span LongMemEval, LoCoMo, and other long-conversation benchmarks. See the evals page, the research blog post, and the Pareto-frontier announcement video for methodology and reproducible results.

Self-hosting

Honcho 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. The paths below are for building from source, contributing, or deploying without the CLI.

Quick start (from source, Docker)

git clone https://github.com/plastic-labs/honcho.git
cd honcho
cp docker-compose.yml.example docker-compose.yml
cp .env.template .env       # fill in LLM_GEMINI_API_KEY / LLM_ANTHROPIC_API_KEY / LLM_OPENAI_API_KEY
docker compose up

Then point the SDKs at it:

honcho = Honcho(workspace_id="my-app-testing", base_url="http://localhost:8000")
or: export HONCHO_URL=http://localhost:8000

git clone https://github.com/plastic-labs/honcho.git

cd honcho
uv sync

source honcho/.venv/bin/activate

cp docker-compose.yml.example docker-compose.yml
docker compose up -d database

DB_CONNECTION_URI= # Connection uri for a postgres database (with postgresql+psycopg prefix)
LLM Provider API Keys
LLM_GEMINI_API_KEY= # API Key for Google Gemini (used for deriver, summary, and dialectic minimal/low by default)
LLM_ANTHROPIC_API_KEY= # API Key for Anthropic (used for dialectic medium/high/max and dream by default)
LLM_OPENAI_API_KEY= # API Key for OpenAI (used for embeddings when EMBED_MESSAGES=true)

AUTH_USE_AUTH=false
SENTRY_ENABLED=false

python scripts/generate_jwt_secret.py

AUTH_JWT_SECRET=<generated_secret>

# Admin token (full access, no expiry)
uv run python scripts/generate_jwt.py --admin
Admin token expiring in 24 hours
uv run python scripts/generate_jwt.py --admin --expires 24h
Workspace-scoped token
uv run python scripts/generate_jwt.py --workspace my-workspace --expires 30d
Capture a token for use in curl/scripts
TOKEN=$(uv run python scripts/generate_jwt.py --admin --print-only)
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/v3/workspaces

uv run alembic upgrade head

uv run fastapi dev src/main.py

uv run python -m src.deriver

Contributors: see CONTRIBUTING.md for pre-commit setup. Deploying to Fly.io: see Self-hosting docs → Deploying on Fly.io.

Configuration

Honcho 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.

Copy the example file to get started:

cp config.toml.example config.toml

The file is organized by subsystem — [app], [db], [auth], [cache], [llm], [deriver], [dialectic], [summary], [dream], [peer_card], [webhook], [metrics], [telemetry],