Nearly every developer in the AI space is now calling Hermes the standard foundation for next‑generation agents — memory engine, intelligent retrieval, enterprise readiness, code‑native core, and plugin ecosystem. This complete playbook leaves a clear generational gap.

Honcho https://github.com/plastic-labs/honcho… is the officially designated external memory backend, focusing on structured long‑term memory storage. In plain terms, it finally gives your agent a “brain.” Persistent memory in production is no longer a fantasy.

Hermes‑Web‑Search‑Plus https://github.com/robbyczgw-cla/hermes-web-search-plus… provides multi‑search‑engine intelligent routing + quality scoring + deep research mode. Search is finally starting to work intelligently, instead of dumping endless irrelevant links on you.

NemoClaw‑Community https://github.com/NVIDIA/nemoclaw-community… is the official community edition from NVIDIA, combining Hermes with NemoClaw’s enterprise‑grade extension scheme. With GPU‑level optimisation and deployment support, the direction is now crystal clear.

Hindsight https://github.com/hindsightai/hindsight… is a repository‑level persistent memory backend that gives agents a thorough understanding of the entire repo’s structure and details. This memory capability is essentially like having a shadow CTO — anyone who uses it knows exactly what they’re getting.

Hermes‑Plugins https://github.com/42-evey/hermes-plugins… brings together 23 plug‑and‑play, practical plugins covering goal decomposition, agent‑to‑agent bridging, and cost control. It’s like a self‑operating ops combat team.

plastic-labs/honcho

Source: https://github.com/plastic-labs/honcho

Static Badge PyPI version NPM version Discord

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 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
• Core Concepts
• Benchmarks & Evals
• Self-hosting
• Configuration
• Architecture
• SDKs
• Learn More
• Contributing
• License

The Honcho project is split between several repositories, with this one hosting the core service logic — implemented as a FastAPI server. Client SDKs for Python and TypeScript live in the sdks/ directory.

Start Here

Why Honcho

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 self‑host and run against 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

See the full SDK Reference and API Reference.

Integrations

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.

OpenCode

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

Details: OpenCode guide.

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.

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

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.

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

Peers exchange messages within sessions; Honcho reasons over those messages to build a representation of each peer that you can query.

• 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.
• Message: an atomic data unit (peer‑to‑peer communication or ingested document chunk).

What you query out of Honcho:

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

Internal storage (Collections & Documents)

Internally, Honcho stores peer‑related observations in collections of vector‑embedded documents. Collections are keyed by (observer, observed) peer pairs — the same mechanism powers self‑representation (observer == observed) and cross‑peer modelling (peer X’s understanding of peer Y). These primitives are not exposed directly; the Conclusions API is the public surface.

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. You can run the full server locally with Docker, then point the SDKs at http://localhost:8000.

Quick start (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

Local development without Docker

Below is a guide on setting up a local environment for running the Honcho Server without Docker.

Prerequisites and Dependencies

Honcho is developed using python and uv. The minimum python version is 3.10. The minimum uv version is 0.5.0.

Setup

Once the dependencies are installed on the system run the following steps to get the local project setup.

1. Clone the repository

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

2. Enter the repository and install the python dependencies

   We recommend using a virtual environment to isolate the dependencies for Honcho from other projects on the same system. uv will create a virtual environment when you sync your dependencies in the project.

   cd honcho
   uv sync
   

   This will create a virtual environment and install the dependencies for Honcho. The default virtual environment will be located at honcho/.venv. Activate the virtual environment via:

   source honcho/.venv/bin/activate
   

3. Set up a database

   Honcho utilizes Postgres for its database with pgvector. An easy way to get started with a postgres database is to create a project with Supabase.

   Alternatively, a docker-compose template is available with a sample database configuration. To use Docker:

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

4. Edit the environment variables

   Honcho uses a .env file for managing runtime environment variables. A .env.template file is included for convenience. Several of the configurations are not required and are only necessary for additional logging, monitoring, and security. Below are the required configurations:

   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)
   

   Note that the DB_CONNECTION_URI must have the prefix postgresql+psycopg to function properly. This is a requirement brought by sqlalchemy.

   The template has the additional functionality disabled by default. To ensure that they are disabled you can verify the following environment variables are set to false:

   AUTH_USE_AUTH=false
   SENTRY_ENABLED=false
   

   If you set AUTH_USE_AUTH to true you will need to generate a JWT secret. You can do this with the following command:

   python scripts/generate_jwt_secret.py
   

   This will generate a JWT secret and print it to the console. You can then set the AUTH_JWT_SECRET environment variable. This is required for AUTH_USE_AUTH:

   AUTH_JWT_SECRET=
   

   Once auth is enabled, use scripts/generate_jwt.py to mint tokens for local development and scripting:

   # 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 $TOK