Honcho Memory Infrastructure
Persistent memory infrastructure that stores interactions, derives insights asynchronously, and returns usable context for stateful agents.
- Source repo
- plastic-labs/honcho
- Stars
- ★ 8k
- Last updated
- today
- License
- AGPL-3.0
- Primary language
- Python
- FA score
- 44/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformClaude Code · OpenAI API · Claude API
- Cost
- Free tier plus a paid hosted plan
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A tutoring product using OpenAI Chat Completions can retain student and tutor interactions, then inject session.context(...) into a later completion.
- Not a fit if
- Apps needing synchronous reads of just-added messages
- Closed-source products unwilling to accept AGPL-3.0 obligations
- Solo users who want no database or background worker
- Source review
- 44/100 · Major gaps 2 safety controls not found
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.
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.
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 does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Honcho Memory Infrastructure This agent | 44 · Major gaps | Library / SDKFreemium | ★ 8k | today | Python | Claude Code · OpenAI API · Claude API |
| Deuz SDK | 69 · Some gaps | Library / SDKFree + model costs | ★ 508 | 20d ago | TypeScript | OpenAI API · Claude API |
| Hindsight | 46 · Major gaps | Self-hosted serviceFreemium | ★ 59k | today | Python | OpenAI API · Claude API |
| Composio | 51 · Major gaps | Library / SDKFree + model costs | ★ 31k | today | TypeScript | Claude Code · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README describes configurable auth (AUTH_USE_AUTH) and JWT secret generation, indicating permission control, but least privilege is not explicit; user confirmation: no user confirmation or consent mechanism found; data flow transparency: README describes storage and reasoning flow, but not data flow to users; sensitive data handling: mentions API keys and JWT secrets, but no encryption or redaction; dependency security: pyproject.toml lists dependencies, but no security audit or vulnerability scanning; external effects: describes interactions with external LLM providers, but side effects not explicit; rollback: no rollback mechanism mentioned; source attribution: author info clear, but publisher unverified. Deductions: missing user confirmation, rollback, insufficient evidence for sensitive data handling and dependency security.
Evidence shows: README and pyproject.toml descriptions consistent, version numbers consistent (3.0.11), dependency list complete; dependency availability: all dependencies listed, but no lock file or integrity checks; failure messages: no explicit error handling or user-friendly error messages found. Deduction: insufficient evidence for failure messages.
Evidence shows: README identifies target audience (developers, product teams) and multiple use cases (Claude Code, OpenCode, etc.); capability boundaries: describes separation of storage and reasoning, but no explicit limits; trigger precision: no explicit triggers or events; environment fit: supports Docker, local development, multiple LLM providers. Deduction: insufficient evidence for trigger precision.
Evidence shows: README well-structured with TOC and detailed sections; install notes detailed including Docker and local dev; naming stability: version numbers present but no naming conventions; examples and FAQ: quickstart and integration examples, but no FAQ; known limitations: not explicitly listed; license: AGPL-3.0, clear; versioning changelog: no CHANGELOG provided; maintenance responsibility: contributing guide present, but maintainers not explicit. Deductions: missing FAQ, known limitations, CHANGELOG, maintenance responsibility unclear.
Evidence shows: output usability: multiple query interfaces and SDKs, output formats clear; marginal value: provides memory infrastructure with unique value; cost benefit: no performance or cost data. Deduction: insufficient evidence for cost benefit.
Evidence shows: README references external resources (evals page, blog), but no specific data; cross-source corroboration: multiple integration examples, but not independently verified; fact/inference separation: README distinguishes descriptions and marketing claims, but not explicitly labeled. Deductions: external references lack specific data, cross-verification insufficient.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Publisher identity unverified; exercise caution regarding supply chain risks.
- Lack of user confirmation and rollback mechanisms may affect reversibility of data operations.
- Dependency security not explicit; recommend checking for dependency vulnerabilities.
- Marketing claims in README (e.g., Pareto Frontier) lack verifiable data.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Added - The workspace session list can report and filter by scope membership. ?include_scopes=true gives each session a scopes list of the scopes it is in ([] for none), fetched in one query per page; without it the response is unchanged. Body scope lists only that scope's sessions (404 if the scope doesn't exist) and in_no_scope: true lists only sessions in no scope; both combine with filters and pagination, and total counts the filtered result. Clients no longer need to list every scope's members to show which scopes a session is in (#1477) …View on GitHub ↗ -
Release notes excerpt
Security - The Docker image ships certifi 2026.10.19, up from 2026.4.22, so outbound TLS from the API and the deriver (LLM providers, embeddings, webhooks) verifies against the current CA bundle. The build's uv moves from 0.9.24 to 0.13.5. Self-hosted deployments that install from uv.lock need uv 0.13.5 or newer: older uv ignores the lockfile's per-package exclude-newer override for certifi and resolves an older bundle (#1439) Fixed …View on GitHub ↗ -
Release notes excerpt
Added - Workspace, peer and session responses carry uid, the immutable identifier Honcho assigns (the row's internal id). id is unchanged and stays the client-chosen name, so clients can start storing uid as a reference that won't move if names become renameable. Every route that returns these objects includes it: get-or-create, list, update, clone, session peers, peer sessions and scope sessions. Additive, no migration (#1394) …View on GitHub ↗