内容摘录
<!-- markdownlint-disable MD033 -->
<div align="center">
<a href="https://app.honcho.dev" target="_blank">
<img src="assets/honcho.svg" alt="Honcho" width="400">
</a>
</div>
<!-- markdownlint-enable MD033 -->
---
!Static Badge
PyPI version
NPM version
Discord
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 has defined the Pareto Frontier of Agent Memory. Watch the video, check out our evals page, and read the blog post for more detail.
TL;DR - Getting Started
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
Typescript examples are available in our docs.
Install the SDK
Setup your Workspace, Peers, Session, and send Messages
Leverage reasoning from Honcho to inform your agent's behavior
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 to get started with a managed version of Honcho.
Learn more ways to use Honcho on our developer docs.
Read about the design philosophy and history of the project on our blog.
Project Structure
Usage
Local Development
Prerequisites and Dependencies
Setup
Docker
Deploy on Fly
Configuration
Using config.toml
Using Environment Variables
Configuration Priority
Example
Architecture
Storage
Reasoning
Retrieving Data & Insights
Contributing
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.
There are also client SDKs implemented in the sdks/ directory with support
for Python and TypeScript.
Python
TypeScript
Examples on how to use the SDK are located within each SDK folder and in the
SDK Reference
There are also documented examples of how to use the core SDKs in the
API Reference section of
the documentation.
Usage
Sign up for an account at
https://app.honcho.dev and get started with $100 free credits. When you sign up you'll be prompted to
join an organization which will have a dedicated instance of Honcho.
Provision API keys and change your base url to point to
https://api.honcho.dev
Additionally, Honcho can be self-hosted for testing and evaluation purposes. See
the Local Development section below for details on how to set up a local
version of Honcho.
Local Development
Below is a guide on setting up a local environment for running the Honcho
Server.
This guide was made using a M3 Macbook Pro. For any compatibility issues
on different platforms, please raise an Issue.
Prerequisites and Dependencies
Honcho is developed using python and uv.
The minimum python version is 3.9
The minimum uv version is 0.4.9
Setup
Once the dependencies are installed on the system run the following steps to get
the local project setup.
**Clone the repository**
**Enter the repository and install the python dependencies**
We recommend using a virtual environment to isolate the dependencies for Honcho
from other projects on the same system. uv will create a virtual environment
when you sync your dependencies in the project.
This will create a virtual environment and install the dependencies for Honcho.
The default virtual environment will be located at honcho/.venv. Activate the
virtual environment via:
**Set up a database**
Honcho utilizes Postgres for its database with
pgvector. An easy way to get started with a postgres database is to create a project
with Supabase
Alternatively, a docker-compose template is available with a sample database configuration.
To use Docker:
**Edit the environment variables**
Honcho uses a .env file for managing runtime environment variables. A
.env.template file is included for convenience. Several of the configurations
are not required and are only necessary for additional logging, monitoring, and
security.
Below are the required configurations:
Note that the DB_CONNECTION_URI must have the prefix postgresql+psycopg to
function properly. This is a requirement brought by sqlalchemy
The template has the additional functionality disabled by default. To ensure
that they are disabled you can verify the following environment variables are
set to false:
If you set AUTH_USE_AUTH to true you will need to generate a JWT secret. You can
do this with the following command:
This will generate a JWT secret and print it to the console. You can then set
the AUTH_JWT_SECRET environment variable. This is required for AUTH_USE_AUTH:
**Run database migrations**
With the database set up and environment variables configured, run the migrations
to create the necessary tables:
This will create all tables for Honcho including workspaces, peers, sessions,
messages, and the queue system.
**Launch Honcho**
With everything set up, you can now launch a local instance of Honcho. In addition to the database, two
components need to be running:
**Start the API server:**
This is a development server that will reload whenever code is changed.
**Start a background worker (deriver):**
In a separate terminal, run:
The deriver generates representation, summaries, peer cards, and manages dreaming tasks. You can increase the number of deriver's to improve runtime efficiency.
Pre-commit Hooks
Honcho uses pre-commit hooks to ensure code quality and consistency across the project. These hooks automatically run checks on your code before each commit, including linting, formatting, type checking, and security scans.
Installation
To set up pre-commit hooks in yo…