Honcho Memory Infrastructure
Persistent memory infrastructure that stores interactions, derives insights asynchronously, and returns usable context for stateful agents.
Per-dimension scores and reasoning
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.
- 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.
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.