Skip to content
Back to search

honcho

Memory library for building stateful agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/plastic-labs/honcho with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/plastic-labs/honcho'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/plastic-labs--honcho/badge.svg)](/listings/plastic-labs--honcho)

HTML

<a href="/listings/plastic-labs--honcho"><img src="/api/listings/plastic-labs--honcho/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Get an API key at [app.honcho.dev](https://app.honcho.dev) — when you sign up you'll be prompted to join an organization, which gets its own dedicated Honcho instance. Or install the CLI and run [`honcho start --setup`](#cli), then point the SDK at `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`](https://honcho.dev/docs/v3/documentation/features/representation) endpoint.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 767 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!-- markdownlint-disable MD033 -->
  2. <div align="center">
  3. <a href="https://app.honcho.dev" target="_blank">
  4. <img src="assets/honcho.svg" alt="Honcho" width="400">
  5. </a>
  6. </div>
  7. <!-- markdownlint-enable MD033 -->
  8. ---
  9. ![Static Badge](https://img.shields.io/badge/Server-3.6.1-blue)
  10. [![PyPI version](https://img.shields.io/pypi/v/honcho-ai.svg)](https://pypi.org/project/honcho-ai/)
  11. [![NPM version](https://img.shields.io/npm/v/@honcho-ai/sdk.svg)](https://npmjs.org/package/@honcho-ai/sdk)
  12. [![CLI](https://img.shields.io/pypi/v/honcho-cli.svg?label=honcho-cli)](https://pypi.org/project/honcho-cli/)
  13. [![Discord](https://img.shields.io/discord/1016845111637839922?style=flat&logo=discord&logoColor=23ffffff&label=Plastic%20Labs&labelColor=235865F2)](https://discord.gg/honcho)
  14. **Honcho is memory infrastructure for building stateful agents that understand changing people, agents, groups, projects, and ideas over time.**
  15. 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), run a local stack with [`honcho start`](#cli), or self-host the FastAPI server yourself.
  16. Using Honcho as your memory system will earn your agents higher retention, more trust, and help you build data moats to out-compete incumbents.
  17. > 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://honcho.dev/evals/), and read the [blog post](https://blog.plasticlabs.ai/research/Benchmarking-Honcho) for more detail.
  18. ## Contents
  19. - [Start Here](#start-here)
  20. - [Why Honcho](#why-honcho)
  21. - [The Honcho Loop](#the-honcho-loop)
  22. - [Quickstart](#quickstart)
  23. - [What Honcho Gives You](#what-honcho-gives-you)
  24. - [Integrations](#integrations)
  25. - [CLI](#cli)
  26. - [Core Concepts](#core-concepts)
  27. - [Benchmarks & Evals](#benchmarks--evals)
  28. - [Self-hosting](#self-hosting)
  29. - [Configuration](#configuration)
  30. - [Architecture](#architecture)
  31. - [SDKs](#sdks)
  32. - [Learn More](#learn-more)
  33. - [Contributing](#contributing)
  34. - [License](#license)
  35. 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/`](./sdks) directory. The [`honcho-cli`](./honcho-cli) package lives here too.
  36. ## Start Here
  37. | I want to... | Path | Get started |
  38. | -------------------------------------- | ---------------------------------------------------------- | ----------------------------- |
  39. | Give my coding agent persistent memory | Claude Code, Cursor, Grok Bot, OpenCode, Kilo Code, OpenClaw, Hermes, or any MCP client | [Integrations](#integrations) |
  40. | Add memory to my product | Python or TypeScript SDK | [Quickstart](#quickstart) |
  41. | Run Honcho locally | Install CLI, then `honcho start --setup` | [CLI](#cli) |
  42. | Inspect a deployment | `honcho workspace inspect`, `honcho doctor` | [CLI](#cli) |
  43. | Self-host from source | Docker Compose or local development | [Self-hosting](#self-hosting) |
  44. ## Why Honcho
  45. | Capability | What it means |
  46. | ----------------------- | ------------------------------------------------------------------------------------ |
  47. | Reasoning-first memory | Extracts conclusions from conversations and events, not just matching chunks. |
  48. | Peer-centric model | Tracks users, agents, groups, projects, and ideas as entities that change over time. |
  49. | Multi-peer perspective | Models what one peer knows about another when configured. |
  50. | Managed or self-hosted | Use `api.honcho.dev`, `honcho start` locally, or run the FastAPI server yourself. |
  51. | Agent-tool integrations | MCP, Claude Code, Cursor, Grok Bot, OpenCode, Kilo Code, OpenClaw, Hermes. |
  52. ## The Honcho Loop
  53. 1. **Store** conversations, events, documents, or tool traces as messages on a session.
  54. 2. **Reason** — Honcho processes the queue in the background and updates peer representations.
  55. 3. **Query** — ask Honcho for context, search results, peer representations, or a natural-language answer.
  56. 4. **Inject** — drop the result into any LLM call or agent framework.
  57. 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://honcho.dev/docs/v3/documentation/features/chat) or directly.
  58. ## Quickstart
  59. Get an API key at [app.honcho.dev](https://app.honcho.dev) — when you sign up you'll be prompted to join an organization, which gets its own dedicated Honcho instance. Or install the CLI and run [`honcho start --setup`](#cli), then point the SDK at `http://localhost:8000`.
  60. ### Python
  61. ```bash
  62. pip install honcho-ai
  63. # or: uv add honcho-ai
  64. # or: poetry add honcho-ai
  65. ```
  66. ```python
  67. import os
  68. from honcho import Honcho
  69. # Managed service uses api.honcho.dev by default. For self-hosted, pass
  70. # base_url="http://localhost:8000" or set HONCHO_URL.
  71. honcho = Honcho(
  72. workspace_id="my-app-testing",
  73. api_key=os.environ["HONCHO_API_KEY"],
  74. )
  75. # 1. Store: peers and messages on a session
  76. alice = honcho.peer("alice")
  77. tutor = honcho.peer("tutor")
  78. session = honcho.session("session-1")
  79. session.add_messages([
  80. alice.message("Hey there — can you help me with my math homework?"),
  81. tutor.message("Absolutely. Send me your first problem!"),
  82. ])
  83. # 2. Reason: happens asynchronously in the background.
  84. # 3. Query: ask Honcho what it knows, or pull prompt-ready context.
  85. answer = alice.chat("What learning styles does the user respond to best?")
  86. context = session.context(summary=True, tokens=10_000)
  87. # 4. Inject: hand the context to your model of choice.
  88. from openai import OpenAI
  89. client = OpenAI()
  90. completion = client.chat.completions.create(
  91. model=os.environ.get("OPENAI_MODEL", "gpt-4o-mini"),
  92. messages=context.to_openai(assistant=tutor),
  93. )
  94. ```
  95. ### TypeScript
  96. ```bash
  97. npm install @honcho-ai/sdk
  98. # or: bun add @honcho-ai/sdk
  99. ```
  100. ```typescript
  101. import { Honcho } from "@honcho-ai/sdk";
  102. import OpenAI from "openai";
  103. const honcho = new Honcho({
  104. workspaceId: "my-app-testing",
  105. apiKey: process.env.HONCHO_API_KEY,
  106. });
  107. const alice = await honcho.peer("alice");
  108. const tutor = await honcho.peer("tutor");
  109. const session = await honcho.session("session-1");
  110. await session.addMessages([
  111. alice.message("Hey there — can you help me with my math homework?"),
  112. tutor.message("Absolutely. Send me your first problem!"),
  113. ]);
  114. const answer = await alice.chat(
  115. "What learning styles does the user respond to best?",
  116. );
  117. const context = await session.context({ summary: true, tokens: 10_000 });
  118. const openai = new OpenAI();
  119. const completion = await openai.chat.completions.create({
  120. model: process.env.OPENAI_MODEL ?? "gpt-4o-mini",
  121. messages: context.toOpenAI({ assistant: tutor }),
  122. });
  123. ```
  124. > **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://honcho.dev/docs/v3/documentation/features/representation) endpoint.
  125. ## What Honcho Gives You
  126. | Need | API |
  127. | ---------------------------------- | --------------------------------------------------------------- |
  128. | Save interaction history | `session.add_messages(...)` |
  129. | Ask what Honcho knows about a peer | `peer.chat(...)` |
  130. | Ask across the whole workspace | `honcho.chat(...)` / `honcho.chat_stream(...)` |
  131. | Get prompt-ready context | `session.context(...).to_openai(...)` / `.to_anthropic(...)` |
  132. | Hybrid search (BM25 + vector) | `peer.search(...)`, `session.search(...)`, `honcho.search(...)` |
  133. | Low-latency static representations | `peer.representation(...)`, `session.representation(...)` |
  134. | Import documents | `session.upload_file(...)` |
  135. | Inspect background processing | `honcho.queue_status(...)` |
  136. See the full [SDK Reference](https://honcho.dev/docs/v3/documentation/reference/sdk) and [API Reference](https://honcho.dev/docs/v3/api-reference/introduction).
  137. ## Integrations
  138. Honcho ships a first-party memory plugin for every major coding agent. They all read the same
  139. `~/.honcho/config.json`, so one key configures all of them — and pointing two at the same `workspace`
  140. gives them one shared memory.
  141. One command finds the agents on your machine and adds Honcho to the ones you pick:
  142. ```bash
  143. uvx honcho-cli install
  144. ```
  145. It installs the plugin for Claude Code, Hermes, OpenClaw and Pi, and the MCP server and skill for Codex, using each agent's own CLI. It asks for your API key if `~/.honcho/config.json` doesn't have one yet. For any other agent it finds, it links to that agent's setup guide. To install one agent by hand, use the table below.
  146. | Agent | Install | Source |
  147. | ---------------- | ------------------------------------------------------- | ------------------------------------------------------------------ |
  148. | Claude Code | `/plugin marketplace add plastic-labs/claude-honcho` | [claude-honcho](https://github.com/plastic-labs/claude-honcho) |
  149. | Codex | `npm install -g @honcho-ai/codex-honcho` | [codex-honcho](https://github.com/plastic-labs/codex-honcho) |
  150. | Cursor | Install **Honcho** from the Cursor Marketplace | [integrations/cursor](integrations/cursor/) |
  151. | Grok Bot | **Add to Grok Bot** from the Honcho plugin page | [integrations/cursor](integrations/cursor/) |
  152. | DeepSeek Harness | `dsh plugin --profile <name> add @honcho-ai/dsh-honcho` | [dsh-honcho](https://github.com/plastic-labs/dsh-honcho) |
  153. | OpenCode | `opencode plugin "@honcho-ai/opencode-honcho" --global` | [opencode-honcho](https://github.com/plastic-labs/opencode-honcho) |
  154. | Kilo Code | `kilo plugin @honcho-ai/kilo-honcho --global` | [kilo-honcho](kilo-honcho/) |
  155. | OpenClaw | `openclaw plugins install @honcho-ai/openclaw-honcho` | [openclaw-honcho](https://github.com/plastic-labs/openclaw-honcho) |
  156. | Pi | `pi install npm:@honcho-ai/pi-honcho` | [pi-honcho](https://github.com/plastic-labs/pi-honcho) |
  157. | Hermes | `hermes memory setup` | built in upstream |
  158. | Any MCP client | `claude mcp add honcho --transport http ...` | [MCP guide](https://honcho.dev/docs/v3/guides/integrations/mcp) |
  159. Get a key at [app.honcho.dev](https://app.honcho.dev), then `honcho init` (or `uv tool install honcho-cli && honcho init`) writes it to `~/.honcho/config.json` once for every integration. Cursor and Grok Bot are the exception: the marketplace plugin signs in with OAuth, and `honcho init` is optional there (in Cursor it turns on automatic capture).
  160. ### Claude Code
  161. Two ways, depending on how deep you want to go:
  162. **Plugin (richer integration — recommended for Claude Code users):**
  163. ```text
  164. /plugin marketplace add plastic-labs/claude-honcho
  165. /plugin install honcho@honcho
  166. ```
  167. **Raw MCP (works in any MCP client — Cursor, Cline, Windsurf, etc.):**
  168. ```bash
  169. claude mcp add honcho \
  170. --transport http \
  171. --url "https://mcp.honcho.dev" \
  172. --header "Authorization: Bearer hch-your-key-here" \
  173. --header "X-Honcho-User-Name: YourName"
  174. ```
  175. Details: [Claude Code guide](https://honcho.dev/docs/v3/guides/integrations/claude-code) · [MCP guide](https://honcho.dev/docs/v3/guides/integrations/mcp) · [repo](https://github.com/plastic-labs/claude-honcho).
  176. ### Codex
  177. ```bash
  178. npm install -g @honcho-ai/codex-honcho
  179. codex-honcho install # registers hooks + MCP + skill in ~/.codex
  180. ```
  181. Restart Codex to load the hooks. Details: [Codex guide](https://honcho.dev/docs/v3/guides/integrations/codex) · [repo](https://github.com/plastic-labs/codex-honcho).
  182. ### Cursor and Grok Bot
  183. One Cursor Marketplace listing serves both. In Cursor, open **Customize**, install **Honcho**, authenticate the `honcho` MCP server, then run `/honcho-setup` once. In Grok Bot, add **Honcho** under **Connect apps** (or **Add to Grok Bot** from the plugin page) and ask a Bot to set up Honcho. The plugin connects to the hosted MCP server over OAuth and ships the skills that drive the memory loop, so nothing runs locally.
  184. Details: [Cursor guide](https://honcho.dev/docs/v3/guides/integrations/cursor) · [Grok Bot guide](https://honcho.dev/docs/v3/guides/integrations/grok-bot) · [source](integrations/cursor/).
  185. ### DeepSeek Harness
  186. ```bash
  187. dsh plugin --profile <name> add @honcho-ai/dsh-honcho
  188. ```
  189. A native Cordis plugin. It injects memory into the system prompt and captures new information from the session event feed. The model gets three tools — honcho_search, honcho_chat, and honcho_remember — and you can run /honcho to check status.
  190. Details: [DeepSeek Harness guide](https://honcho.dev/docs/v3/guides/integrations/deepseek-harness) · [repo](https://github.com/plastic-labs/dsh-honcho).
  191. ### OpenCode
  192. ```bash
  193. opencode plugin "@honcho-ai/opencode-honcho" --global
  194. ```
  195. Details: [OpenCode guide](https://honcho.dev/docs/v3/guides/integrations/opencode) · [repo](https://github.com/plastic-labs/opencode-honcho).
  196. ### Kilo Code
  197. ```bash
  198. kilo plugin @honcho-ai/kilo-honcho --global
  199. ```
  200. One install covers the Kilo CLI, the VS Code extension, and the JetBrains plugin, since all three run the same Kilo server.
  201. Details: [Kilo Code guide](https://honcho.dev/docs/v3/guides/integrations/kilo) · [source](kilo-honcho/).
  202. ### OpenClaw
  203. ```bash
  204. openclaw plugins install @honcho-ai/openclaw-honcho
  205. openclaw honcho setup
  206. openclaw gateway --force
  207. ```
  208. `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://honcho.dev/docs/v3/guides/integrations/openclaw) · [repo](https://github.com/plastic-labs/openclaw-honcho).
  209. ### Hermes
  210. ```bash
  211. hermes memory setup # select "honcho", point at api.honcho.dev or your local server
  212. ```
  213. Details: [Hermes guide](https://honcho.dev/docs/v3/guides/integrations/hermes).
  214. ### Add Honcho to your own codebase (agent skill)
  215. 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:
  216. ```bash
  217. npx skills add plastic-labs/honcho
  218. ```
  219. Then invoke `/honcho-integration` in Claude Code (or `/honcho-dev:integrate` via the plugin marketplace). The same command also installs the memory skills — `honcho-memory` (concepts: the recall/record loop, session and peer strategy, plus how to connect and drive an MCP-connected Honcho) and `honcho-cli` (inspecting a deployment, or running a local stack with `honcho start`). Details: [agentic development guide](https://honcho.dev/docs/v3/documentation/introduction/vibecoding).
  220. ### Other MCP clients
  221. The same `claude mcp add` form (or its client-specific equivalent) works in any MCP-compatible client. See [MCP guide](https://honcho.dev/docs/v3/guides/integrations/mcp).
  222. ## CLI
  223. [`honcho-cli`](https://pypi.org/project/honcho-cli/) inspects a Honcho deployment from the terminal, or runs a personal local stack with Docker.
  224. ```bash
  225. uv tool install honcho-cli
  226. honcho init # Honcho API key or browser login + server URL
  227. honcho install # add Honcho to the AI agents on this machine
  228. honcho start --setup basic # local stack: LLM provider key + Docker
  229. honcho doctor
  230. ```
  231. `honcho init` authenticates the CLI against a Honcho server. `honcho start --setup` is a separate step: it writes the LLM provider key the local deriver needs and starts API + deriver + Postgres + Redis.
  232. Full commands and local-stack details: [CLI reference](https://honcho.dev/docs/v3/documentation/reference/cli) · [`honcho-cli/README.md`](./honcho-cli/README.md). To develop the server from source, see [Self-hosting](#self-hosting).
  233. ## Core Concepts
  234. Honcho organises everything around **peers** — humans and AI agents alike are first-class entities. The peer model enables:
  235. - Multi-participant sessions with mixed human and AI agents
  236. - Configurable observation settings (which peers observe which others)
  237. - Flexible identity management for all participants
  238. - Support for complex multi-agent interactions
  239. Peers exchange messages within sessions; Honcho reasons over those messages to build a representation of each peer that you can query.
  240. - **Workspace** (formerly App): top-level container; isolates data between use cases.
  241. - **Peer** (formerly User): any participant — human user or AI agent.
  242. - **Session**: a conversation context; many-to-many with peers.
  243. - **Scope**: a named grouping of sessions that bounds recall (chat, representation, search) to those members.
  244. - **Message**: an atomic data unit (peer-to-peer communication or ingested document chunk).
  245. What you query out of Honcho:
  246. - **Conclusions** — what Honcho has extracted about a peer (deductive and inductive). Exposed via the [conclusions API](https://honcho.dev/docs/v3/api-reference/introduction).
  247. - **Representations** — static, low-latency snapshots of what Honcho knows about a peer (optionally session-scoped).
  248. - **Peer Cards** — compact identity summaries.
  249. - **Session context / summaries** — prompt-ready bundles for long-running conversations.
  250. <!-- markdownlint-disable MD033 -->
  251. <details>
  252. <summary>Internal storage (Collections &amp; Documents)</summary>
  253. 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.
  254. </details>
  255. <!-- markdownlint-enable MD033 -->
  256. <!-- TODO(vineeth/marketing): write the "Honcho vs RAG / vector DB / memory-only" comparison.
  257. Audit recommendation referenced; copy intentionally deferred to avoid inventing
  258. positioning claims unsupported by primary sources. -->
  259. ## Benchmarks &amp; Evals
  260. Honcho's evals span LongMemEval, LoCoMo, and other long-conversation benchmarks. See the [evals page](https://honcho.dev/evals/), 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.
  261. ## Self-hosting
  262. Honcho is open source under AGPL-3.0. To **run** a personal instance, install the CLI (`uv tool install honcho-cli`) and then [`honcho start --setup`](#cli). The paths below are for building from source, contributing, or deploying without the CLI.
  263. ### Quick start (from source, Docker)
  264. ```bash
  265. git clone https://github.com/plastic-labs/honcho.git
  266. cd honcho
  267. cp docker-compose.yml.example docker-compose.yml
  268. cp .env.template .env # set LLM_OPENAI_API_KEY (see "LLM provider" below for OpenRouter etc.)
  269. docker compose up
  270. ```
  271. Then point the SDKs at it:
  272. ```python
  273. honcho = Honcho(workspace_id="my-app-testing", base_url="http://localhost:8000")
  274. # or: export HONCHO_URL=http://localhost:8000
  275. ```
  276. <!-- markdownlint-disable MD033 -->
  277. <details>
  278. <summary>Without Docker (manual setup)</summary>
  279. Everything below runs directly on the host — no Docker required. You need:
  280. - [uv](https://docs.astral.sh/uv/) (it installs the required Python, 3.13+, for you)
  281. - PostgreSQL with the [pgvector](https://github.com/pgvector/pgvector) extension, local or managed
  282. - An API key for one LLM provider
  283. Redis is optional; caching is off by default (`CACHE_ENABLED=false`).
  284. 1. **Clone and install**
  285. ```bash
  286. git clone https://github.com/plastic-labs/honcho.git
  287. cd honcho
  288. uv sync
  289. ```
  290. 2. **Set up PostgreSQL with pgvector**
  291. Install Postgres and pgvector natively, then create a `honcho` role and database and enable the extensions in it as a superuser.
  292. On Ubuntu/Debian:
  293. ```bash
  294. # Postgres and pgvector majors must match the distro's packaged version.
  295. # Ubuntu 24.04:
  296. sudo apt install postgresql-16 postgresql-16-pgvector
  297. # Debian 12:
  298. sudo apt install postgresql-15 postgresql-15-pgvector
  299. # Other versions: add the PostgreSQL APT repo (apt.postgresql.org) first.
  300. sudo -u postgres psql -c "CREATE ROLE honcho LOGIN PASSWORD 'honcho';"
  301. sudo -u postgres createdb -O honcho honcho
  302. sudo -u postgres psql -d honcho -c "CREATE EXTENSION IF NOT EXISTS vector;"
  303. sudo -u postgres psql -d honcho -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;" # optional, speeds up message search
  304. ```
  305. On macOS, Homebrew makes your login user the superuser, so drop the `sudo -u postgres`:
  306. ```bash
  307. brew install postgresql@17 pgvector
  308. brew services start postgresql@17
  309. psql -d postgres -c "CREATE ROLE honcho LOGIN PASSWORD 'honcho';"
  310. createdb -O honcho honcho
  311. psql -d honcho -c "CREATE EXTENSION IF NOT EXISTS vector;"
  312. psql -d honcho -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"
  313. ```
  314. A managed Postgres that offers pgvector (Supabase, Neon, RDS, and so on) works too. Enable the same extensions in its database.
  315. 3. **Configure `.env`**
  316. ```bash
  317. cp .env.template .env
  318. ```
  319. Only two settings are required:
  320. ```env
  321. DB_CONNECTION_URI=postgresql+psycopg://honcho:honcho@localhost:5432/honcho
  322. LLM_OPENAI_API_KEY=sk-...
  323. ```
  324. `DB_CONNECTION_URI` must use the `postgresql+psycopg` prefix (a SQLAlchemy requirement).
  325. **LLM provider.** You need one key, not one per vendor. Every feature defaults to `openai / gpt-5.4-mini`, and embeddings default to `openai / text-embedding-3-small`. To use OpenRouter or another OpenAI-compatible endpoint (Together, Fireworks, vLLM, Ollama, LiteLLM), put that provider's key in `LLM_OPENAI_API_KEY` and set the model and base URL on each feature in `.env`:
  326. ```env
  327. LLM_OPENAI_API_KEY=sk-or-v1-...
  328. DERIVER_MODEL_CONFIG__MODEL=google/gemini-2.5-flash
  329. DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1
  330. # ...repeat for DIALECTIC_LEVELS__*, SUMMARY_*, DREAM_*
  331. ```
  332. Models must support tool calling. If your provider doesn't serve embeddings, point `EMBEDDING_MODEL_CONFIG__*` at one that does. See [`.env.template`](./.env.template) for every per-feature line, and the [configuration guide](https://honcho.dev/docs/v3/contributing/configuration#llm-configuration) for direct Anthropic/Gemini keys and mixing providers.
  333. **Auth.** Auth is off by default (`AUTH_USE_AUTH=false`). Turn it on before exposing the server to a network. Enabling it requires a JWT secret, which you can generate with:
  334. ```bash
  335. python scripts/generate_jwt_secret.py
  336. ```
  337. This will generate a JWT secret and print it to the console. You can then set
  338. the `AUTH_JWT_SECRET` environment variable. This is required for `AUTH_USE_AUTH`:
  339. ```env
  340. AUTH_JWT_SECRET=<generated_secret>
  341. ```
  342. Once auth is enabled, use `scripts/generate_jwt.py` to mint tokens for local
  343. development and scripting:
  344. ```bash
  345. # Admin token (full access, no expiry)
  346. uv run python scripts/generate_jwt.py --admin
  347. # Admin token expiring in 24 hours
  348. uv run python scripts/generate_jwt.py --admin --expires 24h
  349. # Admin token for a tenant -- required when MULTI_TENANT is enabled, since a
  350. # token with no tenant claim is rejected for every caller, admin included
  351. uv run python scripts/generate_jwt.py --admin --tenant acme
  352. # Workspace-scoped token
  353. uv run python scripts/generate_jwt.py --workspace my-workspace --expires 30d
  354. # Capture a token for use in curl/scripts
  355. TOKEN=$(uv run python scripts/generate_jwt.py --admin --print-only)
  356. curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/v3/workspaces
  357. ```
  358. Duration units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days), `w` (weeks), `y` (years).
  359. 4. **Run database migrations**
  360. ```bash
  361. uv run alembic upgrade head
  362. ```
  363. Migrations hold a session-level advisory lock, so they need a session-mode connection (direct Postgres or a session pooler), not a transaction-mode pooler. A Supabase-style `:6543` port is rewritten to `:5432` automatically.
  364. 5. **Launch Honcho**
  365. Two processes need to run alongside the database.
  366. **Start the API server:**
  367. ```bash
  368. uv run fastapi dev src/main.py # local development, reloads on code changes
  369. uv run fastapi run --host 0.0.0.0 src/main.py # on a server
  370. ```
  371. **Start a background worker (deriver):**
  372. In a separate terminal, run:
  373. ```bash
  374. uv run python -m src.deriver
  375. ```
  376. The deriver generates representations, summaries, peer cards, and manages dreaming tasks. You can increase the number of derivers to improve runtime efficiency.
  377. For verification steps and production notes, see [Self-hosting docs → Manual Setup](https://honcho.dev/docs/v3/contributing/self-hosting#manual-setup).
  378. </details>
  379. <!-- markdownlint-enable MD033 -->
  380. Contributors: install the git hooks with `uv run pre-commit install --hook-type pre-commit --hook-type commit-msg --hook-type pre-push`. Tests only run at push time, so a clean commit is not a clean push. Deploying to Fly.io: see [Self-hosting docs → Deploying on Fly.io](https://honcho.dev/docs/v3/contributing/self-hosting#deploying-on-fly-io).
  381. ### Multi-tenant mode
  382. `MULTI_TENANT=true` makes one Honcho serve many tenants on one database, with
  383. row-level security scoping every query to the tenant bound on the connection.
  384. Honcho does not create the roles itself; the startup validator checks them and
  385. refuses to boot otherwise. The database needs these roles (the first and the
  386. last may be one role):
  387. - the migration role (`DB_OWNER_CONNECTION_URI`, falling back to
  388. `DB_CONNECTION_URI` when unset), which owns the schema and runs
  389. `alembic upgrade head`, created `WITH LOGIN BYPASSRLS`. Message search runs
  390. through a `SECURITY DEFINER` function owned by this role: the full-text and
  391. `ILIKE` operators are not leakproof, so under RLS the content indexes cannot
  392. serve them, and the function reads as its owner, pinned to the bound tenant. If the function was
  393. created by a role without `BYPASSRLS`, boot fails with the repair:
  394. `ALTER FUNCTION message_text_matches_page(...) OWNER TO <the BYPASSRLS role>`
  395. (the full signature is in the error);
  396. - the app role (`DB_CONNECTION_URI`), an ordinary role with no `BYPASSRLS`, which
  397. every tenant-scoped query runs as. It needs `GRANT EXECUTE ON FUNCTION
  398. message_text_matches_page(...) TO <app role>`, which `alembic upgrade head`
  399. grants with the flag on: EXECUTE is revoked from PUBLIC so no other role can
  400. reach the function's RLS bypass, and boot fails with the exact statement when
  401. the grant is missing;
  402. - the service role (`DB_SERVICE_CONNECTION_URI`), `WITH LOGIN BYPASSRLS`, for the
  403. cross-tenant background work (the deriver claim, the reconciler).
  404. Every tenant table needs `ENABLE` and `FORCE ROW LEVEL SECURITY`, a policy
  405. `USING (tenant_id = current_setting('app.tenant', true)) WITH CHECK (...)`, and
  406. `SELECT, INSERT, UPDATE, DELETE` granted to the app and service roles. With the
  407. flag on, `alembic upgrade head` applies all of that itself after the revisions
  408. run, so a release that adds a tenant table needs nothing by hand; the roles come
  409. from `DB_CONNECTION_URI` and `DB_SERVICE_CONNECTION_URI`. The connection must
  410. not go through a transaction-mode pooler. Self-hosted single-tenant installs
  411. leave the flag off; none of this applies then.
  412. A single-tenant instance can still name the tenant that owns its data with
  413. `TENANT_ID`, with the flag off.
  414. ## Configuration
  415. 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**.
  416. Copy the example file to get started:
  417. ```bash
  418. cp config.toml.example config.toml
  419. ```
  420. The file is organized by subsystem — `[app]`, `[db]`, `[auth]`, `[cache]`, `[llm]`, `[deriver]`, `[dialectic]`, `[summary]`, `[dream]`, `[peer_card]`, `[webhook]`, `[metrics]`, `[telemetry]`, `[vector_store]`, and `[sentry]`. Any value can be overridden by an environment variable named `{SECTION}_{KEY}`, using `__` for nesting (`DIALECTIC_LEVELS__low__MODEL_CONFIG__MODEL`), or just `{KEY}` for app-level settings.
  421. See the [configuration reference](https://honcho.dev/docs/v3/contributing/configuration) for every available option, and [`.env.template`](./.env.template) for an annotated list of environment variables.
  422. ## Architecture
  423. Honcho splits into two services: **Storage** (workspaces, peers, sessions, scopes, 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.
  424. **Key features:**
  425. - **Rich Reasoning System** — multiple implementation methods that extract conclusions from interactions and build comprehensive representations of peers
  426. - **Chat Endpoint** — reasoning-informed responses that integrate conclusions with current context
  427. - **Background Processing** — asynchronous processing pipeline for expensive operations like representation updates and session summarization
  428. - **Multi-Provider Support** — configurable LLM providers for different use cases
  429. <!-- markdownlint-disable MD033 MD001 -->
  430. <details>
  431. <summary>Storage primitives in detail</summary>
  432. Honcho contains several different primitives used for storing application and
  433. peer data. This data is used for managing conversations, modeling peer
  434. identity, building RAG applications, and more.
  435. The philosophy behind Honcho is to provide a platform that is peer-centric and
  436. easily scalable from a single user to a million.
  437. Below is a mapping of the different primitives and their relationships.
  438. ```
  439. Workspaces
  440. ├── Peers ←──────────────────┐
  441. │ ├── Sessions │
  442. │ └── (internal collections, keyed by observer/observed peer pair)
  443. │ │
  444. ├── Scopes ←─────────────────┤ (many-to-many with sessions)
  445. │ │
  446. └── Sessions ←───────────────┤ (many-to-many with peers)
  447. ├── Peers ───────────────┘
  448. └── Messages (session-level)
  449. ```
  450. **Relationship Details:**
  451. - A **Workspace** contains multiple **Peers** and **Scopes**.
  452. - **Peers** and **Sessions** have a many-to-many relationship (peers can participate in multiple sessions, sessions can have multiple peers).
  453. - **Scopes** and **Sessions** have a many-to-many relationship (a session can belong to several scopes; a scope groups many sessions).
  454. - **Messages** belong to a session and are labelled by their source peer.
  455. - **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**.
  456. Users familiar with APIs such as the OpenAI Assistants API will be familiar with
  457. much of the mapping here.
  458. #### Workspaces
  459. This is the top level construct of Honcho. Developers can register different
  460. `Workspaces` for different assistants, agents, AI enabled features, etc. It is a way to
  461. isolate data between use cases and provide multi-tenant capabilities.
  462. #### Peers
  463. Within a `Workspace` everything revolves around a `Peer`. The `Peer` object
  464. represents any participant in the system — whether human users or AI agents.
  465. This unified model enables complex multi-participant interactions.
  466. #### Sessions
  467. The `Session` object represents a set of interactions between `Peers` within a
  468. `Workspace`. Other applications may refer to this as a thread or conversation.
  469. Sessions can involve multiple peers with configurable observation settings.
  470. A session can optionally join one or more **Scopes** at creation, or later via
  471. the scopes API.
  472. #### Scopes
  473. A `Scope` is a named grouping of sessions inside a `Workspace`. It is a
  474. visibility boundary on recall: chat, representation, session context, and
  475. workspace search answered through a scope see only what happened in that
  476. scope's member sessions. The underlying peers keep their unified
  477. representations across everything they have participated in.
  478. Developers manage scopes through the scopes API (`honcho.scope(...)` /
  479. `honcho.scopes()`) and an optional `scopes` field on session create — not
  480. through observer/observed configuration. Adding a session that already has
  481. messages copies its existing explicit conclusions into the scope (no
  482. re-derivation); removing one reconciles those copies back out. Query
  483. backfill progress with the scope `status` endpoint.
  484. A single scope name answers from that scope's collection and card. A list of
  485. scopes restricts recall to the union of their member sessions. Empty scopes
  486. fail closed. `scope` is mutually exclusive with `session` / `filters` on the
  487. same read.
  488. #### Messages
  489. The `Message` represents an atomic data unit that exists at the session level:
  490. communication between peers within a session context. All messages are labelled
  491. by their source peer and can be processed asynchronously to update their
  492. representations. This flexible design allows for both conversational interactions
  493. and broader data ingestion for personality modelling.
  494. </details>
  495. <!-- markdownlint-enable MD033 MD001 -->
  496. <!-- markdownlint-disable MD033 -->
  497. <details>
  498. <summary>Reasoning pipeline</summary>
  499. The reasoning functionality of Honcho is built on top of the Storage service. As
  500. `Messages` and `Sessions` are created for `Peers`, Honcho will asynchronously
  501. reason about peer psychology to derive facts about them and store them
  502. in reserved internal collections.
  503. A high level summary of the pipeline is as follows:
  504. 1. Messages are created via the API.
  505. 2. Derivation tasks are enqueued for background processing, including:
  506. - `representation`: update representations of `Peers`.
  507. - `summary`: create summaries of `Sessions`.
  508. 3. Session-based queue processing ensures proper ordering.
  509. 4. Results are stored internally and surfaced via the Conclusions API, Representations, Peer Cards, and the Chat Endpoint.
  510. </details>
  511. <!-- markdownlint-enable MD033 -->
  512. <!-- markdownlint-disable MD033 MD001 -->
  513. <details>
  514. <summary>Retrieving data and insights</summary>
  515. Honcho exposes several different ways to retrieve data from the system to best
  516. serve the needs of any given application.
  517. #### Get Context
  518. In long-running conversations with an LLM, the context window can fill up
  519. quickly. To address this, Honcho provides a `context`
  520. endpoint that returns a combination of messages, conclusions, summaries from a
  521. session up to a provided token limit.
  522. Use this to keep sessions going indefinitely. If you'd like to see this in action, try out [Honcho Chat](https://honcho.chat).
  523. #### Search
  524. There are several search endpoints that let developers query messages at the
  525. `Workspace`, `Session`, or `Peer` level using a hybrid search strategy.
  526. Requests can include advanced filters to further refine
  527. the results.
  528. #### Chat API
  529. The flagship interface for using these insights is the [Chat Endpoint](https://honcho.dev/docs/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:
  530. - Asking Honcho for a generic or specific insight about the peer.
  531. - Asking Honcho to hydrate a prompt with data about the peer's behaviour.
  532. - Asking Honcho for a second opinion on how to respond.
  533. - Getting personalised responses that incorporate long-term facts and context.
  534. #### Representations
  535. 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.
  536. </details>
  537. <!-- markdownlint-enable MD033 MD001 -->
  538. ## SDKs
  539. - **Python** — [`honcho-ai`](https://pypi.org/project/honcho-ai/) on PyPI · source in [`sdks/python/`](./sdks/python)
  540. - **TypeScript** — [`@honcho-ai/sdk`](https://www.npmjs.com/package/@honcho-ai/sdk) on npm · source in [`sdks/typescript/`](./sdks/typescript)
  541. - **CLI** — [`honcho-cli`](https://pypi.org/project/honcho-cli/) on PyPI · source in [`honcho-cli/`](./honcho-cli) · [CLI reference](https://honcho.dev/docs/v3/documentation/reference/cli)
  542. SDKs are versioned independently of the server. Current SDK versions track each other; the server badge above reflects the deployed server version.
  543. See the [SDK Reference](https://honcho.dev/docs/v3/documentation/reference/sdk) for full API surface, the [API Reference](https://honcho.dev/docs/v3/api-reference/introduction) for the raw HTTP API, and per-SDK example folders for runnable demos.
  544. ## Learn More
  545. - [Developer documentation](https://honcho.dev/docs/) — full API surface, guides, integrations.
  546. - [CLI reference](https://honcho.dev/docs/v3/documentation/reference/cli) — local stack, inspect/debug commands, scripting.
  547. - [Plastic Labs blog](https://blog.plasticlabs.ai/) — design philosophy and history of the project.
  548. ## Contributing
  549. **Pull requests are limited to maintainers.** If you find a bug or want a change, please [open an issue](https://github.com/plastic-labs/honcho/issues/new/choose) instead. If you think your work is an exception, make the case in [Discord](http://discord.gg/honcho), where maintainers are most active.
  550. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full process, an architecture walkthrough, and a map of where to change what. For vulnerabilities, see [SECURITY.md](./SECURITY.md) — note that Honcho does not operate a bug bounty.
  551. ## License
  552. Honcho is licensed under the AGPL-3.0 License. Learn more at the [License file](./LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.