RomanNum3ral
/
honcho
mirror of https://github.com/plastic-labs/honcho.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs(readme): repositioning pass + staleness fixes (P0-P4 audit) 

Restructure README to match dual audience (AI-tool users + product
developers) per Vineeth's audit. No content deleted - long internal
sections collapsed under `<details>` for scannability.

Staleness fixes:
- Replace 404'd doc links (.../tutorial/SDK, /api-reference/introduction)
  with verified replacements under /v3/documentation/reference/sdk
  and /v3/api-reference/introduction
- Fix Python quickstart to pass api_key (managed default api.honcho.dev
  would 401 otherwise)
- Drop hardcoded `gpt-4` model reference; read OPENAI_MODEL from env
- Replace archived Dialectic blog link with current Chat Endpoint docs
- Drop M3-Macbook-specific note; minor grammar ("deriver's" -> "derivers")
- Replace TL;DR Python-only example with side-by-side Python + TypeScript
  framed around the "Honcho Loop" (store / reason / query / inject)

New sections:
- Start Here: three-path table (AI tools / building product / self-host)
- The Honcho Loop: operation model before code
- What Honcho Gives You: API-at-a-glance table
- Integrations: verified install commands for Claude Code (plugin + raw
  MCP), OpenCode, OpenClaw, Hermes
- Honcho vs RAG: stubbed with TODO; copy deferred to marketing
- SDKs section with clearer Python/TypeScript landing pointers

Restructured:
- Core Concepts moved above Architecture; Collections/Documents reframed
  as internal mechanism (Conclusions is the public surface)
- Storage / Reasoning / Retrieving deep-dive wrapped in <details>
- Local Development, Pre-commit hooks, Fly deployment, full config
  matrix wrapped in <details>

Known follow-up (not in this branch): SDK docs at docs.honcho.dev and
PyPI PKG-INFO advertise `HONCHO_BASE_URL`, but the actual SDK code
(sdks/python/src/honcho/client.py:234, sdks/typescript/src/client.ts:154)
reads `HONCHO_URL`. README aligned with code; docs + PKG-INFO need
separate fix.
This commit is contained in:
thrialectics 2026-05-11 18:28:14 -04:00
parent 5de8a3b81a
commit d6d60435ac
1 changed files with 250 additions and 223 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

473
README.md
View File

