Core Documentation Re-write (#154)
* fix (docs): Introduction * fix (docs): Cleaned up core concepts * fix (docs): Rename section * chore: Code Rabbit * chore (docs): Code Rabbit * nit * chore (docs): Code Rabbit
This commit is contained in:
Vineeth Voruganti
GitHub
parent
eb748e8009
commit
d16660b88f
|
|
@ -52,8 +52,8 @@ We recommend using the official client SDKs instead of the core ones for better
|
|||
developer experience, however for any custom use cases you can still access the
|
||||
core SDKs in their own repos:
|
||||
|
||||
[Honcho Core Python](https://github.com/plastic-labs/honcho-python-core)
|
||||
[Honcho Core TypeScript](https://github.com/plastic-labs/honcho-node-core)
|
||||
- [Honcho Core Python](https://github.com/plastic-labs/honcho-python-core)
|
||||
- [Honcho Core TypeScript](https://github.com/plastic-labs/honcho-node-core)
|
||||
|
||||
Examples on how to use the SDK are located within each SDK folder and in the
|
||||
[SDK Reference](https://docs.honcho.dev/v2/documentation/tutorial/SDK)
|
||||
|
|
|
|||
|
|
@ -32,17 +32,16 @@
|
|||
{
|
||||
"group": "Core Concepts",
|
||||
"pages": [
|
||||
"v2/documentation/core-concepts/glossary",
|
||||
"v2/documentation/core-concepts/architecture",
|
||||
"v2/documentation/core-concepts/glossary",
|
||||
"v2/documentation/core-concepts/features"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Tutorial",
|
||||
"group": "Reference",
|
||||
"pages": [
|
||||
"v2/documentation/tutorial/platform",
|
||||
"v2/documentation/tutorial/guided-tutorial",
|
||||
"v2/documentation/tutorial/sdk"
|
||||
"v2/documentation/reference/platform",
|
||||
"v2/documentation/reference/sdk"
|
||||
]
|
||||
}
|
||||
]
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 324 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 148 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 150 KiB |
|
|
@ -1,39 +1,52 @@
|
|||
---
|
||||
title: "Architecture"
|
||||
title: "Architecture & Intuition"
|
||||
description: "Understanding Honcho's core concepts and data model."
|
||||
icon: "sitemap"
|
||||
sidebarTitle: "Architecture"
|
||||
---
|
||||
|
||||
Honcho is built around a hierarchical data model that enables scalable memory management for AI applications. Understanding these core concepts is essential for effectively using the platform.
|
||||
<Note> The goal of this page is to build an intuition for the primitives in Honcho and how they fit together </Note>
|
||||
|
||||
## Data Model Overview
|
||||
Honcho has 3 main components that work together to manage agent identity and context.
|
||||
|
||||
- **The Storage API**: The Memory layer for storing interaction history for your agents
|
||||
- **The Deriver**: The background processing layer that builds representations of users and agents
|
||||
- **The Dialectic API**: The natural language API for chatting with representations
|
||||
|
||||
Below we'll deep dive into these different areas, discussing the data
|
||||
primitives, the flow of data through the system, artifacts Honcho produces, and
|
||||
how to use them.
|
||||
|
||||
|
||||
## Data Model
|
||||
|
||||
Honcho has a hierarchical data model centered around the entities below.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
W[Workspace] --> P[Peers]
|
||||
W --> S[Sessions]
|
||||
W --> D[Background Processing]
|
||||
P --> PM[Messages]
|
||||
S --> SM[Messages]
|
||||
S --> SP[Session Peers]
|
||||
SP --> Config[Configurations]
|
||||
D --> DQ[Deriver Queue]
|
||||
|
||||
style W fill:#FF5A7E,stroke:#333,stroke-width:2px,color:#fff
|
||||
style P fill:#e1f5fe
|
||||
style S fill:#f3e5f5
|
||||
style D fill:#fff3e0
|
||||
graph TD
|
||||
W[Workspaces] -->|have| P[Peers]
|
||||
W -->|have| S[Sessions]
|
||||
|
||||
P -->|have| PM[Messages]
|
||||
|
||||
S -->|have| SM[Messages]
|
||||
|
||||
P <-.->|many-to-many| S
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
<Info>
|
||||
See the [Storage API](/v2/api-reference/introduction) to learn how to use the data model in practice.
|
||||
</Info>
|
||||
|
||||
## Core Concepts
|
||||
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`
|
||||
|
||||
### <Icon icon="building" /> Workspaces
|
||||
|
||||
Workspaces are the top-level containers that provide complete isolation between different applications or environments.
|
||||
Workspaces are the top-level containers that provide complete isolation between different applications or environments; they essentially as a namespace to isolate different workloads or environments
|
||||
|
||||
**Key Features:**
|
||||
- **Isolation**: Complete data separation between workspaces
|
||||
|
|
@ -47,24 +60,16 @@ Workspaces are the top-level containers that provide complete isolation between
|
|||
- Different product lines or use cases
|
||||
- Complete data separation between teams
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-production-app",
|
||||
"metadata": {
|
||||
"environment": "production",
|
||||
"version": "1.0.0"
|
||||
},
|
||||
"configuration": {
|
||||
"deriver_enabled": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### <Icon icon="user" /> Peers
|
||||
|
||||
Peers represent individual users, agents, or entities in a workspace. They are the primary subjects for memory and context management.
|
||||
Honcho has a Peer-Centric Architecture: Peers are the most important entity within Honcho, with everything revolving around Peers and their representations.
|
||||
|
||||
Peers represent individual users, agents, or entities in a workspace. They are
|
||||
the primary subjects for memory and context management. Treating humans and
|
||||
agents the same lets us support arbitrary combinations of Peers for
|
||||
multi-agent or group chat scenarios.
|
||||
|
||||
**Key Features:**
|
||||
- **Identity**: Unique identifier within a workspace
|
||||
|
|
@ -77,22 +82,7 @@ Peers represent individual users, agents, or entities in a workspace. They are t
|
|||
- AI agents interacting with users or other agents
|
||||
- Customer profiles in support systems
|
||||
- Student profiles in educational platforms
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "user-123",
|
||||
"metadata": {
|
||||
"email": "user@example.com",
|
||||
"preferences": {
|
||||
"language": "en",
|
||||
"timezone": "UTC"
|
||||
}
|
||||
},
|
||||
"configuration": {
|
||||
"observe_me": true
|
||||
}
|
||||
}
|
||||
```
|
||||
- NPCs in role-playing games
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -112,33 +102,15 @@ Sessions represent individual conversation threads or interaction contexts betwe
|
|||
- Meeting transcripts
|
||||
- Learning sessions
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "conversation-456",
|
||||
"peers": {
|
||||
"user-123": {
|
||||
"observe_others": true,
|
||||
"observe_me": true
|
||||
},
|
||||
"assistant-ai": {
|
||||
"observe_others": false,
|
||||
"observe_me": false
|
||||
}
|
||||
},
|
||||
"metadata": {
|
||||
"topic": "product-support",
|
||||
"priority": "high"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### <Icon icon="envelope" /> Messages
|
||||
|
||||
Messages are the fundamental units of interaction within sessions. They may also be used at the peer level to represent stored information of any kind.
|
||||
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.).
|
||||
|
||||
**Key Features:**
|
||||
**Key Features:**
|
||||
- **Rich Content**: Support for text, metadata, and structured data
|
||||
- **Attribution**: Clear association with sending peer
|
||||
- **Ordering**: Chronological sequence within sessions
|
||||
|
|
@ -149,86 +121,102 @@ Messages are the fundamental units of interaction within sessions. They may also
|
|||
- AI responses
|
||||
- System notifications
|
||||
- Rich media content
|
||||
- User actions (clicked, reacted, etc.)
|
||||
|
||||
```json
|
||||
{
|
||||
"content": "I need help with my order",
|
||||
"peer_id": "user-123",
|
||||
"metadata": {
|
||||
"intent": "support_request",
|
||||
"urgency": "medium",
|
||||
"order_id": "12345"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
## Deriver
|
||||
|
||||
## Deriver System
|
||||
At the core of developing representations of Peers, we have the Deriver. The
|
||||
Deriver refers to a set of processes in Honcho that enqueue new messages sent
|
||||
by peers and reasons over them to extract facts, insights, and context.
|
||||
|
||||
### Deriver Queue
|
||||
Depending on the configuration of a `Peer` or `Session`, the deriver will behave
|
||||
differently and update different representations.
|
||||
|
||||
The deriver system provides automatic background processing of user interactions to derive facts, insights, and context. Messages ingested by Honcho are automatically queued for background processing by the deriver. Depending on the configuration of peer that authored the message and the session in which the message is created, the deriver may enqueue the message multiple times -- we can store facts derived from the message in the peer's global representation, their session-level representation, and/or the representations of other peers observing the author.
|
||||
|
||||
Facts derived here are used in the Dialectic chat endpoint to generate context-aware responses that can correctly reference both concrete facts extracted from messages and social insights deduced from facts, tone, and opinion.
|
||||
Facts derived here are used in the Dialectic chat endpoint to generate
|
||||
context-aware responses that can correctly reference both concrete facts
|
||||
extracted from messages and social insights deduced from facts, tone, and
|
||||
opinion.
|
||||
|
||||
<Info>
|
||||
Deriver tasks are processed in parallel, but tasks affecting the same peer representation will always be processed serially in order of message creation, so as to properly understand their cumulative effect.
|
||||
</Info>
|
||||
|
||||
### Deriver Tasks
|
||||
There are two types of tasks that the deriver currently does:
|
||||
|
||||
#### Representation
|
||||
- **Representation Tasks**: Generate/update peer representations
|
||||
- **Summary Tasks**: Generate conversation summaries
|
||||
|
||||
Representation tasks generate peer representations. They may be enqueued for each peer that observes a message, depending on configuration. Representations are accessed via the `chat` endpoint, allowing developers to query a peer's representation: from the "omnipresent" perspective of Honcho, the session-level representation, and the representation of that peer *from the perspective of other peers*.
|
||||
### Peer Representations
|
||||
|
||||
Representation tasks create comprehensive user profiles including:
|
||||
Peer representations are more of an abstract concept, as they are made up of
|
||||
various pieces of data stored throughout Honcho. There are however
|
||||
multiple types of representations that Honcho can produce.
|
||||
|
||||
**Psychological Insights:**
|
||||
- Personality traits
|
||||
- Communication style
|
||||
- Preferences and interests
|
||||
- Behavioral patterns
|
||||
Honcho handles both **local** and **global** representations of Peers, where
|
||||
**local** representations are specific to a single Peer's view of another Peer,
|
||||
while Global Representations are based on any message ever produced by a Peer.
|
||||
|
||||
**Contextual Information:**
|
||||
- Current conversation topics
|
||||
- User goals and objectives
|
||||
- Emotional state indicators
|
||||
- Relationship dynamics
|
||||
<img src="/images/local-vs-global-reps.png" alt="Peer Representations" />
|
||||
|
||||
**Example Output:**
|
||||
Everything is framed with regards to perspective. Alice owns her own global
|
||||
representation, but she also maintains a local representation of Bob based on what she
|
||||
observes and similarly Bob has a global representation of himself and local
|
||||
representation of Alice. So in the example above, when Alice sends a message to
|
||||
Bob it triggers an update to both Alice's global representation of herself and Bob's local
|
||||
representation of Alice.
|
||||
|
||||
If Alice were to have another conversation with a different Peer, Nico, and
|
||||
sent them a message, this action would trigger an update to Alice's Global
|
||||
Representation and Nico's local representation of Alice. Bob's local
|
||||
representation of Alice would not change since Bob would never receive that
|
||||
message.
|
||||
|
||||
<Note>By default, local representations are disabled, but can be enabled in a
|
||||
Peer or Session level configuration</Note>
|
||||
|
||||
Depending on the use case, a developer may choose to only use global
|
||||
representation, only use local, or a combination.
|
||||
|
||||
### Summary
|
||||
|
||||
Summary tasks create conversation summaries. Periodically, a
|
||||
"short" summary will be created for each session as messages are added -- every
|
||||
20 messages by default. "Long" summaries are created every 60 messages by
|
||||
default and maintain a total overview of the session by including the previous
|
||||
summary in a recursive fashion. These summaries are accessed in the
|
||||
`get_context` endpoint along with recent messages, allowing developers to
|
||||
easily fetch everything necessary to generate the next LLM completion for an
|
||||
agent.
|
||||
|
||||
The system defaults are also the checkpoints used on the managed version of
|
||||
Honcho hosted at [https://api.honcho.dev](https://api.honcho.dev)
|
||||
|
||||
|
||||
## Dialectic API
|
||||
|
||||
The Dialectic API is one of the most integral components of Honcho and acts as
|
||||
the main way to leverage Peer Representations. By using the `/chat` endpoint,
|
||||
developers can directly talk to Honcho about any Peer in a workspace to get
|
||||
insights into the psychology of a Peer and help them steer their behavior.
|
||||
|
||||
This allows us to use this one endpoint for a wide variety of use cases. Model
|
||||
steering, personalization, hydrating a prompt, etc. Additionally, since the
|
||||
endpoint works through natural language, a developer can allow an agent to
|
||||
backchannel directly with Honcho, via MCP or a direct API call.
|
||||
|
||||
Developers should frame the Dialectic as talking to an expert on the Peer rather than addressing the Peer itself, meaning:
|
||||
|
||||
```python
|
||||
alice.chat("What is alice's mood like") # ✅ Correct
|
||||
|
||||
alice.chat("What is your mood like") # ❌ Wrong
|
||||
```
|
||||
The user demonstrates high technical competency and prefers direct communication.
|
||||
They show interest in software development topics and value efficiency in conversations.
|
||||
Current session indicates they're seeking help with API integration issues.
|
||||
```
|
||||
|
||||
#### Summary
|
||||
|
||||
Summary tasks create conversation summaries and key insights. Periodically, a "short" summary will be created for each session as messages are added -- every 20 messages by default. "Long" summaries are created every 60 messages by default and maintain a total overview of the session by including the previous summary in a recursive fashion. These summaries are accessed in the `get_context` endpoint along with recent messages, allowing developers to easily fetch everything necessary to generate the next LLM completion for an agent.
|
||||
|
||||
## Dialectic Chat
|
||||
|
||||
Honcho's killer feature is the `chat` endpoint. By storing messages in Honcho, you may query in natural language to get intelligent answer's about a user or agent's personality, theory of mind, history, and more. Dialectic Chat should be thought of as an assisting agent which your agent can reach out to for useful context and answers about actors, human or AI, operating your application.
|
||||
|
||||
<Note>
|
||||
Think of Dialectic Chat as an assisting agent that your main agent can consult for contextual information about any actor in your application.
|
||||
</Note>
|
||||
|
||||
## Scalability Considerations
|
||||
|
||||
- **Stateless API**: Scale API servers independently
|
||||
- **Queue Workers**: Scale background processing workers
|
||||
- **Database**: PostgreSQL with read replicas
|
||||
|
||||
## Security Architecture
|
||||
|
||||
- **JWTs**: Secure API access
|
||||
- **Scoped Access**: Workspace/peer/session level permissions
|
||||
- **Admin Controls**: Super-user capabilities
|
||||
- **Workspace Isolation**: Complete data separation
|
||||
- **Encryption**: Data encryption at rest and in transit
|
||||
|
||||
## Next Steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
|
@ -238,7 +226,7 @@ Think of Dialectic Chat as an assisting agent that your main agent can consult f
|
|||
<Card title="Glossary" icon="book" href="/v2/documentation/core-concepts/glossary">
|
||||
Reference for all technical terms and concepts
|
||||
</Card>
|
||||
<Card title="API Reference" icon="api" href="/v2/api-reference/introduction">
|
||||
<Card title="API Reference" icon="play" href="/v2/api-reference/introduction">
|
||||
Detailed API documentation and examples
|
||||
</Card>
|
||||
<Card title="Quick Start" icon="rocket" href="/v2/documentation/introduction/quickstart">
|
||||
|
|
|
|||
|
|
@ -4,6 +4,9 @@ description: 'Key features and capabilities of Honcho'
|
|||
icon: 'star'
|
||||
---
|
||||
|
||||
This page is a quick overview of the features within Honcho. In-depth
|
||||
guides are available for each feature in the [Spellbooks - Design Patterns](../../guides/overview#design-patterns) section.
|
||||
|
||||
### Local vs Global Representation
|
||||
Peers in Honcho are abstract entities that can represent humans, agents, or NPCs. Honcho has a two-layer approach to forming representations of Peers.
|
||||
- **Global Representation**: Representation owned by a Peer that is constructed from everything the Peer has sent within Honcho.
|
||||
|
|
@ -34,4 +37,4 @@ Builders can create scoped API keys to control access to different resources wit
|
|||
Honcho provides a powerful context retrieval feature that delivers formatted conversation context from sessions, making it easy to integrate with LLMs like OpenAI, Anthropic, and others.
|
||||
- By default, the context includes a blend of summary and messages which covers the entire history of the session.
|
||||
- Summaries are generated automatically at intervals, and recent messages are included based on your specified token budget for the context.
|
||||
- You can set any token limit, and if you prefer, you can disable summaries so that the context consists entirely of the most recent messages up to your chosen limit.
|
||||
- You can set any token limit, and if you prefer, you can disable summaries so that the context consists entirely of the most recent messages up to your chosen limit.
|
||||
|
|
|
|||
|
|
@ -1,222 +1,70 @@
|
|||
---
|
||||
title: 'Glossary'
|
||||
description: 'Key terms and concepts within the Honcho framework'
|
||||
icon: 'book'
|
||||
---
|
||||
title: 'Terminology'
|
||||
description: 'Glossary of AI and Honcho Specific Terms'
|
||||
icon: 'book'
|
||||
---
|
||||
|
||||
## AI Development Basics
|
||||
|
||||
Essential terms for developers new to building AI applications.
|
||||
|
||||
**LLM (Large Language Model)**
|
||||
The AI model that generates text responses, like GPT-4, Claude, or Llama. Think of it as the "brain" that powers your chatbot or AI assistant.
|
||||
**LLM (Large Language Model)** The AI model that generates text responses,
|
||||
like GPT-4, Claude, or Llama. Think of it as the "brain" that powers your
|
||||
chatbot or AI assistant.
|
||||
|
||||
**Prompt**
|
||||
The text you send to an AI model to get a response. This includes user messages, system instructions, and any context you provide.
|
||||
**Prompt** The text you send to an AI model to get a response. This includes
|
||||
user messages, system instructions, and any context you provide.
|
||||
|
||||
**Token**
|
||||
How AI models count and limit text. Roughly 1 token = 0.75 words. Models have token limits (like 4,000 or 128,000 tokens) that determine how much text they can process at once.
|
||||
**Token** How AI models count and limit text. Roughly 1 token = 0.75 words.
|
||||
Models have token limits (like 4,000 or 128,000 tokens) that determine how much
|
||||
text they can process at once.
|
||||
|
||||
**Context Window**
|
||||
The maximum amount of text an AI model can "remember" in one conversation. Once you exceed this limit, the model starts "forgetting" earlier parts of the conversation.
|
||||
**Context Window** The maximum amount of text an AI model can "remember" in
|
||||
one conversation. Once you exceed this limit, the model starts "forgetting"
|
||||
earlier parts of the conversation.
|
||||
|
||||
**Memory**
|
||||
How your AI application remembers information between conversations. Without memory, each conversation starts fresh with no knowledge of previous interactions.
|
||||
**Embedding** Converting text into numerical vectors that computers can
|
||||
understand and compare. Enables "smart search" that finds similar content based
|
||||
on meaning, not just keywords.
|
||||
|
||||
**Context**
|
||||
Background information your AI knows about the current situation, user, or conversation. Good context leads to more relevant and personalized responses.
|
||||
**Semantic Search** Search based on meaning rather than exact keyword
|
||||
matching, often using embeddings.
|
||||
|
||||
**Personalization**
|
||||
Tailoring AI responses to each specific user based on their preferences, history, and behavior patterns.
|
||||
**Agent** An AI system that can take actions and make decisions, not just
|
||||
generate text responses. Agents can use tools, call APIs, and interact with
|
||||
external systems.
|
||||
|
||||
**Embedding**
|
||||
Converting text into numerical vectors that computers can understand and compare. Enables "smart search" that finds similar content based on meaning, not just keywords.
|
||||
## Honcho Terms
|
||||
|
||||
**Metadata**
|
||||
Extra information attached to your data, like tags, timestamps, or custom properties. Helps organize and filter your content.
|
||||
**Global Representation** Derived context of a specific peer, synthesizing
|
||||
insights from interactions across all sessions, including arbitrary data
|
||||
ingested by this specific peer. With arbitrary data, a global representation
|
||||
can be made independent of sessions.
|
||||
|
||||
**API (Application Programming Interface)**
|
||||
How your application communicates with external services. APIs define what requests you can make and what responses you'll get back.
|
||||
|
||||
**Endpoint**
|
||||
A specific URL your application calls to perform an action, like creating a user, sending a message, or retrieving data.
|
||||
|
||||
**Session**
|
||||
One complete conversation or interaction between a user and your AI. Sessions help organize and maintain context within individual conversations.
|
||||
|
||||
**Agent**
|
||||
An AI system that can take actions and make decisions, not just generate text responses. Agents can use tools, call APIs, and interact with external systems.
|
||||
|
||||
---
|
||||
|
||||
## Honcho Core Concepts
|
||||
|
||||
The fundamental building blocks of the Honcho platform.
|
||||
|
||||
|
||||
<Info>
|
||||
These four concepts form the foundation of Honcho's architecture and enable all other features.
|
||||
</Info>
|
||||
|
||||
**Workspace**
|
||||
A top-level container providing complete isolation between different applications or environments. Workspaces enable multi-tenancy and contain all peers, sessions, and data with workspace-scoped authentication.
|
||||
|
||||
**Peer**
|
||||
A persistent identity within a workspace that represents a conversational participant (human users, AI agents, or other possible entities). Peers maintain persistent context and memory across all their interactions and can be configured with specific behavioral settings.
|
||||
|
||||
**Session**
|
||||
An independent conversation or interaction context that can include multiple peers. Sessions exist independently, allowing persistent context as well as dynamic peer participation and removal.
|
||||
|
||||
**Message**
|
||||
A single communication unit within a session, attributed to a specific peer. Messages support rich content, metadata, and automatic background processing for derived insights.
|
||||
|
||||
---
|
||||
|
||||
## Multi-Peer Architecture
|
||||
|
||||
Advanced features for complex conversational scenarios.
|
||||
|
||||
**Multi-Peer Sessions**
|
||||
Sessions that support multiple participants simultaneously, including humans, AI agents, and other entities. Each peer can have individual configuration settings within the session.
|
||||
|
||||
**Peer Configuration**
|
||||
Settings that control how a peer behaves within a session:
|
||||
- **observe_me**: Whether this peer's actions are observed and learned from
|
||||
- **observe_others**: Whether this peer learns from other participants
|
||||
|
||||
---
|
||||
|
||||
## Context & Memory
|
||||
|
||||
How Honcho builds and maintains intelligent context about users and conversations.
|
||||
|
||||
<Tip>
|
||||
Understanding these concepts is key to leveraging Honcho's Theory of Mind capabilities.
|
||||
</Tip>
|
||||
|
||||
**The Deriver**
|
||||
Honcho's core engine that uses Theory of Mind principles to extract facts, maintain context, and create representations of any given peer.
|
||||
|
||||
**Peer Context**
|
||||
Persistent knowledge and preferences associated with a specific peer that spans across all their sessions. This includes personality profiles, preferences, and accumulated facts.
|
||||
|
||||
**Session Context**
|
||||
Conversation-specific memory and context that is scoped to individual sessions, including summaries and session-specific insights.
|
||||
|
||||
**Arbitrary Data**
|
||||
Information fed to the deriver to jump-start a representation or provide extra context to a specific peer, independent of natural conversation.
|
||||
|
||||
**Global Representation**
|
||||
Derived context of a specific peer, synthesizing insights from interactions across all sessions, including arbitrary data ingested by this specific peer. With arbitrary data, a global representation can be made independent of sessions.
|
||||
|
||||
**Local Representation**
|
||||
One peer's persistent context of another based on observed interactions/messages.
|
||||
|
||||
**Observer Peer**
|
||||
A peer that forms representations of other peers based on their interactions.
|
||||
|
||||
**Target Peer**
|
||||
The peer being observed to inform a representation.
|
||||
|
||||
---
|
||||
|
||||
## Storage & Processing
|
||||
|
||||
How Honcho stores and processes conversational data.
|
||||
|
||||
**Dialectic API**
|
||||
Natural language interface for making queries about what insights have been derived concerning global and local peer representations.
|
||||
|
||||
**Collections**
|
||||
Internal storage containers that use vector embeddings (numerical representations of text) to enable semantic search and similarity matching. Collections store insights, facts, and context about peers generated by the Deriver, allowing the Dialectic API to find relevant information based on meaning rather than exact keywords.
|
||||
|
||||
**Documents**
|
||||
Internal pieces of content stored in collections, automatically embedded and searchable via vector similarity. Used internally for context storage and retrieval.
|
||||
|
||||
**Internal Metadata**
|
||||
Honcho's internal state information that is not exposed through the API, used for system processing and state management.
|
||||
|
||||
---
|
||||
|
||||
## Background Processing
|
||||
|
||||
How Honcho processes data in the background to build intelligence.
|
||||
|
||||
**Work Units**
|
||||
Discrete processing tasks that replace session-based processing. Work units handle multi-peer scenarios and different task types for more granular processing control.
|
||||
|
||||
**Deriver Queue**
|
||||
Background processing system that derives insights from interactions, generates peer representations, and maintains context. Processes work units asynchronously.
|
||||
|
||||
**Queue Status**
|
||||
Processing status indicators: **Pending**, **In Progress**, or **Complete**.
|
||||
|
||||
---
|
||||
|
||||
## Advanced Features
|
||||
|
||||
Powerful capabilities for sophisticated AI applications.
|
||||
|
||||
**Batch Operations**
|
||||
Enhanced message operations including:
|
||||
- Batch message creation
|
||||
- Message querying with token and message count limits
|
||||
- Efficient bulk data processing
|
||||
|
||||
**Scoped Search & Summary**
|
||||
Search and summary functionalities that can be scoped by:
|
||||
- Workspace level
|
||||
- Peer level
|
||||
- Session level
|
||||
|
||||
**Context Retrieval**
|
||||
Session context retrieval with automatic summarization and intelligent token allocation management.
|
||||
|
||||
**Peer Paradigm**
|
||||
A conversation model where AI entities act as peers rather than traditional assistants, enabling collaborative interactions and shared context development.
|
||||
|
||||
---
|
||||
|
||||
## Authentication & Security
|
||||
|
||||
Security and access control features.
|
||||
|
||||
**Workspace-Scoped Authentication**
|
||||
JWT-based authentication system updated to support the workspace/peer/session hierarchy with appropriate access controls.
|
||||
|
||||
**Scoped API Keys**
|
||||
Authentication tokens that can limit access to specific workspaces, peers, or resources for enhanced security and multi-tenant isolation.
|
||||
|
||||
---
|
||||
|
||||
## Technical Terms
|
||||
|
||||
Advanced technical concepts for power users.
|
||||
|
||||
<Warning>
|
||||
These concepts require deeper technical understanding and are primarily for advanced implementations.
|
||||
</Warning>
|
||||
|
||||
**Vector Search**
|
||||
Finding similar content using cosine similarity between vector embeddings for semantic context retrieval.
|
||||
|
||||
**Semantic Search**
|
||||
Search based on meaning rather than exact keyword matching, used for intelligent context assembly.
|
||||
|
||||
**Token Allocation**
|
||||
Intelligent management of token usage across context retrieval, summarization, and response generation.
|
||||
|
||||
**Multi-Tenancy**
|
||||
The ability to serve multiple isolated workspaces from a single Honcho instance with complete data separation.
|
||||
|
||||
---
|
||||
**Local Representation** One peer's persistent context of another based on
|
||||
observed interactions/messages.
|
||||
|
||||
## Cognitive Science Terms
|
||||
|
||||
Cognitive science terms that are used throughout the inspiration and implementation of Honcho
|
||||
Cognitive science terms that are used throughout the inspiration and
|
||||
implementation of Honcho
|
||||
|
||||
**Theory of Mind**
|
||||
The ability of a computer to understand, remember, and interact with its own mind, enabling it to form representations of the world and make decisions based on its own knowledge and behavior.
|
||||
**Theory of Mind** The ability of a computer to understand, remember, and
|
||||
interact with its own mind, enabling it to form representations of the world
|
||||
and make decisions based on its own knowledge and behavior.
|
||||
|
||||
**Social Cognition**
|
||||
The mental processes by which we perceive, interpret, and respond to information about others and social situations. It includes the encoding, storage, retrieval, and application of social knowledge.
|
||||
**Social Cognition** The mental processes by which we perceive, interpret, and
|
||||
respond to information about others and social situations. It includes the
|
||||
encoding, storage, retrieval, and application of social knowledge.
|
||||
|
||||
**Cognitive Architecture** In CogSci, frameworks describing fixed structures & mechanisms underlying
|
||||
human cognition. Such frameworks aim to explain how various components of the mind--perception, memory,
|
||||
reasoning, learning, etc--combine to produce intelligent behavior across diverse environments. In
|
||||
AI, it’s a computational implementation of these theories--a designed framework to replicate human
|
||||
cognitive functions.
|
||||
|
||||
**Predictive Coding** A theory in CogSci proposing the brain is an active prediction machine,
|
||||
continually generating & updating internal world models to anticipate sensory input, rather than
|
||||
passively receiving it--closely linked to Bayesian brain hypotheses, which hold that the brain
|
||||
interprets the world probabilistically, weighing prior knowledge against new evidence to minimize
|
||||
uncertainty.
|
||||
|
|
|
|||
|
|
@ -1,46 +1,76 @@
|
|||
---
|
||||
title: "Overview"
|
||||
description: "Honcho solves context for AI agents by going beyond memory."
|
||||
title: "Honcho"
|
||||
description: "Go beyond memory to agents with actual social intelligence"
|
||||
icon: "brain"
|
||||
sidebarTitle: "Overview"
|
||||
---
|
||||
|
||||
Most agents today are stateless - they forget everything between conversations or hit token limits mid-conversation. But even agents with perfect memory still treat every user the same, missing individual psychology and preferences.
|
||||
When building agents developers often run into the same walls:
|
||||
|
||||
Honcho gives agents [social cognition](../core-concepts/glossary#cognitive-science-terms) - the ability to understand users as individuals, not just conversation histories.
|
||||
> "My agent forgets everything between chats"
|
||||
|
||||
**Context that scales:** Auto-summarized conversations and context-window management so agents never lose track, regardless of conversation length.
|
||||
You need memory: session management, message storage, context handling. It's table stakes, but surprisingly complex to get right.
|
||||
|
||||
**User understanding:** Rich psychological profiles built through [theory of mind](../core-concepts/glossary#cognitive-science-terms) "How should I deliver feedback to this user?" or "What's their communication style?"
|
||||
> "My agent treats everyone exactly the same"
|
||||
|
||||
**Adaptive interactions:** Instead of generic responses, agents dynamically adjust based on individual user models, creating truly personalized experiences.
|
||||
You need personalization: user modeling, preference learning, behavioral adaptation. Now you're building a [social cognition](../core-concepts/glossary#cognitive-science-terms) engine
|
||||
|
||||
Your agents move from remembering what users said to understanding how they think. The result: AI that feels less like a chatbot, more like someone who actually gets you.
|
||||
> "I'm writing infrastructure instead of features"
|
||||
|
||||
This is the [dialectic endpoint](glossary#dialectic-endpoint) in action - agents that don't just have context, but have insight.
|
||||
You need Honcho
|
||||
|
||||
<img src="/images/agent_hierarchy.png" alt="Honcho's Hiearchy of Agents" />
|
||||
|
||||
Honcho delivers production-ready memory infrastructure from day one. Store
|
||||
conversations, manage sessions, get perfectly formatted context for any LLM.
|
||||
But here's the magic: while your agents are chatting, Honcho is learning. It
|
||||
builds Theory of Mind models automatically, transforming raw conversations into
|
||||
rich psychological understanding.
|
||||
|
||||
```python
|
||||
# Start simple - just add messages
|
||||
session.add_messages([alice.message("I learn best with examples")])
|
||||
|
||||
# Get powerful - query user psychology
|
||||
insight = peer.chat("How should I explain this concept?")
|
||||
# > "This user learns best through concrete examples..."
|
||||
```
|
||||
|
||||
Your agents evolve from goldfish to counselor, on the same infrastructure. That's Honcho.
|
||||
|
||||
Designed for developers and agents alike:
|
||||
- **Natural Language Queries**: Chat with Honcho in natural language via the [Dialectic API](../core-concepts/glossary#storage-%26-processing) and let agents backchannel
|
||||
- **Automatic Context Management**: Smart summarization that respects token limits
|
||||
- **Native multi-agent support**: Break out of User/Assistant Paradigms and build complex multi-agent systems
|
||||
- **Agent-first interfaces**: MCP connections and APIs designed for agents to consume and use as tools
|
||||
- **Provider Agnostic**: Works with any LLM or Agent Framework
|
||||
|
||||
## How It Works
|
||||
|
||||
Honcho operates through two integrated layers:
|
||||
|
||||
**Storage 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.
|
||||
<img src="/images/basic_honcho_flowchart.png" alt="Basic Honcho Flowchart" />
|
||||
|
||||
**Insights 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.
|
||||
**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.
|
||||
|
||||
Agents access this understanding through the [dialectic endpoint](glossary#dialectic-endpoint) - a natural language API where they can ask specific questions about users and receive actionable insights.
|
||||
**Insights 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.
|
||||
|
||||
## Key Capabilities
|
||||
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.
|
||||
|
||||
### 🗣️ Natural Language User Queries
|
||||
Ask Honcho about users in plain English: "How should I approach this topic?" or "What's their preferred communication style?"
|
||||
|
||||
### 🔄 Automatic Context Optimization
|
||||
Smart conversation summarization that respects context windows while preserving psychological continuity.
|
||||
|
||||
### 🏗️ Agent-First Design
|
||||
Built for AI consumption through MCP connectors and interfaces designed for autonomous agent workflows.
|
||||
|
||||
### 🧠 Theory of Mind Inference
|
||||
Goes beyond pattern matching to understand user psychology, motivations, and mental models.
|
||||
Example Queries
|
||||
- "What's the best way to explain technical concepts to this user?"
|
||||
- "Is this user more task-oriented or relationship-oriented?"
|
||||
- "What time of day is this user most engaged?"
|
||||
- "How does this user prefer to receive feedback?"
|
||||
- "What are this user's core values based on our conversations?"
|
||||
|
||||
## Ideal For
|
||||
|
||||
|
|
@ -50,18 +80,17 @@ Goes beyond pattern matching to understand user psychology, motivations, and men
|
|||
|
||||
**Multi-agent systems** where AI needs to understand human collaborators' working styles and decision-making patterns.
|
||||
|
||||
**NPCs** where you want autonomous agents with a rich and deep personality that isn't the average sycophantic llm
|
||||
|
||||
## Getting Started
|
||||
|
||||
Ready to integrate Honcho into your application?
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Quick Start Guide" icon="rocket" href="/v2/documentation/introduction/quickstart">
|
||||
Get up and running with Honcho in minutes
|
||||
</Card>
|
||||
<Card title="Core Concepts" icon="brain" href="/v2/documentation/core-concepts/glossary">
|
||||
Understand Honcho's fundamental concepts
|
||||
</Card>
|
||||
</CardGroup>
|
||||
<CardGroup cols={2}> <Card title="Quick Start Guide" icon="rocket"
|
||||
href="/v2/documentation/introduction/quickstart"> Get up and running with
|
||||
Honcho in minutes </Card> <Card title="Core Concepts" icon="brain"
|
||||
href="/v2/documentation/core-concepts/glossary"> Understand Honcho's
|
||||
fundamental concepts </Card> </CardGroup>
|
||||
|
||||
## Community & Support
|
||||
|
||||
|
|
|
|||
|
|
@ -4,8 +4,6 @@ description: 'Start building with Honcho in under 5 minutes.'
|
|||
icon: 'bolt'
|
||||
---
|
||||
|
||||
<Tip>📢 **Announcing Honcho Platform**: We've raised $5.35M pre-seed from Variant, White Star Capital & Betaworks to build the personal identity layer for AI!</Tip>
|
||||
|
||||
For production-level use, Honcho offers two powerful ways to leverage ambient personalization: our managed platform and our open source solution. Read further if you want to explore the quickstart demo.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ description: "Honcho is the personal identity platform for AI - enabling truly p
|
|||
|
||||
<Card title="Sign up to start using Honcho!" icon="rocket" href="https://app.honcho.dev">
|
||||
Start using the platform to manage Honcho instances for your workspace or app.
|
||||
</Card>
|
||||
</Card>
|
||||
|
||||
## Welcome to Honcho!
|
||||
|
||||
Loading…
Reference in New Issue