Kass/readme refresh (#681)
* 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.
* docs(readme): restore "stateful agents" in opening sentence
Plastic Labs' canonical positioning uses "stateful agents" across
materials, and the original README opened with "for building stateful
agents." The repositioning pass in d6d60435 dropped the term entirely
(now zero occurrences) by following Vineeth's suggested opening copy
verbatim - but his audit's executive summary explicitly praised the
"stateful agents" positioning and didn't ask to remove it. Restoring
it in the bolded thesis sentence.
* docs(readme): drop self-referential "observations" in Conclusions bullet
The Conclusions definition shouldn't define itself in terms of
"observations." Per Plastic's positioning, "conclusions" is the
documentation-facing name for what the Deriver produces;
"observations" remains the internal code symbol. The README's
two remaining "observations" references (inside the <details>
Internal storage block and the Storage primitives block) are
explicit code-internal framing and stay.
* docs(readme): restore content dropped without audit instruction
Self-audit against Vineeth's audit found seven items I'd dropped that weren't in the audit's instructions to drop: outcome-marketing line, Contents TOC (audit said rename, not remove), multi-repo prose, org-onboarding detail, peer-paradigm feature bullets, Architecture "Key Features" bullets, and Learn More pointers. Also fixes two residual "Dialectic API" → "Chat Endpoint" mentions the original P0 sweep missed.
* docs(readme): add "Why Honcho" capability table + agent-skill onboarding
Closes the two gaps flagged in the freshness/repositioning audit: adds Vineeth's recommended "Why Honcho" capability table between Start Here and The Honcho Loop, and adds the `npx skills add plastic-labs/honcho` + `/honcho-integration` agent-skill path as a subsection of Integrations (verified against current docs).
* docs: split contributor-only sections out of README; trust auth for local postgres
- Move pre-commit hooks setup from README to CONTRIBUTING.md (pure
contributor content; the README still links to it).
- Move Fly.io deployment notes from README to the self-hosting docs.
- Wrap remaining <details>/<summary> blocks with markdownlint
disable/enable to clear pre-existing MD033/MD001 failures.
- Add POSTGRES_HOST_AUTH_METHOD=trust to the example compose template
with an inline warning, so host-side tests and tooling can connect
without supplying a password.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix: (docs) update docs and evals urls and split pre-commit into contributing docs
---------
Co-authored-by: Vineeth Voruganti <13438633+VVoruganti@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Marianne
GitHub
parent
092b60520f
commit
a1895e9ecc
|
|
@ -102,7 +102,7 @@ Based on interview responses, implement the integration:
|
|||
|
||||
## Before You Start
|
||||
|
||||
1. **Check the latest SDK versions** at <https://docs.honcho.dev/changelog/introduction>
|
||||
1. **Check the latest SDK versions** at <https://honcho.dev/docs/changelog/introduction>
|
||||
- Python SDK: `honcho-ai`
|
||||
- TypeScript SDK: `@honcho-ai/sdk`
|
||||
|
||||
|
|
@ -549,6 +549,6 @@ When integrating Honcho into an existing codebase:
|
|||
|
||||
## Resources
|
||||
|
||||
- Documentation: <https://docs.honcho.dev>
|
||||
- Latest SDK versions: <https://docs.honcho.dev/changelog/introduction>
|
||||
- API Reference: <https://docs.honcho.dev/v3/api-reference/introduction>
|
||||
- Documentation: <https://honcho.dev/docs>
|
||||
- Latest SDK versions: <https://honcho.dev/docs/changelog/introduction>
|
||||
- API Reference: <https://honcho.dev/docs/v3/api-reference/introduction>
|
||||
|
|
|
|||
|
|
@ -101,6 +101,45 @@ git commit -m "docs(readme): update installation instructions"
|
|||
- Any relevant issue numbers (use "Closes #123" to auto-close issues)
|
||||
- Screenshots or examples if applicable
|
||||
|
||||
## Pre-commit Hooks
|
||||
|
||||
Honcho uses pre-commit hooks to enforce code quality and consistency. They run linting, formatting, type checking, and security scans before each commit.
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
uv add --dev pre-commit
|
||||
uv run pre-commit install \
|
||||
--hook-type pre-commit \
|
||||
--hook-type commit-msg \
|
||||
--hook-type pre-push
|
||||
```
|
||||
|
||||
### What the hooks do
|
||||
|
||||
- **Code Quality** — Python linting and formatting (ruff), TypeScript linting (biome)
|
||||
- **Type Checking** — Static analysis with basedpyright
|
||||
- **Security** — Vulnerability scanning with bandit
|
||||
- **Documentation** — Markdown linting and license header checks
|
||||
- **Testing** — Automated test runs for Python and TypeScript
|
||||
- **File Hygiene** — Trailing whitespace, line endings, file size checks
|
||||
- **Commit Standards** — Conventional commit message validation
|
||||
|
||||
### Manual execution
|
||||
|
||||
Run against all files without committing:
|
||||
|
||||
```bash
|
||||
uv run pre-commit run --all-files
|
||||
```
|
||||
|
||||
Run a specific hook:
|
||||
|
||||
```bash
|
||||
uv run pre-commit run ruff --all-files
|
||||
uv run pre-commit run basedpyright --all-files
|
||||
```
|
||||
|
||||
## Coding Standards
|
||||
|
||||
### Python Code Style
|
||||
|
|
|
|||
652
README.md
652
README.md
|
|
@ -8,164 +8,303 @@
|
|||
|
||||
---
|
||||
|
||||
|
||||
|
||||
[](https://pypi.org/project/honcho-ai/)
|
||||
[](https://npmjs.org/package/@honcho-ai/sdk)
|
||||
[](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 building stateful agents that understand changing people, agents, groups, projects, and ideas over time.**
|
||||
|
||||
> 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.
|
||||
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.
|
||||
|
||||
## TL;DR - Getting Started
|
||||
Using Honcho as your memory system will earn your agents higher retention, more trust, and help you build data moats to out-compete incumbents.
|
||||
|
||||
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
|
||||
> 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.
|
||||
|
||||
> Typescript examples are available in our [docs](https://docs.honcho.dev).
|
||||
## Contents
|
||||
|
||||
1. Install the SDK
|
||||
|
||||
```bash
|
||||
# Python
|
||||
pip install honcho-ai
|
||||
uv add honcho-ai
|
||||
poetry add honcho-ai
|
||||
```
|
||||
|
||||
2. Setup your `Workspace`, `Peers`, `Session`, and send `Messages`
|
||||
|
||||
```python
|
||||
from honcho import Honcho
|
||||
|
||||
# 1. Initialize your Honcho client
|
||||
honcho = Honcho(workspace_id="my-app-testing")
|
||||
|
||||
# 2. Initialize peers
|
||||
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!"),
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
3. Leverage reasoning from Honcho to inform your agent's behavior
|
||||
|
||||
```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
|
||||
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)
|
||||
|
||||
from openai import OpenAI
|
||||
client = OpenAI()
|
||||
response = client.chat.completions.create(
|
||||
model="gpt-4",
|
||||
messages=openai_messages
|
||||
)
|
||||
|
||||
### 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.
|
||||
|
||||
Sign up at [app.honcho.dev](https://app.honcho.dev) to get started with a managed version of Honcho.
|
||||
|
||||
Learn more ways to use Honcho on our [developer docs](https://docs.honcho.dev).
|
||||
|
||||
Read about the design philosophy and history of the project on our [blog](https://blog.plasticlabs.ai/).
|
||||
|
||||
## Project Structure
|
||||
|
||||
- [Usage](#usage)
|
||||
- [Local Development](#local-development)
|
||||
- [Prerequisites and Dependencies](#prerequisites-and-dependencies)
|
||||
- [Setup](#setup)
|
||||
- [Docker](#docker)
|
||||
- [Deploy on Fly](#deploy-on-fly)
|
||||
- [Start Here](#start-here)
|
||||
- [Why Honcho](#why-honcho)
|
||||
- [The Honcho Loop](#the-honcho-loop)
|
||||
- [Quickstart](#quickstart)
|
||||
- [What Honcho Gives You](#what-honcho-gives-you)
|
||||
- [Integrations](#integrations)
|
||||
- [Core Concepts](#core-concepts)
|
||||
- [Benchmarks & Evals](#benchmarks--evals)
|
||||
- [Self-hosting](#self-hosting)
|
||||
- [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)
|
||||
- [SDKs](#sdks)
|
||||
- [Learn More](#learn-more)
|
||||
- [Contributing](#contributing)
|
||||
- [License](#license)
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
There are also client SDKs implemented in the `sdks/` directory with support
|
||||
for Python and TypeScript.
|
||||
## Start Here
|
||||
|
||||
- [Python](https://pypi.org/project/honcho-ai/)
|
||||
- [TypeScript](https://www.npmjs.com/package/@honcho-ai/sdk)
|
||||
| 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) |
|
||||
|
||||
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)
|
||||
## Why Honcho
|
||||
|
||||
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.
|
||||
| Capability | What it means |
|
||||
|---|---|
|
||||
| Reasoning-first memory | Extracts conclusions from conversations and events, not just matching chunks. |
|
||||
| Peer-centric model | Tracks users, agents, groups, projects, and ideas as entities that change over time. |
|
||||
| Multi-peer perspective | Models what one peer knows about another when configured. |
|
||||
| Managed or self-hosted | Use `api.honcho.dev` or run the FastAPI server yourself. |
|
||||
| Agent-tool integrations | MCP, Claude Code, OpenCode, OpenClaw, Hermes, Cursor-compatible clients. |
|
||||
|
||||
## Usage
|
||||
## The Honcho Loop
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Provision API keys and change your base url to point to
|
||||
[https://api.honcho.dev](https://api.honcho.dev)
|
||||
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.
|
||||
|
||||
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.
|
||||
## Quickstart
|
||||
|
||||
## Local Development
|
||||
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 and $100 free credits. Or [self-host](#self-hosting) and run against `http://localhost:8000`.
|
||||
|
||||
Below is a guide on setting up a local environment for running the Honcho
|
||||
Server.
|
||||
### Python
|
||||
|
||||
> This guide was made using a M3 Macbook Pro. For any compatibility issues
|
||||
> on different platforms, please raise an Issue.
|
||||
```bash
|
||||
pip install honcho-ai
|
||||
# or: uv add honcho-ai
|
||||
# or: poetry add honcho-ai
|
||||
```
|
||||
|
||||
### Prerequisites and Dependencies
|
||||
```python
|
||||
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
|
||||
|
||||
```bash
|
||||
npm install @honcho-ai/sdk
|
||||
# or: bun add @honcho-ai/sdk
|
||||
```
|
||||
|
||||
```typescript
|
||||
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 Honcho Gives You
|
||||
|
||||
| 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(...)` |
|
||||
|
||||
See the full [SDK Reference](https://honcho.dev/docs/v3/documentation/reference/sdk) and [API Reference](https://honcho.dev/docs/v3/api-reference/introduction).
|
||||
|
||||
## Integrations
|
||||
|
||||
### Claude Code
|
||||
|
||||
Two ways, depending on how deep you want to go:
|
||||
|
||||
**Plugin (richer integration — recommended for Claude Code users):**
|
||||
|
||||
```text
|
||||
/plugin marketplace add plastic-labs/claude-honcho
|
||||
/plugin install honcho@honcho
|
||||
```
|
||||
|
||||
**Raw MCP (works in any MCP client — Cursor, Cline, Windsurf, etc.):**
|
||||
|
||||
```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"
|
||||
```
|
||||
|
||||
Details: [Claude Code guide](https://honcho.dev/docs/v3/guides/integrations/claude-code) · [MCP guide](https://honcho.dev/docs/v3/guides/integrations/mcp).
|
||||
|
||||
### OpenCode
|
||||
|
||||
```bash
|
||||
opencode plugin "@honcho-ai/opencode-honcho" --global
|
||||
```
|
||||
|
||||
Details: [OpenCode guide](https://honcho.dev/docs/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://honcho.dev/docs/v3/guides/integrations/openclaw).
|
||||
|
||||
### Hermes
|
||||
|
||||
```bash
|
||||
hermes memory setup # select "honcho", point at api.honcho.dev or your local server
|
||||
```
|
||||
|
||||
Details: [Hermes guide](https://honcho.dev/docs/v3/guides/integrations/hermes).
|
||||
|
||||
### Add Honcho to your own codebase (agent skill)
|
||||
|
||||
For wiring the Honcho SDK into an existing application, install the integration skill — it explores your codebase, asks about integration preferences, generates the SDK setup, and verifies it works:
|
||||
|
||||
```bash
|
||||
npx skills add plastic-labs/honcho
|
||||
```
|
||||
|
||||
Then invoke `/honcho-integration` in Claude Code (or `/honcho-dev:integrate` via the plugin marketplace). Details: [agentic development guide](https://honcho.dev/docs/v3/documentation/introduction/vibecoding).
|
||||
|
||||
### Other MCP clients
|
||||
|
||||
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).
|
||||
|
||||
## Core Concepts
|
||||
|
||||
Honcho organises everything around **peers** — humans and AI agents alike are first-class entities. The peer model enables:
|
||||
|
||||
- Multi-participant sessions with mixed human and AI agents
|
||||
- Configurable observation settings (which peers observe which others)
|
||||
- Flexible identity management for all participants
|
||||
- Support for complex multi-agent interactions
|
||||
|
||||
Peers exchange messages within sessions; Honcho reasons over those messages to build a representation of each peer that you can query.
|
||||
|
||||
- **Workspace** (formerly App): top-level container; isolates data between use cases.
|
||||
- **Peer** (formerly User): any participant — human user or AI agent.
|
||||
- **Session**: a conversation context; many-to-many with peers.
|
||||
- **Message**: an atomic data unit (peer-to-peer communication or ingested document chunk).
|
||||
|
||||
What you query out of Honcho:
|
||||
|
||||
- **Conclusions** — what Honcho has extracted about a peer (deductive and inductive). Exposed via the [conclusions API](https://honcho.dev/docs/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.
|
||||
|
||||
<!-- markdownlint-disable MD033 -->
|
||||
<details>
|
||||
<summary>Internal storage (Collections & 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>
|
||||
<!-- markdownlint-enable MD033 -->
|
||||
|
||||
<!-- 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 & Evals
|
||||
|
||||
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.
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
<!-- markdownlint-disable MD033 -->
|
||||
<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/).
|
||||
|
||||
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,108 +425,20 @@ 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
|
||||
</details>
|
||||
<!-- markdownlint-enable MD033 -->
|
||||
|
||||
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.
|
||||
|
||||
#### Installation
|
||||
|
||||
To set up pre-commit hooks in your development environment:
|
||||
|
||||
1. **Install pre-commit using uv**
|
||||
|
||||
```bash
|
||||
uv add --dev pre-commit
|
||||
```
|
||||
|
||||
2. **Install the pre-commit hooks**
|
||||
|
||||
```bash
|
||||
uv run pre-commit install \
|
||||
--hook-type pre-commit \
|
||||
--hook-type commit-msg \
|
||||
--hook-type pre-push
|
||||
```
|
||||
|
||||
This will install hooks for `pre-commit`, `commit-msg`, and `pre-push` stages.
|
||||
|
||||
#### What the hooks do
|
||||
|
||||
The pre-commit configuration includes:
|
||||
|
||||
- **Code Quality**: Python linting and formatting (ruff), TypeScript linting (biome)
|
||||
- **Type Checking**: Static type analysis with basedpyright
|
||||
- **Security**: Vulnerability scanning with bandit
|
||||
- **Documentation**: Markdown linting and license header checks
|
||||
- **Testing**: Automated test runs for Python and TypeScript code
|
||||
- **File Hygiene**: Trailing whitespace, line endings, file size checks
|
||||
- **Commit Standards**: Conventional commit message validation
|
||||
|
||||
#### Manual execution
|
||||
|
||||
You can run the hooks manually on all files without making a commit:
|
||||
|
||||
```bash
|
||||
uv run pre-commit run --all-files
|
||||
```
|
||||
|
||||
Or run specific hooks:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
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
|
||||
`flyctl`.
|
||||
|
||||
A sample `fly.toml` is included for convenience.
|
||||
|
||||
> Note: The fly.toml does not include launching a Postgres database. This must
|
||||
> be configured separately
|
||||
|
||||
Once `flyctl` is set up use the following commands to launch the application:
|
||||
|
||||
```bash
|
||||
cd honcho
|
||||
flyctl launch --no-deploy # Follow the prompts and edit as you see fit
|
||||
cat .env | flyctl secrets import # Load in your secrets
|
||||
flyctl deploy # Deploy with appropriate environment variables
|
||||
```
|
||||
Contributors: see [`CONTRIBUTING.md`](./CONTRIBUTING.md) for pre-commit setup. Deploying to Fly.io: see [Self-hosting docs → Deploying on Fly.io](https://honcho.dev/docs/v3/contributing/self-hosting#deploying-on-fly-io).
|
||||
|
||||
## 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
|
||||
<!-- markdownlint-disable MD033 -->
|
||||
<details>
|
||||
<summary>Full configuration reference</summary>
|
||||
|
||||
### Using config.toml
|
||||
|
||||
|
|
@ -406,7 +457,7 @@ Then modify the values as needed. The TOML file is organized into sections:
|
|||
- `[llm]` - LLM provider API keys and general settings
|
||||
- `[deriver]` - Background worker settings and representation configuration
|
||||
- `[peer_card]` - Peer card generation settings
|
||||
- `[dialectic]` - Dialectic API configuration with per-level reasoning settings
|
||||
- `[dialectic]` - Chat Endpoint configuration with per-level reasoning settings
|
||||
- `[summary]` - Session summarization settings
|
||||
- `[dream]` - Dream processing configuration (including specialist models and surprisal settings)
|
||||
- `[webhook]` - Webhook configuration
|
||||
|
|
@ -434,21 +485,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 +503,23 @@ 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.
|
||||
|
||||
</details>
|
||||
<!-- markdownlint-enable MD033 -->
|
||||
|
||||
## 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
|
||||
**Key features:**
|
||||
|
||||
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:
|
||||
- **Rich Reasoning System** — multiple implementation methods that extract conclusions from interactions and build comprehensive representations of peers
|
||||
- **Chat Endpoint** — 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
|
||||
|
||||
- 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
|
||||
<!-- markdownlint-disable MD033 MD001 -->
|
||||
<details>
|
||||
<summary>Storage primitives in detail</summary>
|
||||
|
||||
Honcho contains several different primitives used for storing application and
|
||||
peer data. This data is used for managing conversations, modeling peer
|
||||
|
|
@ -503,8 +534,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 +544,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 +561,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 +572,39 @@ 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
|
||||
</details>
|
||||
<!-- markdownlint-enable MD033 MD001 -->
|
||||
|
||||
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
|
||||
<!-- markdownlint-disable MD033 -->
|
||||
<details>
|
||||
<summary>Reasoning pipeline</summary>
|
||||
|
||||
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
|
||||
</details>
|
||||
<!-- markdownlint-enable MD033 -->
|
||||
|
||||
<!-- markdownlint-disable MD033 MD001 -->
|
||||
<details>
|
||||
<summary>Retrieving data and insights</summary>
|
||||
|
||||
Honcho exposes several different ways to retrieve data from the system to best
|
||||
serve the needs of any given application.
|
||||
|
|
@ -606,31 +628,33 @@ 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://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:
|
||||
|
||||
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.
|
||||
</details>
|
||||
<!-- markdownlint-enable MD033 MD001 -->
|
||||
|
||||
## 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://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.
|
||||
|
||||
## Learn More
|
||||
|
||||
- [Developer documentation](https://honcho.dev/docs/) — full API surface, guides, integrations.
|
||||
- [Plastic Labs blog](https://blog.plasticlabs.ai/) — design philosophy and history of the project.
|
||||
|
||||
## Contributing
|
||||
|
||||
|
|
@ -638,4 +662,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).
|
||||
|
|
|
|||
|
|
@ -67,6 +67,10 @@ services:
|
|||
- POSTGRES_DB=postgres
|
||||
- POSTGRES_USER=postgres
|
||||
- POSTGRES_PASSWORD=postgres
|
||||
# Allow passwordless connections from the host (port is bound to 127.0.0.1).
|
||||
# Lets the local test suite and ad-hoc tools connect without supplying a
|
||||
# password. Do NOT use this in production.
|
||||
- POSTGRES_HOST_AUTH_METHOD=trust
|
||||
- PGDATA=/var/lib/postgresql/data/pgdata
|
||||
volumes:
|
||||
- ./database/init.sql:/docker-entrypoint-initdb.d/init.sql
|
||||
|
|
|
|||
|
|
@ -25,10 +25,10 @@ I want to start building with Honcho - a memory and personalization platform for
|
|||
## Honcho Resources
|
||||
|
||||
**Documentation:**
|
||||
- Main docs: https://docs.honcho.dev
|
||||
- API Reference: https://docs.honcho.dev/v2/api-reference/introduction
|
||||
- Quickstart: https://docs.honcho.dev/v2/documentation/introduction/quickstart
|
||||
- Architecture: https://docs.honcho.dev/v2/documentation/reference/architecture
|
||||
- Main docs: https://honcho.dev/docs
|
||||
- API Reference: https://honcho.dev/docs/v2/api-reference/introduction
|
||||
- Quickstart: https://honcho.dev/docs/v2/documentation/introduction/quickstart
|
||||
- Architecture: https://honcho.dev/docs/v2/documentation/reference/architecture
|
||||
|
||||
**Code & Examples:**
|
||||
- Core repo: https://github.com/plastic-labs/honcho
|
||||
|
|
|
|||
|
|
@ -97,7 +97,7 @@ results = storage.search("query", filters={
|
|||
})
|
||||
```
|
||||
|
||||
For the full filter syntax including logical operators (AND, OR, NOT), comparison operators, and metadata filtering, see the [Using Filters](https://docs.honcho.dev/v2/documentation/core-concepts/features/using-filters) documentation.
|
||||
For the full filter syntax including logical operators (AND, OR, NOT), comparison operators, and metadata filtering, see the [Using Filters](https://honcho.dev/docs/v2/documentation/core-concepts/features/using-filters) documentation.
|
||||
|
||||
<Note>
|
||||
For comprehensive details about CrewAI's memory system, see the [official CrewAI Memory documentation](https://docs.crewai.com/en/concepts/memory).
|
||||
|
|
|
|||
|
|
@ -395,4 +395,20 @@ The default compose file is already production-oriented — ports bound to `127.
|
|||
# Restore
|
||||
cat backup.sql | docker compose exec -T database psql -U postgres postgres
|
||||
```
|
||||
|
||||
## Deploying on Fly.io
|
||||
|
||||
The API can be deployed on [Fly.io](https://fly.io). Follow the [Fly.io getting-started docs](https://fly.io/docs/getting-started/) to set up your account and install `flyctl`. A sample `fly.toml` is included in the repo for convenience.
|
||||
|
||||
<Note>
|
||||
The included `fly.toml` does not provision a PostgreSQL database. Stand one up separately (Fly Postgres, Supabase, Neon, or another managed provider) and set `DB_CONNECTION_URI` to point at it.
|
||||
</Note>
|
||||
|
||||
Once `flyctl` is set up, from the repo root:
|
||||
|
||||
```bash
|
||||
flyctl launch --no-deploy # follow the prompts and edit as you see fit
|
||||
cat .env | flyctl secrets import # load secrets from .env
|
||||
flyctl deploy # deploy
|
||||
```
|
||||
- Back up your `.env` or `config.toml` configuration files
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ sidebarTitle: "Overview"
|
|||
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.
|
||||
|
||||
<Note>
|
||||
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://honcho.dev/evals/), and read the [blog post](https://blog.plasticlabs.ai/research/Benchmarking-Honcho) for more detail.
|
||||
</Note>
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
|
|
|||
|
|
@ -244,7 +244,7 @@ This is rich personal context for domain-specific agents to do what they want wi
|
|||
- A productivity agent might see the same pattern and say "let's protect your weekend time for the finance app."
|
||||
- A financial advisor agent might see it and ask "what runway would you need to make the leap?"
|
||||
|
||||
Honcho acts almost like a detective--it reasons about new and existing evidence in order to form conclusions that can be used to make a *case*. These conclusions wait to be composed dynamically based on how you, the ~~judge~~ developer, query it. This approach is what drives our [pareto-frontier](https://evals.honcho.dev) performance on memory benchmarks, and our custom models allow us to optimize speed and cost.
|
||||
Honcho acts almost like a detective--it reasons about new and existing evidence in order to form conclusions that can be used to make a *case*. These conclusions wait to be composed dynamically based on how you, the ~~judge~~ developer, query it. This approach is what drives our [pareto-frontier](https://honcho.dev/evals) performance on memory benchmarks, and our custom models allow us to optimize speed and cost.
|
||||
|
||||
|
||||
## Next Steps
|
||||
|
|
|
|||
|
|
@ -167,10 +167,10 @@ I want to start building with Honcho - an open source memory library for buildin
|
|||
## Honcho Resources
|
||||
|
||||
**Documentation:**
|
||||
- Main docs: https://docs.honcho.dev
|
||||
- API Reference: https://docs.honcho.dev/v3/api-reference/introduction
|
||||
- Quickstart: https://docs.honcho.dev/v3/documentation/introduction/quickstart
|
||||
- Architecture: https://docs.honcho.dev/v3/documentation/core-concepts/architecture
|
||||
- Main docs: https://honcho.dev/docs
|
||||
- API Reference: https://honcho.dev/docs/v3/api-reference/introduction
|
||||
- Quickstart: https://honcho.dev/docs/v3/documentation/introduction/quickstart
|
||||
- Architecture: https://honcho.dev/docs/v3/documentation/core-concepts/architecture
|
||||
|
||||
**Code & Examples:**
|
||||
- Core repo: https://github.com/plastic-labs/honcho
|
||||
|
|
|
|||
|
|
@ -97,7 +97,7 @@ results = storage.search("query", filters={
|
|||
})
|
||||
```
|
||||
|
||||
For the full filter syntax including logical operators (AND, OR, NOT), comparison operators, and metadata filtering, see the [Using Filters](https://docs.honcho.dev/v3/documentation/features/advanced/using-filters) documentation.
|
||||
For the full filter syntax including logical operators (AND, OR, NOT), comparison operators, and metadata filtering, see the [Using Filters](https://honcho.dev/docs/v3/documentation/features/advanced/using-filters) documentation.
|
||||
|
||||
<Note>
|
||||
For comprehensive details about CrewAI's memory system, see the [official CrewAI Memory documentation](https://docs.crewai.com/en/concepts/memory).
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ crew = Crew(
|
|||
## Documentation
|
||||
|
||||
For comprehensive guides, examples, and API reference, visit:
|
||||
**[https://docs.honcho.dev/v3/integrations/crewai](https://docs.honcho.dev/v3/integrations/crewai)**
|
||||
**[https://honcho.dev/docs/v3/integrations/crewai](https://honcho.dev/docs/v3/integrations/crewai)**
|
||||
|
||||
## Examples
|
||||
|
||||
|
|
@ -58,5 +58,5 @@ AGPL-3.0-or-later
|
|||
## Support
|
||||
|
||||
- Report issues: [GitHub Issues](https://github.com/plastic-labs/honcho/issues)
|
||||
- Documentation: [docs.honcho.dev](https://docs.honcho.dev)
|
||||
- Documentation: [honcho.dev/docs](https://honcho.dev/docs)
|
||||
- Website: [honcho.dev](https://honcho.dev)
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ dependencies = [
|
|||
|
||||
[project.urls]
|
||||
Homepage = "https://honcho.dev"
|
||||
Documentation = "https://docs.honcho.dev/v3/integrations/crewai"
|
||||
Documentation = "https://honcho.dev/docs/v3/integrations/crewai"
|
||||
Repository = "https://github.com/plastic-labs/honcho"
|
||||
"Bug Tracker" = "https://github.com/plastic-labs/honcho/issues"
|
||||
Changelog = "https://github.com/plastic-labs/honcho/blob/main/CHANGELOG.md"
|
||||
|
|
|
|||
|
|
@ -125,7 +125,7 @@ class HonchoStorage(Storage):
|
|||
including logical operators (AND, OR, NOT), comparison operators
|
||||
(gt, gte, lt, lte, eq, ne), and metadata filtering.
|
||||
Example: {"peer_id": "user123"} or {"metadata": {"type": "important"}}
|
||||
See: https://docs.honcho.dev/v3/documentation/core-concepts/features/using-filters
|
||||
See: https://honcho.dev/docs/v3/documentation/core-concepts/features/using-filters
|
||||
|
||||
Returns:
|
||||
List of message dictionaries in CrewAI expected format.
|
||||
|
|
|
|||
|
|
@ -159,6 +159,6 @@ Apache 2.0 - see [LICENSE](../../LICENSE) for details.
|
|||
|
||||
## Support
|
||||
|
||||
- [Documentation](https://docs.honcho.dev)
|
||||
- [Documentation](https://honcho.dev/docs)
|
||||
- [GitHub Issues](https://github.com/plastic-labs/honcho/issues)
|
||||
- [Discord Community](https://discord.gg/honcho)
|
||||
|
|
|
|||
|
|
@ -553,7 +553,7 @@ class Honcho(BaseModel, MetadataConfigMixin): # pyright: ignore[reportUnsafeMul
|
|||
|
||||
Args:
|
||||
query: The search query to use
|
||||
filters: Filters to scope the search. See [search filters documentation](https://docs.honcho.dev/v3/documentation/core-concepts/features/using-filters).
|
||||
filters: Filters to scope the search. See [search filters documentation](https://honcho.dev/docs/v3/documentation/core-concepts/features/using-filters).
|
||||
limit: Number of results to return (1-100, default: 10)
|
||||
|
||||
Returns:
|
||||
|
|
|
|||
|
|
@ -473,7 +473,7 @@ class Peer(PeerBase, MetadataConfigMixin):
|
|||
|
||||
Args:
|
||||
query: The search query to use
|
||||
filters: Filters to scope the search. See [search filters documentation](https://docs.honcho.dev/v3/documentation/core-concepts/features/using-filters).
|
||||
filters: Filters to scope the search. See [search filters documentation](https://honcho.dev/docs/v3/documentation/core-concepts/features/using-filters).
|
||||
limit: Number of results to return (1-100, default: 10)
|
||||
|
||||
Returns:
|
||||
|
|
|
|||
|
|
@ -771,7 +771,7 @@ class Session(SessionBase, MetadataConfigMixin):
|
|||
|
||||
Args:
|
||||
query: The search query to use
|
||||
filters: Filters to scope the search. See [search filters documentation](https://docs.honcho.dev/v3/documentation/core-concepts/features/using-filters).
|
||||
filters: Filters to scope the search. See [search filters documentation](https://honcho.dev/docs/v3/documentation/core-concepts/features/using-filters).
|
||||
limit: Number of results to return (1-100, default: 10)
|
||||
|
||||
Returns:
|
||||
|
|
|
|||
|
|
@ -416,7 +416,7 @@ export class Honcho {
|
|||
*
|
||||
* @param options - Either a legacy raw filter object or an options object with
|
||||
* `filters`, `page`, `size`, and `reverse`. See
|
||||
* [search filters documentation](https://docs.honcho.dev/v3/documentation/core-concepts/features/using-filters).
|
||||
* [search filters documentation](https://honcho.dev/docs/v3/documentation/core-concepts/features/using-filters).
|
||||
* @returns Promise resolving to a Page of Peer objects representing all peers in the workspace
|
||||
*/
|
||||
async peers(
|
||||
|
|
@ -537,7 +537,7 @@ export class Honcho {
|
|||
*
|
||||
* @param options - Either a legacy raw filter object or an options object with
|
||||
* `filters`, `page`, `size`, and `reverse`. See
|
||||
* [search filters documentation](https://docs.honcho.dev/v3/documentation/core-concepts/features/using-filters).
|
||||
* [search filters documentation](https://honcho.dev/docs/v3/documentation/core-concepts/features/using-filters).
|
||||
* @returns Promise resolving to a Page of Session objects representing all sessions
|
||||
* in the workspace. Returns an empty page if no sessions exist
|
||||
*/
|
||||
|
|
@ -692,7 +692,7 @@ export class Honcho {
|
|||
*
|
||||
* @param options - Either a legacy raw filter object or an options object with
|
||||
* `filters`, `page`, and `size`. See
|
||||
* [search filters documentation](https://docs.honcho.dev/v3/documentation/core-concepts/features/using-filters).
|
||||
* [search filters documentation](https://honcho.dev/docs/v3/documentation/core-concepts/features/using-filters).
|
||||
* @returns Promise resolving to a Page of workspace ID strings. Returns an empty
|
||||
* page if no workspaces are accessible or none exist
|
||||
*/
|
||||
|
|
@ -751,7 +751,7 @@ export class Honcho {
|
|||
* Makes an API call to search for messages in the current workspace.
|
||||
*
|
||||
* @param query - The search query to use
|
||||
* @param filters - Optional filters to scope the search. See [search filters documentation](https://docs.honcho.dev/v3/documentation/core-concepts/features/using-filters).
|
||||
* @param filters - Optional filters to scope the search. See [search filters documentation](https://honcho.dev/docs/v3/documentation/core-concepts/features/using-filters).
|
||||
* @param limit - Number of results to return (1-100, default: 10).
|
||||
* @returns Promise resolving to an array of Message objects representing the search results.
|
||||
* Returns an empty array if no messages are found.
|
||||
|
|
|
|||
|
|
@ -480,7 +480,7 @@ export class Peer {
|
|||
*
|
||||
* @param options - Either a legacy raw filter object or an options object with
|
||||
* `filters`, `page`, `size`, and `reverse`. See
|
||||
* [search filters documentation](https://docs.honcho.dev/v3/documentation/core-concepts/features/using-filters).
|
||||
* [search filters documentation](https://honcho.dev/docs/v3/documentation/core-concepts/features/using-filters).
|
||||
* @returns Promise resolving to a paginated list of Session objects this peer belongs to.
|
||||
* Returns an empty list if the peer is not a member of any sessions
|
||||
*/
|
||||
|
|
@ -684,7 +684,7 @@ export class Peer {
|
|||
* Makes an API call to search endpoint.
|
||||
*
|
||||
* @param query The search query to use
|
||||
* @param filters - Optional filters to scope the search. See [search filters documentation](https://docs.honcho.dev/v3/documentation/core-concepts/features/using-filters).
|
||||
* @param filters - Optional filters to scope the search. See [search filters documentation](https://honcho.dev/docs/v3/documentation/core-concepts/features/using-filters).
|
||||
* @param limit - Optional limit on the number of results to return.
|
||||
* @returns Promise resolving to an array of Message objects representing the search results.
|
||||
* Returns an empty array if no messages are found.
|
||||
|
|
|
|||
|
|
@ -585,7 +585,7 @@ export class Session {
|
|||
*
|
||||
* @param options - Either a legacy raw filter object or an options object with
|
||||
* `filters`, `page`, `size`, and `reverse`. See
|
||||
* [search filters documentation](https://docs.honcho.dev/v3/documentation/core-concepts/features/using-filters).
|
||||
* [search filters documentation](https://honcho.dev/docs/v3/documentation/core-concepts/features/using-filters).
|
||||
* @returns Promise resolving to a paginated Page of Message objects
|
||||
*/
|
||||
async messages(
|
||||
|
|
@ -843,7 +843,7 @@ export class Session {
|
|||
* @param query - The search query to use
|
||||
* @param options - Search options
|
||||
* @param options.filters - Optional filters to scope the search. See
|
||||
* [search filters documentation](https://docs.honcho.dev/v3/documentation/core-concepts/features/using-filters).
|
||||
* [search filters documentation](https://honcho.dev/docs/v3/documentation/core-concepts/features/using-filters).
|
||||
* @param options.limit - Number of results to return (1-100, default: 10)
|
||||
* @returns Promise resolving to an array of Message objects matching the query
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue