plastic-labs/honcho

Honcho – Memory infrastructure for stateful AI agents

What it is

• Honcho is an open‑source service (FastAPI server) that stores and reasons over messages, events, and documents for AI agents and humans (called peers). It builds up per‑peer representations that can be queried as natural‑language answers, summaries, or vector‑search results. The service can be used as a managed cloud offering (api.honcho.dev) or self‑hosted via Docker or a local CLI.

Key concepts

Concept	Role
Workspace	Top‑level container that isolates data for a product or team.
Peer	Any participant – a human user or an AI agent – that can send and receive messages.
Session	A conversation (or event stream) involving one or more peers.
Scope	Named grouping of sessions that limits recall for searches or representations.
Message	Atomic unit of data (chat turn, tool call, document chunk).

How it works – the Honcho Loop

1. Store – Add peers, sessions and messages via the SDK or HTTP API.
2. Reason – Honcho processes the queued items in the background, extracting conclusions and updating each peer’s representation.
3. Query – Retrieve context, search results, peer representations, or direct natural‑language answers.
4. Inject – Feed the returned data into any LLM call or agent framework.

Main capabilities

• Reasoning‑first memory – Not just a vector store; Honcho runs background reasoning to produce conclusions about peers.
• Peer‑centric model – Tracks what each peer knows about every other peer (observer/observed pairs).
• Hybrid search – Combines BM25 keyword search with vector similarity.
• Low‑latency static representations – Snapshots of a peer’s knowledge that can be fetched quickly.
• Prompt‑ready context – Summaries or full conversation histories formatted for OpenAI, Anthropic, etc.
• Multi‑agent support – Sessions can contain any mix of humans and AI agents.

Getting started

• Managed – Sign up at https://app.honcho.dev, obtain an API key, and start using the Python (honcho-ai) or TypeScript (@honcho-ai/sdk) SDKs.
• Local – Install the CLI (uv tool install honcho-cli), run honcho start --setup, and point the SDKs at http://localhost:8000.
• Self‑host from source – Clone the repo, copy the Docker compose example, provide LLM provider keys, and run docker compose up.

Example (Python)

from honcho import Honcho
import os

honcho = Honcho(
    workspace_id="my-app-testing",
    api_key=os.getenv("HONCHO_API_KEY"),
)

alice = honcho.peer("alice")
tutor = honcho.peer("tutor")
session = honcho.session("session-1")
session.add_messages([
    alice.message("Hey, can you help me with my math homework?"),
    tutor.message("Sure, send the first problem!"),
])

# Background reasoning runs automatically.
answer = alice.chat("What learning styles does the user respond to best?")
context = session.context(summary=True, tokens=10_000)

# Use the context with any LLM, e.g. OpenAI:
from openai import OpenAI
client = OpenAI()
client.chat.completions.create(
    model="gpt-4o-mini",
    messages=context.to_openai(assistant=tutor),
)

Integrations – First‑party plugins exist for many coding agents (Claude Code, Codex, Cursor, DeepSeek Harness, OpenCode, Kilo Code, OpenClaw, Hermes) and any MCP‑compatible client. All plugins read a shared ~/.honcho/config.json so a single API key can power multiple tools.

CLI – honcho-cli lets you inspect a deployment (honcho workspace inspect, honcho doctor), run a local stack, and manage configuration.

Benchmarks – Honcho reports results on long‑conversation benchmarks such as LongMemEval and LoCoMo, with a research blog post and public evals page describing its Pareto‑frontier performance.

License – AGPL‑3.0 (open source, can be self‑hosted).

---

Bottom line – Honcho provides a purpose‑built memory layer for agents that need to retain and reason over interactions over time. It abstracts away storage, background reasoning, and representation retrieval, letting developers focus on building agents, bots, or products that remember users and other agents across sessions.