@ -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/) [![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) [![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) [![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 **Honcho is memory infrastructure for agents that need to understand changing people, agents, groups, projects, and ideas over time.**
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 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.
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 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. > 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 | I want to... | Path | Get started |
interaction history, and leverage the reasoning it does to inform the behavior of |---|---|---|
your agents | 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 ```bash
# Python
pip install honcho-ai pip install honcho-ai
uv add honcho-ai # or: uv add honcho-ai
poetry add honcho-ai # or: poetry add honcho-ai
``` ```
2. Setup your `Workspace`, `Peers`, `Session`, and send `Messages`
```python ```python
import os
from honcho import Honcho from honcho import Honcho
# 1. Initialize your Honcho client # Managed service uses api.honcho.dev by default. For self-hosted, pass
honcho = Honcho(workspace_id="my-app-testing") # 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") alice = honcho.peer("alice")
tutor = honcho.peer("tutor") tutor = honcho.peer("tutor")
# 3. Create a session and add messages
session = honcho.session("session-1") session = honcho.session("session-1")
# Adding messages from a peer will automatically add them to the session session.add_messages([
session.add_messages( alice.message("Hey there — can you help me with my math homework?"),
[ tutor.message("Absolutely. Send me your first problem!"),
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 # 3. Query: ask Honcho what it knows, or pull prompt-ready context.
answer = alice.chat("What learning styles does the user respond to best?")
### 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
context = session.context(summary=True, tokens=10_000) context = session.context(summary=True, tokens=10_000)
# Convert to a format to send to OpenAI and get the next message # 4. Inject: hand the context to your model of choice.
openai_messages = context.to_openai(assistant=tutor)
from openai import OpenAI from openai import OpenAI
client = OpenAI() client = OpenAI()
response = client.chat.completions.create( completion = client.chat.completions.create(
model="gpt-4", model=os.environ.get("OPENAI_MODEL", "gpt-4o-mini"),
messages=openai_messages 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 ### TypeScript
leverage insights to personalize the agent's behavior.
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) const answer = await alice.chat("What learning styles does the user respond to best?");
- [Local Development](#local-development) const context = await session.context({ summary: true, tokens: 10_000 });
- [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)
The Honcho project is split between several repositories with this one hosting const openai = new OpenAI();
the core service logic. This is implemented as a FastAPI server/API to store const completion = await openai.chat.completions.create({
data about an application's state. 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 > **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.
for Python and TypeScript.
- [Python](https://pypi.org/project/honcho-ai/) ## What Honcho Gives You
- [TypeScript](https://www.npmjs.com/package/@honcho-ai/sdk)
Examples on how to use the SDK are located within each SDK folder and in the | Need | API |
[SDK Reference](https://docs.honcho.dev/v3/documentation/tutorial/SDK) |---|---|
| 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 See the full [SDK Reference](https://docs.honcho.dev/v3/documentation/reference/sdk) and [API Reference](https://docs.honcho.dev/v3/api-reference/introduction).
[API Reference](https://docs.honcho.dev/api-reference/introduction) section of
the documentation.
## Usage ## Integrations
Sign up for an account at ### Claude Code
[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.
Provision API keys and change your base url to point to Two ways, depending on how deep you want to go:
[https://api.honcho.dev](https://api.honcho.dev)
Additionally, Honcho can be self-hosted for testing and evaluation purposes. See **Plugin (richer integration — recommended for Claude Code users):**
the [Local Development](#local-development) section below for details on how to set up a local
version of Honcho.
## 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 **Raw MCP (works in any MCP client — Cursor, Cline, Windsurf, etc.):**
Server.
> This guide was made using a M3 Macbook Pro. For any compatibility issues ```bash
> on different platforms, please raise an Issue. 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.
<details>
<summary>Internal storage (Collections &amp; Documents)</summary>
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.
</details>
<!-- TODO(vineeth/marketing): write the "Honcho vs RAG / vector DB / memory-only" comparison.
Audit recommendation referenced; copy intentionally deferred to avoid inventing
positioning claims unsupported by primary sources. -->
## Benchmarks &amp; 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
```
<details>
<summary>Local development without Docker</summary>
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/). 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 python version is `3.10`
The minimum uv version is `0.5.0` The minimum uv version is `0.5.0`
### Setup #### Setup
Once the dependencies are installed on the system run the following steps to get Once the dependencies are installed on the system run the following steps to get
the local project setup. the local project setup.
@ -286,9 +373,12 @@ In a separate terminal, run:
uv run python -m src.deriver 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 </details>
<details>
<summary>Pre-commit hooks</summary>
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. 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 uv run pre-commit run basedpyright --all-files
``` ```
### Docker </details>
As mentioned earlier a `docker-compose` template is included for running Honcho. <details>
As an alternative to running Honcho locally it can also be run with the compose <summary>Deploy on Fly</summary>
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
The API can also be deployed on fly.io. Follow the [Fly.io 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 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 flyctl deploy # Deploy with appropriate environment variables
``` ```
</details>
## Configuration ## 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 <details>
2. `.env` file (for local development) <summary>Full configuration reference</summary>
3. `config.toml` file
4. Default values
### Using config.toml ### Using config.toml
@ -434,21 +507,6 @@ Examples:
- `METRICS_ENABLED` - Enable Prometheus metrics - `METRICS_ENABLED` - Enable Prometheus metrics
- `TELEMETRY_ENABLED` - Enable CloudEvents telemetry - `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 ### Example
If you have this in `config.toml`: 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. The application will use the production connection URI while keeping the pool size from config.toml.
</details>
## Architecture ## Architecture
The functionality of Honcho can be split into two different services: Storage 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.
and Insights.
### Peer Paradigm <details>
<summary>Storage primitives in detail</summary>
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
Honcho contains several different primitives used for storing application and Honcho contains several different primitives used for storing application and
peer data. This data is used for managing conversations, modeling peer 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 Workspaces
├── Peers ←──────────────────┐ ├── Peers ←──────────────────┐
│ ├── Sessions │ │ ├── Sessions │
│ └── Collections │ │ └── (internal collections, keyed by observer/observed peer pair)
│ └── Documents │
│ │ │ │
│ │ │ │
└── Sessions ←───────────────┤ (many-to-many) └── Sessions ←───────────────┤ (many-to-many)
@ -514,12 +557,10 @@ Workspaces
**Relationship Details:** **Relationship Details:**
- A **Workspace** contains multiple **Peers** - 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) - **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: - **Messages** belong to a session and are labelled by their source peer.
- **Session-level**: Communication between peers within a session - **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**.
- **Collections** belong to specific **Peers**
- **Documents** are stored within **Collections**
Users familiar with APIs such as the OpenAI Assistants API will be familiar with Users familiar with APIs such as the OpenAI Assistants API will be familiar with
much of the mapping here. much of the mapping here.
@ -533,7 +574,7 @@ isolate data between use cases and provide multi-tenant capabilities.
#### Peers #### Peers
Within a `Workspace` everything revolves around a `Peer`. The `Peer` object 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. This unified model enables complex multi-participant interactions.
#### Sessions #### Sessions
@ -544,45 +585,35 @@ Sessions can involve multiple peers with configurable observation settings.
#### Messages #### 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 </details>
All messages are labeled by their source peer and can be processed <details>
asynchronously to update their representations. This flexible design allows for <summary>Reasoning pipeline</summary>
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
The reasoning functionality of Honcho is built on top of the Storage service. As The reasoning functionality of Honcho is built on top of the Storage service. As
`Messages` and `Sessions` are created for `Peers`, Honcho will asynchronously `Messages` and `Sessions` are created for `Peers`, Honcho will asynchronously
reason about peer psychology to derive facts about them and store them 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: A high level summary of the pipeline is as follows:
1. Messages are created via the API 1. Messages are created via the API.
2. Derivation Tasks are enqueued for background processing including: 2. Derivation tasks are enqueued for background processing, including:
- `representation`: To update representations of `Peers` - `representation`: update representations of `Peers`.
- `summary`: To create summaries of `Sessions` - `summary`: create summaries of `Sessions`.
3. Session-based queue processing ensures proper ordering 3. Session-based queue processing ensures proper ordering.
4. Results are stored internally 4. Results are stored internally and surfaced via the Conclusions API, Representations, Peer Cards, and the Chat Endpoint.
### Retrieving Data & Insights </details>
<details>
<summary>Retrieving data and insights</summary>
Honcho exposes several different ways to retrieve data from the system to best Honcho exposes several different ways to retrieve data from the system to best
serve the needs of any given application. serve the needs of any given application.
@ -606,31 +637,27 @@ the results.
#### Chat API #### Chat API
The flagship interface for using these insights is through 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:
the [`Chat` Endpoint](https://blog.plasticlabs.ai/archive/ARCHIVED;-Introducing-Honcho's-Dialectic-API).
This is a regular API endpoint (`/peers/{peer_id}/chat`) that takes natural language requests to get data - Asking Honcho for a generic or specific insight about the peer.
about the `Peer`. This robust design lets us use this single endpoint for all - Asking Honcho to hydrate a prompt with data about the peer's behaviour.
cases where extra personalization or information about the `Peer` is necessary. - Asking Honcho for a second opinion on how to respond.
- Getting personalised responses that incorporate long-term facts and context.
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
#### Representations #### Representations
For low-latency use cases, 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.
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 </details>
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 ## Contributing
@ -638,4 +665,4 @@ We welcome contributions to Honcho! Please read our [Contributing Guide](./CONTR
## License ## 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).