Honcho Memory Infrastructure
Persistent memory infrastructure that stores interactions, derives insights asynchronously, and returns usable context for stateful agents.
What does this agent do, and when should you use it?
Honcho is memory infrastructure for stateful agents, built around a FastAPI core service with Python and TypeScript SDKs. Its data model uses workspaces, peers, sessions, and messages, with humans and AI agents represented through the same peer abstraction. After messages are stored, a background deriver process produces representations, session summaries, Peer Cards, and conclusions. Applications retrieve those outputs through chat, representation, context, and search interfaces, then can inject the results into their own model calls. It is available as the managed api.honcho.dev service or as a self-hosted server, and it supplies memory capabilities rather than an autonomous agent runtime.
An application creates or retrieves peers and sessions through the SDK, then uses session.add_messages(...) to store conversations, events, documents, or tool traces. Honcho enqueues session-ordered background work; the deriver processes representation and summary tasks, with results surfaced through the Conclusions API, Peer Cards, representations, and POST /peers/{peer_id}/chat. A caller can use peer.chat(...) for reasoning-grounded natural-language responses, session.context(summary=True, tokens=10_000) for prompt-ready context, and peer.search(...), session.search(...), or honcho.search(...) for BM25-plus-vector hybrid search. session.upload_file(...) imports documents, while honcho.queue_status(...) reports background-processing status.
- A tutoring product using OpenAI Chat Completions can retain student and tutor interactions, then inject session.context(...) into a later completion.
- A Claude Code user can add persistent memory across coding sessions through the documented plugin or HTTP MCP setup.
- A multi-participant application can record human and AI peer messages in one session and model what one peer observes about another.
- A latency-sensitive application can call peer.representation(...) or session.representation(...) to add a static memory snapshot to a prompt.
- A product investigating past interactions can run filtered hybrid search at peer, session, or workspace scope.
- A team needing deployment control can self-host the service with PostgreSQL and pgvector while isolating data by workspace.
What are this agent's strengths and limitations?
- Uses one peer model for humans and AI agents, including observer/observed peer-pair storage for cross-peer perspectives.
- Separates synchronous storage from an asynchronous insights pipeline that can produce representations, summaries, conclusions, and Peer Cards.
- Offers multiple retrieval modes: Chat Endpoint, low-latency representations, prompt-ready context, and hybrid BM25-plus-vector search.
- Ships Python and TypeScript SDKs plus HTTP MCP connectivity, with documented integrations for Claude Code, OpenCode, OpenClaw, and Hermes.
- Supports both a managed API and self-hosting with FastAPI, PostgreSQL/pgvector, and Docker.
- Reasoning is asynchronous, so recently added messages may not immediately appear in chat or representation responses.
- Self-hosting requires both the API service and a deriver worker, as well as database configuration and LLM provider keys.
- Local development depends on Python 3.10+, uv 0.5.0+, PostgreSQL, and pgvector, adding operational work compared with a client-only service.
- The repository is licensed under AGPL-3.0, so adopters need to assess license implications for their deployment and distribution model.
- The supplied material does not provide full managed-service pricing; it only states that a new organization receives $100 in free credits.
How do you install or deploy this agent?
For the managed service, obtain HONCHO_API_KEY from app.honcho.dev, then run pip install honcho-ai or npm install @honcho-ai/sdk. A minimal Python client is: from honcho import Honcho; honcho = Honcho(workspace_id="my-app-testing", api_key=os.environ["HONCHO_API_KEY"]). For self-hosting, run git clone https://github.com/plastic-labs/honcho.git && cd honcho && cp docker-compose.yml.example docker-compose.yml && cp .env.template .env; configure DB_CONNECTION_URI plus LLM_GEMINI_API_KEY, LLM_ANTHROPIC_API_KEY, and LLM_OPENAI_API_KEY in .env, then run docker compose up. Local development without Docker requires Python 3.10+, uv 0.5.0+, and PostgreSQL with pgvector; run uv sync, uv run alembic upgrade head, uv run fastapi dev src/main.py, and uv run python -m src.deriver in a separate terminal.
How do you use this agent?
Create a client for a workspace, then obtain peers and a session with alice = honcho.peer("alice"), tutor = honcho.peer("tutor"), and session = honcho.session("session-1"). Store interactions with session.add_messages([alice.message("..."), tutor.message("...")]). Once asynchronous processing has run, query an insight with alice.chat("What learning styles does the user respond to best?") or retrieve context with session.context(summary=True, tokens=10_000); the latter can be passed to OpenAI with context.to_openai(assistant=tutor) or converted for Anthropic. For a local server, set base_url="http://localhost:8000" or HONCHO_URL.