diff --git a/README.md b/README.md index 9a7cf541..69733738 100644 --- a/README.md +++ b/README.md @@ -8,164 +8,251 @@ --- -![Static Badge](https://img.shields.io/badge/Version-3.0.6-blue) +![Static Badge](https://img.shields.io/badge/Server-3.0.6-blue) [![PyPI version](https://img.shields.io/pypi/v/honcho-ai.svg)](https://pypi.org/project/honcho-ai/) [![NPM version](https://img.shields.io/npm/v/@honcho-ai/sdk.svg)](https://npmjs.org/package/@honcho-ai/sdk) [![Discord](https://img.shields.io/discord/1016845111637839922?style=flat&logo=discord&logoColor=23ffffff&label=Plastic%20Labs&labelColor=235865F2)](https://discord.gg/honcho) -Honcho is an open source memory library with a managed service for building stateful -agents. Use it with any model, framework, or architecture. It enables agents to build -and maintain state about any entity--users, agents, groups, ideas, and more. And because -it's a continual learning system, it understands entities that change over time. 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 is memory infrastructure for agents that need to 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](https://api.honcho.dev) or self-host the FastAPI server yourself. > Honcho has defined the Pareto Frontier of Agent Memory. Watch the [video](https://x.com/honchodotdev/status/2002090546521911703?s=20), check out our [evals page](https://evals.honcho.dev/), and read the [blog post](https://blog.plasticlabs.ai/research/Benchmarking-Honcho) for more detail. -## TL;DR - Getting Started +## Start Here -With Honcho you can easily setup your application's workflow, save your -interaction history, and leverage the reasoning it does to inform the behavior of -your agents +| I want to... | Path | Get started | +|---|---|---| +| Give my coding agent persistent memory | Claude Code, OpenCode, OpenClaw, Hermes, or any MCP client | [Integrations](#integrations) | +| Add memory to my product | Python or TypeScript SDK | [Quickstart](#quickstart) | +| Self-host Honcho | Docker / local development | [Self-hosting](#self-hosting) | -> Typescript examples are available in our [docs](https://docs.honcho.dev). +## The Honcho Loop -1. Install the SDK +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](https://docs.honcho.dev/v3/documentation/features/chat) or directly. + +## Quickstart + +Get an API key at [app.honcho.dev](https://app.honcho.dev) (managed service, $100 free credits) or [self-host](#self-hosting) and run against `http://localhost:8000`. + +### Python ```bash -# Python pip install honcho-ai -uv add honcho-ai -poetry add honcho-ai +# or: uv add honcho-ai +# or: poetry add honcho-ai ``` -2. Setup your `Workspace`, `Peers`, `Session`, and send `Messages` - ```python +import os from honcho import Honcho -# 1. Initialize your Honcho client -honcho = Honcho(workspace_id="my-app-testing") +# 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"], +) -# 2. Initialize peers +# 1. Store: peers and messages on a session alice = honcho.peer("alice") tutor = honcho.peer("tutor") - -# 3. Create a session and add messages - session = honcho.session("session-1") -# Adding messages from a peer will automatically add them to the session -session.add_messages( - [ - alice.message("Hey there — can you help me with my math homework?"), - tutor.message("Absolutely. Send me your first problem!"), - ] -) -``` +session.add_messages([ + alice.message("Hey there — can you help me with my math homework?"), + tutor.message("Absolutely. Send me your first problem!"), +]) -3. Leverage reasoning from Honcho to inform your agent's behavior +# 2. Reason: happens asynchronously in the background. -```python - -### 1. Use the chat endpoint to ask questions about your users in natural language -response = alice.chat("What learning styles does the user respond to best?") - -### 2. Use session context to continue a conversation with an LLM +# 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) -# Convert to a format to send to OpenAI and get the next message -openai_messages = context.to_openai(assistant=tutor) - +# 4. Inject: hand the context to your model of choice. from openai import OpenAI client = OpenAI() -response = client.chat.completions.create( - model="gpt-4", - messages=openai_messages +completion = client.chat.completions.create( + model=os.environ.get("OPENAI_MODEL", "gpt-4o-mini"), + messages=context.to_openai(assistant=tutor), ) - -### 3. Search for similar messages -results = alice.search("Math Homework") - -### 4. Get a session-scoped representation of a peer -alice_representation = session.representation(alice) - ``` -This is a simple example of how you can use Honcho to build a chatbot and -leverage insights to personalize the agent's behavior. +### TypeScript -Sign up at [app.honcho.dev](https://app.honcho.dev) to get started with a managed version of Honcho. +```bash +npm install @honcho-ai/sdk +# or: bun add @honcho-ai/sdk +``` -Learn more ways to use Honcho on our [developer docs](https://docs.honcho.dev). +```typescript +import { Honcho } from "@honcho-ai/sdk"; +import OpenAI from "openai"; -Read about the design philosophy and history of the project on our [blog](https://blog.plasticlabs.ai/). +const honcho = new Honcho({ + workspaceId: "my-app-testing", + apiKey: process.env.HONCHO_API_KEY, +}); -## Project Structure +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!"), +]); -- [Usage](#usage) -- [Local Development](#local-development) - - [Prerequisites and Dependencies](#prerequisites-and-dependencies) - - [Setup](#setup) - - [Docker](#docker) - - [Deploy on Fly](#deploy-on-fly) -- [Configuration](#configuration) - - [Using config.toml](#using-configtoml) - - [Using Environment Variables](#using-environment-variables) - - [Configuration Priority](#configuration-priority) - - [Example](#example) -- [Architecture](#architecture) - - [Storage](#storage) - - [Reasoning](#reasoning) - - [Retrieving Data & Insights](#retrieving-data--insights) -- [Contributing](#contributing) -- [License](#license) +const answer = await alice.chat("What learning styles does the user respond to best?"); +const context = await session.context({ summary: true, tokens: 10_000 }); -The Honcho project is split between several repositories with this one hosting -the core service logic. This is implemented as a FastAPI server/API to store -data about an application's state. +const openai = new OpenAI(); +const completion = await openai.chat.completions.create({ + model: process.env.OPENAI_MODEL ?? "gpt-4o-mini", + messages: context.toOpenAI({ assistant: tutor }), +}); +``` -There are also client SDKs implemented in the `sdks/` directory with support -for Python and TypeScript. +> **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`](https://docs.honcho.dev/v3/documentation/features/representation) endpoint. -- [Python](https://pypi.org/project/honcho-ai/) -- [TypeScript](https://www.npmjs.com/package/@honcho-ai/sdk) +## What Honcho Gives You -Examples on how to use the SDK are located within each SDK folder and in the -[SDK Reference](https://docs.honcho.dev/v3/documentation/tutorial/SDK) +| Need | API | +|---|---| +| Save interaction history | `session.add_messages(...)` | +| Ask what Honcho knows about a peer | `peer.chat(...)` | +| Get prompt-ready context | `session.context(...).to_openai(...)` / `.to_anthropic(...)` | +| Hybrid search (BM25 + vector) | `peer.search(...)`, `session.search(...)`, `honcho.search(...)` | +| Low-latency static representations | `peer.representation(...)`, `session.representation(...)` | +| Import documents | `session.upload_file(...)` | +| Inspect background processing | `honcho.queue_status(...)` | -There are also documented examples of how to use the core SDKs in the -[API Reference](https://docs.honcho.dev/api-reference/introduction) section of -the documentation. +See the full [SDK Reference](https://docs.honcho.dev/v3/documentation/reference/sdk) and [API Reference](https://docs.honcho.dev/v3/api-reference/introduction). -## Usage +## Integrations -Sign up for an account at -[https://app.honcho.dev](https://app.honcho.dev) and get started with $100 free credits. When you sign up you'll be prompted to -join an organization which will have a dedicated instance of Honcho. +### Claude Code -Provision API keys and change your base url to point to -[https://api.honcho.dev](https://api.honcho.dev) +Two ways, depending on how deep you want to go: -Additionally, Honcho can be self-hosted for testing and evaluation purposes. See -the [Local Development](#local-development) section below for details on how to set up a local -version of Honcho. +**Plugin (richer integration — recommended for Claude Code users):** -## Local Development +```text +/plugin marketplace add plastic-labs/claude-honcho +/plugin install honcho@honcho +``` -Below is a guide on setting up a local environment for running the Honcho -Server. +**Raw MCP (works in any MCP client — Cursor, Cline, Windsurf, etc.):** -> This guide was made using a M3 Macbook Pro. For any compatibility issues -> on different platforms, please raise an Issue. +```bash +claude mcp add honcho \ + --transport http \ + --url "https://mcp.honcho.dev" \ + --header "Authorization: Bearer hch-your-key-here" \ + --header "X-Honcho-User-Name: YourName" +``` -### Prerequisites and Dependencies +Details: [Claude Code guide](https://docs.honcho.dev/v3/guides/integrations/claude-code) · [MCP guide](https://docs.honcho.dev/v3/guides/integrations/mcp). + +### OpenCode + +```bash +opencode plugin "@honcho-ai/opencode-honcho" --global +``` + +Details: [OpenCode guide](https://docs.honcho.dev/v3/guides/integrations/opencode). + +### OpenClaw + +```bash +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](https://docs.honcho.dev/v3/guides/integrations/openclaw). + +### Hermes + +```bash +hermes memory setup # select "honcho", point at api.honcho.dev or your local server +``` + +Details: [Hermes guide](https://docs.honcho.dev/v3/guides/integrations/hermes). + +### Other MCP clients + +The same `claude mcp add` form (or its client-specific equivalent) works in any MCP-compatible client. See [MCP guide](https://docs.honcho.dev/v3/guides/integrations/mcp). + +## Core Concepts + +Honcho organises everything around **peers** — humans and AI agents alike are first-class entities. 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** — observations Honcho has extracted about a peer (deductive and inductive). Exposed via the [conclusions API](https://docs.honcho.dev/v3/api-reference/introduction). +- **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](https://evals.honcho.dev/), the [research blog post](https://blog.plasticlabs.ai/research/Benchmarking-Honcho), and the [Pareto-frontier announcement video](https://x.com/honchodotdev/status/2002090546521911703?s=20) 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) + +```bash +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: + +```python +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](https://www.python.org/) and [uv](https://docs.astral.sh/uv/). The minimum python version is `3.10` The minimum uv version is `0.5.0` -### Setup +#### Setup Once the dependencies are installed on the system run the following steps to get the local project setup. @@ -286,9 +373,12 @@ In a separate terminal, run: uv run python -m src.deriver ``` -The deriver generates representation, summaries, peer cards, and manages dreaming tasks. You can increase the number of deriver's to improve runtime efficiency. +The deriver generates representations, summaries, peer cards, and manages dreaming tasks. You can increase the number of derivers to improve runtime efficiency. -### Pre-commit Hooks +
+ +
+Pre-commit hooks Honcho uses pre-commit hooks to ensure code quality and consistency across the project. These hooks automatically run checks on your code before each commit, including linting, formatting, type checking, and security scans. @@ -340,27 +430,10 @@ uv run pre-commit run ruff --all-files uv run pre-commit run basedpyright --all-files ``` -### Docker +
-As mentioned earlier a `docker-compose` template is included for running Honcho. -As an alternative to running Honcho locally it can also be run with the compose -template. - -The docker-compose template is set to use an environment file called `.env`. -You can also copy the `.env.template` and fill with the appropriate values. - -Copy the template and update the appropriate environment variables before -launching the service: - -```bash -cd honcho -cp .env.template .env -# update the file with openai key and other wanted environment variables -cp docker-compose.yml.example docker-compose.yml -docker compose up -``` - -### Deploy on Fly +
+Deploy on Fly The API can also be deployed on fly.io. Follow the [Fly.io Docs](https://fly.io/docs/getting-started/) to setup your environment and the @@ -380,14 +453,14 @@ cat .env | flyctl secrets import # Load in your secrets flyctl deploy # Deploy with appropriate environment variables ``` +
+ ## Configuration -Honcho uses a flexible configuration system that supports both TOML files and environment variables. Configuration values are loaded in the following priority order (highest to lowest): +Honcho uses a flexible configuration system that supports both TOML files and environment variables. Configuration values are loaded in priority order: **environment variables > `.env` file > `config.toml` > defaults**. -1. Environment variables -2. `.env` file (for local development) -3. `config.toml` file -4. Default values +
+Full configuration reference ### Using config.toml @@ -434,21 +507,6 @@ Examples: - `METRICS_ENABLED` - Enable Prometheus metrics - `TELEMETRY_ENABLED` - Enable CloudEvents telemetry -### Configuration Priority - -When a configuration value is set in multiple places, Honcho uses this priority: - -1. **Environment variables** - Always take precedence -2. **.env file** - Loaded for local development -3. **config.toml** - Base configuration -4. **Default values** - Built-in defaults - -This allows you to: - -- Use `config.toml` for base configuration -- Override specific values with environment variables in production -- Use `.env` files for local development without modifying config.toml - ### Example If you have this in `config.toml`: @@ -467,28 +525,14 @@ export DB_CONNECTION_URI="postgresql+psycopg://prod-server/honcho_prod" The application will use the production connection URI while keeping the pool size from config.toml. +
+ ## Architecture -The functionality of Honcho can be split into two different services: Storage -and Insights. +Honcho splits into two services: **Storage** (workspaces, peers, sessions, messages, internal collections) and **Insights** (reasoning, conclusions, representations, summaries, the chat endpoint). Storage is synchronous via the API; Insights is asynchronous via a background queue consumed by the deriver worker process. -### Peer Paradigm - -Honcho uses an entity-centric model where both users and agents are represented as "[peers](https://blog.plasticlabs.ai/blog/Beyond-the-User-Assistant-Paradigm;-Introducing-Peers)". This unified approach 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 - -#### Key Features - -- **Rich Reasoning System**: Multiple implementation methods that extract conclusions from interactions and build comprehensive representations of peers -- **Chat API**: Provides reasoning-informed responses that integrate conclusions with current context -- **Background Processing**: Asynchronous processing pipeline for expensive operations like representation updates and session summarization -- **Multi-Provider Support**: Configurable LLM providers for different use cases - -### Storage +
+Storage primitives in detail Honcho contains several different primitives used for storing application and peer data. This data is used for managing conversations, modeling peer @@ -503,8 +547,7 @@ Below is a mapping of the different primitives and their relationships. Workspaces ├── Peers ←──────────────────┐ │ ├── Sessions │ -│ └── Collections │ -│ └── Documents │ +│ └── (internal collections, keyed by observer/observed peer pair) │ │ │ │ └── Sessions ←───────────────┤ (many-to-many) @@ -514,12 +557,10 @@ Workspaces **Relationship Details:** -- A **Workspace** contains multiple **Peers** -- **Peers** and **Sessions** have a many-to-many relationship (peers can participate in multiple sessions, sessions can have multiple peers) -- **Messages** can exist at two levels: - - **Session-level**: Communication between peers within a session -- **Collections** belong to specific **Peers** -- **Documents** are stored within **Collections** +- A **Workspace** contains multiple **Peers**. +- **Peers** and **Sessions** have a many-to-many relationship (peers can participate in multiple sessions, sessions can have multiple peers). +- **Messages** belong to a session and are labelled by their source peer. +- **Internal collections** of vector-embedded **documents** are keyed by `(observer, observed)` peer pairs. They are not directly exposed via the API; the observations stored in them are exposed as **Conclusions**. Users familiar with APIs such as the OpenAI Assistants API will be familiar with much of the mapping here. @@ -533,7 +574,7 @@ isolate data between use cases and provide multi-tenant capabilities. #### Peers Within a `Workspace` everything revolves around a `Peer`. The `Peer` object -represents any participant in the system - whether human users or AI agents. +represents any participant in the system — whether human users or AI agents. This unified model enables complex multi-participant interactions. #### Sessions @@ -544,45 +585,35 @@ Sessions can involve multiple peers with configurable observation settings. #### Messages -The `Message` represents an atomic data unit that can exist at two levels: +The `Message` represents an atomic data unit that exists at the session level: +communication between peers within a session context. All messages are labelled +by their source peer and can be processed asynchronously to update their +representations. This flexible design allows for both conversational interactions +and broader data ingestion for personality modelling. -- **Session-level Messages**: Communication between peers within a session context +
-All messages are labeled by their source peer and can be processed -asynchronously to update their representations. This flexible design allows for -both conversational interactions and broader data ingestion for personality -modeling. - -#### Collections - -At a high level a `Collection` is a named group of `Documents`. Developers -familiar with RAG based applications will be familiar with these. `Collections` -store vector embedded data that developers and agents can retrieve against using -functions like cosine similarity. - -Collections are also used internally by Honcho while creating representations of peers. - -#### Documents - -As stated before a `Document` is vector embedded data stored in a `Collection`. - -### Reasoning +
+Reasoning pipeline The reasoning functionality of Honcho is built on top of the Storage service. As `Messages` and `Sessions` are created for `Peers`, Honcho will asynchronously reason about peer psychology to derive facts about them and store them -in reserved `Collections`. +in reserved internal collections. A high level summary of the pipeline is as follows: -1. Messages are created via the API -2. Derivation Tasks are enqueued for background processing including: - - `representation`: To update representations of `Peers` - - `summary`: To create summaries of `Sessions` -3. Session-based queue processing ensures proper ordering -4. Results are stored internally +1. Messages are created via the API. +2. Derivation tasks are enqueued for background processing, including: + - `representation`: update representations of `Peers`. + - `summary`: create summaries of `Sessions`. +3. Session-based queue processing ensures proper ordering. +4. Results are stored internally and surfaced via the Conclusions API, Representations, Peer Cards, and the Chat Endpoint. -### Retrieving Data & Insights +
+ +
+Retrieving data and insights Honcho exposes several different ways to retrieve data from the system to best serve the needs of any given application. @@ -606,31 +637,27 @@ the results. #### Chat API -The flagship interface for using these insights is through -the [`Chat` Endpoint](https://blog.plasticlabs.ai/archive/ARCHIVED;-Introducing-Honcho's-Dialectic-API). +The flagship interface for using these insights is the [Chat Endpoint](https://docs.honcho.dev/v3/documentation/features/chat) (`POST /peers/{peer_id}/chat`). It takes natural-language requests to get data about a peer and returns reasoning-grounded responses. Examples: -This is a regular API endpoint (`/peers/{peer_id}/chat`) that takes natural language requests to get data -about the `Peer`. This robust design lets us use this single endpoint for all -cases where extra personalization or information about the `Peer` is necessary. - -A developer's application can treat Honcho as an oracle to the `Peer` and -consult it when necessary. Some examples of how to leverage the Dialectic -API include: - -- Asking Honcho for a generic or specific insight about the `Peer` -- Asking Honcho to hydrate a prompt with data about the `Peer`s behavior -- Asking Honcho for a 2nd opinion or approach about how to respond to the Peer -- Getting personalized responses that incorporate long-term facts and context +- Asking Honcho for a generic or specific insight about the peer. +- Asking Honcho to hydrate a prompt with data about the peer's behaviour. +- Asking Honcho for a second opinion on how to respond. +- Getting personalised responses that incorporate long-term facts and context. #### Representations -For low-latency use cases, -Honcho provides access to a `representation` endpoint that -returns a static document with insights about a `Peer` in the context of a -particular session. +For low-latency use cases, Honcho provides access to a `representation` endpoint that returns a static document with insights about a peer in the context of a particular session. Use this to quickly add context to a prompt without having to wait for an LLM response. -Use this to quickly add context to a prompt without having to wait for an LLM -response. +
+ +## SDKs + +- **Python** — [`honcho-ai`](https://pypi.org/project/honcho-ai/) on PyPI · source in [`sdks/python/`](./sdks/python) +- **TypeScript** — [`@honcho-ai/sdk`](https://www.npmjs.com/package/@honcho-ai/sdk) on npm · source in [`sdks/typescript/`](./sdks/typescript) + +SDKs are versioned independently of the server. Current SDK versions track each other; the server badge above reflects the deployed server version. + +See the [SDK Reference](https://docs.honcho.dev/v3/documentation/reference/sdk) for full API surface, the [API Reference](https://docs.honcho.dev/v3/api-reference/introduction) for the raw HTTP API, and per-SDK example folders for runnable demos. ## Contributing @@ -638,4 +665,4 @@ We welcome contributions to Honcho! Please read our [Contributing Guide](./CONTR ## License -Honcho is licensed under the AGPL-3.0 License. Learn more at the [License file](./LICENSE) +Honcho is licensed under the AGPL-3.0 License. Learn more at the [License file](./LICENSE).