+
+
+---
-[](https://discord.gg/plasticlabs)
-[](https://arxiv.org/abs/2310.06983)
-
-
-[](https://twitter.com/plastic_labs)
[](https://pypi.org/project/honcho-ai/)
[](https://npmjs.org/package/@honcho-ai/sdk)
+[](https://discord.gg/plasticlabs)
+[](https://arxiv.org/abs/2310.06983)
-Honcho is an infrastructure layer for building AI agents with social cognition and theory-of-mind capabilities. It enables developers to create AI agents and LLM-powered applications that are personalized to their end users by leveraging the inherent theory-of-mind capabilities of LLMs to build coherent models of user psychology over time.
+Honcho is an AI-native memory library for building agents with perfect memory and
+social cognition.
-Read about the project [here](https://blog.plasticlabs.ai/blog/A-Simple-Honcho-Primer).
+It provides [state-of-the-art
+memory](https://blog.plasticlabs.ai/research/Introducing-Neuromancer-XR) and
+then goes beyond storage by reasoning about the stored data to build
+rich psychological profiles of each user in your system.
-Read the user documentation [here](https://docs.honcho.dev)
+Use it to build
-## Table of Contents
+- Highly personalized experiences
+- Agents with social cognition
+- Agents with rich identity that evolve over time
+- Multi-agent systems with complex social dynamics
+
+## TL;DR - Getting Started
+
+With Honcho you can easily setup your application's workflow, save your
+interaction history, and leverage generated insights to inform the behavior of
+your agents
+
+> Typescript examples are available in our [docs](https://docs.honcho.dev)
+
+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
+
+####### Storing Data in Honcho
+
+# 1. Initialize your Honcho client, by default SDK will use the demo environment and workspace named "default"
+honcho = Honcho(environment="demo", workspace_id="my-app-testing")
+
+# 2.. Initialize Peers
+alice = honcho.peer("alice")
+tutor = honcho.peer("tutor")
+
+# 3. Make a Session and send messages
+
+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!"),
+ .
+ .
+ .
+)
+```
+
+3. Leverage insights from Honcho to inform your agent's behavior
+
+```python
+
+### 1. Use the Dialectic API to ask questions about your users in natural language
+response = alice.chat("What learning styles does the user respond to best?")
+
+### 2. Use Get context to get most recent messages and summaries to continue a conversation
+context = session.get_context(summary=True, tokens=10000)
+
+# Convert to a format to send to OpenAI and get the next message
+openai_messages = context.to_openai_messages(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 cached working representation of a Peer for the Session
+alice_representation = session.working_rep("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
-- [Project Structure](#project-structure)
- [Usage](#usage)
- [Local Development](#local-development)
- [Prerequisites and Dependencies](#prerequisites-and-dependencies)
@@ -31,12 +125,11 @@ Read the user documentation [here](https://docs.honcho.dev)
- [Example](#example)
- [Architecture](#architecture)
- [Storage](#storage)
- - [Insights](#insights)
+ - [Reasoning](#reasoning)
+ - [Retrieving Data & Insights](#retrieving-data--insights)
- [Contributing](#contributing)
- [License](#license)
-## Project Structure
-
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.
@@ -396,9 +489,9 @@ Below is a mapping of the different primitives and their relationships.
Workspaces
├── Peers ←──────────────────┐
│ ├── Sessions │
-│ ├── Collections │
-│ │ └── Documents │
-│ └── Messages (peer-level)│
+│ └── Collections │
+│ └── Documents │
+│ │
│ │
└── Sessions ←───────────────┤ (many-to-many)
├── Peers ───────────────┘
@@ -411,7 +504,6 @@ Workspaces
- **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
- - **Peer-level**: Data ingested by a peer to enhance its global representation
- **Collections** belong to specific **Peers**
- **Documents** are stored within **Collections**
@@ -441,7 +533,6 @@ Sessions can involve multiple peers with configurable observation settings.
The `Message` represents an atomic data unit that can exist at two levels:
- **Session-level Messages**: Communication between peers within a session context
-- **Peer-level Messages**: Arbitrary data ingested by a peer to enhance its global representation (independent of any session)
All messages are labeled by their source peer and can be processed
asynchronously to update theory-of-mind models. This flexible design allows for
@@ -462,26 +553,49 @@ representations of peers.
As stated before a `Document` is vector embedded data stored in a `Collection`.
-### Insights
+### Reasoning
-The Insight functionality of Honcho is built on top of the Storage service. As
+The reasoning functionality of Honcho is built on top of the Storage service. As
`Messages` and `Sessions` are created for `Peers`, Honcho will asynchronously
reason about peer psychology to derive facts about them and store them
in reserved `Collections`.
-The system uses a sophisticated message processing pipeline:
+A high level summary of the pipeline is as follows:
-1. Messages are created via API
-2. Enqueued for background processing including:
- - `representation`: Update peer's theory of mind
- - `summary`: Create session summaries
+1. Messages are created via the API
+2. Derivation Tasks are enqueued for background processing including:
+ - `representation`: To update theory-of-mind representations of `Peers`
+ - `summary`: To create summaries of `Sessions`
3. Session-based queue processing ensures proper ordering
-4. Results are stored internally in the vector database
+4. Results are stored internally
To read more about how this works read our [Research Paper](https://arxiv.org/abs/2310.06983)
-Developers can then leverage these insights in their application to better
-serve peer needs. The primary interface for using these insights is through
+### Retrieving Data & Insights
+
+Honcho exposes several different ways to retrieve data from the system to best
+serve the needs of any given application.
+
+#### Get Context
+
+In long-running conversations with an LLM, the context window can fill up
+quickly. To address this, Honcho provides a `get_context`
+endpoint that returns a combination of messages and summaries from a
+session, up to a provided token limit.
+
+Use this to keep sessions going indefinitely.
+
+#### Search
+
+There are several search endpoints that let developers query messages at the
+`Workspace`, `Session`, or `Peer` level using a hybrid search strategy.
+
+Requests can include advanced filters to further refine
+the results.
+
+#### Dialectic API
+
+The flagship interface for using these insights is through
the [Dialectic Endpoint](https://blog.plasticlabs.ai/blog/Introducing-Honcho's-Dialectic-API).
This is a regular API endpoint (`/peers/{peer_id}/chat`) that takes natural language requests to get data
@@ -497,6 +611,16 @@ API include:
- 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
+#### Working Representations
+
+For low-latency use cases,
+Honcho provides access to a `get_working_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.
+
## Contributing
We welcome contributions to Honcho! Please read our [Contributing Guide](./CONTRIBUTING.md) for details on our development process, coding conventions, and how to submit pull requests.
diff --git a/assets/honcho.svg b/assets/honcho.svg
new file mode 100644
index 00000000..cac927da
--- /dev/null
+++ b/assets/honcho.svg
@@ -0,0 +1,27 @@
+
+
diff --git a/docs/v2/documentation/core-concepts/architecture.mdx b/docs/v2/documentation/core-concepts/architecture.mdx
index c35739ef..0a48e274 100644
--- a/docs/v2/documentation/core-concepts/architecture.mdx
+++ b/docs/v2/documentation/core-concepts/architecture.mdx
@@ -27,8 +27,6 @@ Honcho has a hierarchical data model centered around the entities below.
W[Workspaces] -->|have| P[Peers]
W -->|have| S[Sessions]
- P -->|have| PM[Messages]
-
S -->|have| SM[Messages]
P <-.->|many-to-many| S
@@ -36,13 +34,12 @@ Honcho has a hierarchical data model centered around the entities below.
style W fill:#FF5A7E,stroke:#333,stroke-width:2px,color:#fff
style P fill:#e1f5fe,stroke:#0277bd,color:#000
style S fill:#f3e5f5,stroke:#7b1fa2,color:#000
- style PM fill:#e8f5e9,stroke:#2e7d32,color:#000
style SM fill:#e8f5e9,stroke:#2e7d32,color:#000
```
There are `Workspaces` at the top that contain `Peers` and `Sessions`. A `Peer`
-can be part of many `Sessions` and a `Session` can have many `Peers`. Both
-`Sessions` and `Peers` can have `Messages`
+can be part of many `Sessions` and a `Session` can have many `Peers`. `Sessions`
+hold messages that are sent by `Peers`.
### Workspaces
@@ -103,14 +100,16 @@ Sessions represent individual conversation threads or interaction contexts betwe
- Support tickets
- Meeting transcripts
- Learning sessions
+- Single-Peer onboarding sessions where data is imported from an external source
---
### Messages
Messages are the fundamental units of interaction within sessions. They may
-also be used at the peer level to ingest information of any kind that is not related to a specific interaction, but provides
-important context for a peer (emails, docs, files, etc.).
+also be used to ingest information of any kind that is not related to a specific interaction, but provides
+important context for a peer (emails, docs, files, etc.). Simple make a session
+with a single peer and structure the data as messages.
**Key Features:**
- **Rich Content**: Support for text, metadata, and structured data
diff --git a/docs/v2/documentation/introduction/overview.mdx b/docs/v2/documentation/introduction/overview.mdx
index 41fa6318..4e8ddbe6 100644
--- a/docs/v2/documentation/introduction/overview.mdx
+++ b/docs/v2/documentation/introduction/overview.mdx
@@ -47,23 +47,32 @@ Designed for developers and agents alike:
## How It Works
-Honcho operates through two integrated layers:
+### Storage
+
+Developers use Honcho to store information about their users and application via
+two integrated layers:
**Memory Layer**: Captures all user interactions - messages, preferences, and
-behavioral patterns - in a user-centric data model that scales from individual
-conversations to complex multi-agent scenarios. This also queues up messages for the insights layer to process.
+behavioral patterns - in a peer-centric data model that scales from individual
+conversations to complex multi-agent scenarios. This also queues up messages for
+the reasoning layer to process.
-**Insights Layer**: Continuously analyzes stored interactions to build
+**Reasoning Layer**: Continuously analyzes stored interactions to build
psychological profiles using [theory of mind](glossary#theory-of-mind)
inference, extracting patterns about communication style, decision-making
preferences, and mental models.
-Agents access this understanding through the [dialectic
-endpoint](../core-concepts/architecture#dialectic-api) - a natural language API
-where they can ask specific questions about users and receive actionable
-insights.
+### Retrieval
+
+Once data is stored and generated within Honcho, the API exposes several
+different ways to retrieve and use those insights.
+
+**[Dialectic API](../guides/dialectic-endpoint)**: This is the
+flagship endpoint that allows developers to send natural language queries to
+Honcho to chat with the representation of each user in your system to get
+dynamic, in-context actionable insights.
Example Queries
- "What's the best way to explain technical concepts to this user?"
@@ -72,6 +81,23 @@ Example Queries
- "How does this user prefer to receive feedback?"
- "What are this user's core values based on our conversations?"
+**[Get Context](../guides/get-context)**: This endpoint abstracts context window
+constraints and continuously retrieves the most relevant and recent data from a
+conversation. Provide a token budget and Honcho will rturn a combination of
+summaries and messages that pvoide session context. Use this for creating
+long-running conversations. We crafted our summaries to provide the most
+[coverage of a session possible](../core-concepts/summarizer).
+
+**[Search](../guides/search)**: This endpoint allows you to search across Honcho
+for relevant messages either at the workspace, peer, or session level. This
+endpoint uses a hybrid search strategy that combines text search and cosine
+similarity.
+
+**[Working Representations](../guides/working-rep)**: Get a cached, snapshot
+of a user in the context of a session. Instead of waiting for an LLM to
+synthesize an in-context response via the Dialectic endpoint, use this to get
+recent insights you can plug into your context window.
+
## Ideal For
**Personalized AI assistants** that need to understand individual psychology, not just remember conversations.
+
+
**Memory Layer**: Captures all user interactions - messages, preferences, and
-behavioral patterns - in a user-centric data model that scales from individual
-conversations to complex multi-agent scenarios. This also queues up messages for the insights layer to process.
+behavioral patterns - in a peer-centric data model that scales from individual
+conversations to complex multi-agent scenarios. This also queues up messages for
+the reasoning layer to process.
-**Insights Layer**: Continuously analyzes stored interactions to build
+**Reasoning Layer**: Continuously analyzes stored interactions to build
psychological profiles using [theory of mind](glossary#theory-of-mind)
inference, extracting patterns about communication style, decision-making
preferences, and mental models.
-Agents access this understanding through the [dialectic
-endpoint](../core-concepts/architecture#dialectic-api) - a natural language API
-where they can ask specific questions about users and receive actionable
-insights.
+### Retrieval
+
+Once data is stored and generated within Honcho, the API exposes several
+different ways to retrieve and use those insights.
+
+**[Dialectic API](../guides/dialectic-endpoint)**: This is the
+flagship endpoint that allows developers to send natural language queries to
+Honcho to chat with the representation of each user in your system to get
+dynamic, in-context actionable insights.
Example Queries
- "What's the best way to explain technical concepts to this user?"
@@ -72,6 +81,23 @@ Example Queries
- "How does this user prefer to receive feedback?"
- "What are this user's core values based on our conversations?"
+**[Get Context](../guides/get-context)**: This endpoint abstracts context window
+constraints and continuously retrieves the most relevant and recent data from a
+conversation. Provide a token budget and Honcho will rturn a combination of
+summaries and messages that pvoide session context. Use this for creating
+long-running conversations. We crafted our summaries to provide the most
+[coverage of a session possible](../core-concepts/summarizer).
+
+**[Search](../guides/search)**: This endpoint allows you to search across Honcho
+for relevant messages either at the workspace, peer, or session level. This
+endpoint uses a hybrid search strategy that combines text search and cosine
+similarity.
+
+**[Working Representations](../guides/working-rep)**: Get a cached, snapshot
+of a user in the context of a session. Instead of waiting for an LLM to
+synthesize an in-context response via the Dialectic endpoint, use this to get
+recent insights you can plug into your context window.
+
## Ideal For
**Personalized AI assistants** that need to understand individual psychology, not just remember conversations.