fix: overview draft, rough reorg
This commit is contained in:
vintro
parent
ace8558388
commit
36a468e00a
|
|
@ -26,64 +26,41 @@
|
|||
"group": "Introduction",
|
||||
"pages": [
|
||||
"v2/documentation/introduction/overview",
|
||||
"v2/documentation/introduction/architecture",
|
||||
"v2/documentation/introduction/vibecoding"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Honcho Context",
|
||||
"group": "Core Concepts",
|
||||
"pages": [
|
||||
"v2/documentation/honcho-context/quickstart",
|
||||
{
|
||||
"group": "Storage",
|
||||
"expanded": true,
|
||||
"pages": [
|
||||
"v2/documentation/honcho-context/storage/storing-data",
|
||||
"v2/documentation/honcho-context/storage/file-uploads"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Retrieval",
|
||||
"expanded": true,
|
||||
"pages": [
|
||||
"v2/documentation/honcho-context/retrieval/using-filters",
|
||||
"v2/documentation/honcho-context/retrieval/search",
|
||||
"v2/documentation/honcho-context/retrieval/get-context"
|
||||
]
|
||||
}
|
||||
"v2/documentation/reference/storage",
|
||||
"v2/documentation/core-concepts/deriver",
|
||||
"v2/documentation/core-concepts/representation"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Honcho Memory",
|
||||
"group": "Features",
|
||||
"pages": [
|
||||
"v2/documentation/honcho-memory/quickstart",
|
||||
{
|
||||
"group": "Advanced Storage",
|
||||
"expanded": true,
|
||||
"pages": [
|
||||
"v2/documentation/core-concepts/features/queue-status",
|
||||
"v2/documentation/core-concepts/features/working-rep"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Advanced Retrieval",
|
||||
"expanded": true,
|
||||
"pages": [
|
||||
"v2/documentation/honcho-memory/advanced-retrieval/get-context",
|
||||
"v2/documentation/core-concepts/summarizer",
|
||||
"v2/documentation/core-concepts/features/dialectic-endpoint",
|
||||
"v2/documentation/core-concepts/features/streaming-response"
|
||||
]
|
||||
}
|
||||
"v2/documentation/features/get-context",
|
||||
"v2/documentation/features/dialectic-endpoint",
|
||||
"v2/documentation/features/summarizer",
|
||||
"v2/documentation/features/working-rep",
|
||||
"v2/documentation/features/local-vs-global"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Advanced",
|
||||
"pages": [
|
||||
"v2/documentation/advanced/configuration",
|
||||
"v2/documentation/advanced/queue-status",
|
||||
"v2/documentation/advanced/streaming-response",
|
||||
"v2/documentation/advanced/file-uploads",
|
||||
"v2/documentation/advanced/search",
|
||||
"v2/documentation/advanced/using-filters"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Reference",
|
||||
"pages": [
|
||||
"v2/documentation/core-concepts/architecture",
|
||||
"v2/documentation/core-concepts/configuration",
|
||||
"v2/documentation/core-concepts/features/local-vs-global",
|
||||
"v2/documentation/core-concepts/glossary",
|
||||
"v2/documentation/reference/platform",
|
||||
"v2/documentation/reference/sdk"
|
||||
]
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
|
|
@ -1,55 +0,0 @@
|
|||
---
|
||||
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.
|
||||
|
||||
#### 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.
|
||||
|
||||
#### 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.
|
||||
|
||||
#### 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.
|
||||
|
||||
#### Semantic Search
|
||||
Search based on meaning rather than exact keyword matching, often using embeddings.
|
||||
|
||||
#### 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 Terms
|
||||
|
||||
#### 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.
|
||||
|
||||
## Cognitive Science Terms
|
||||
|
||||
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.
|
||||
|
||||
#### 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,292 +0,0 @@
|
|||
---
|
||||
title: 'Quickstart - Honcho Context'
|
||||
icon: 'bolt'
|
||||
sidebarTitle: 'Quickstart'
|
||||
---
|
||||
|
||||
Implement Honcho Context in just a few steps. No signup required.
|
||||
|
||||
<Note>
|
||||
By default, the SDK uses the demo server hosted at demo.honcho.dev. The demo server is meant for quick experimentation and the data is cleared on a regular basis. Do not use for production applications.
|
||||
</Note>
|
||||
|
||||
## 1. Install the SDK
|
||||
|
||||
<CodeGroup>
|
||||
```bash Python (uv)
|
||||
uv add honcho-ai
|
||||
```
|
||||
|
||||
```bash Python (pip)
|
||||
pip install honcho-ai
|
||||
```
|
||||
|
||||
```bash TypeScript (npm)
|
||||
npm install @honcho-ai/sdk
|
||||
```
|
||||
|
||||
```bash TypeScript (yarn)
|
||||
yarn add @honcho-ai/sdk
|
||||
```
|
||||
|
||||
```bash TypeScript (pnpm)
|
||||
pnpm add @honcho-ai/sdk
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## 2. Initialize the Client
|
||||
|
||||
The Honcho client is the main entry point for interacting with Honcho's API. By default, it uses the demo environment and a default workspace.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
from honcho import Honcho
|
||||
|
||||
# Initialize client (uses demo environment and default workspace)
|
||||
honcho = Honcho()
|
||||
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Honcho } from '@honcho-ai/sdk';
|
||||
|
||||
// Initialize client (uses demo environment and default workspace)
|
||||
const honcho = new Honcho({});
|
||||
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## 3. Create Peers
|
||||
|
||||
Peers represent individual users, AI agents, or any entity in your system:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
alice = honcho.peer("alice")
|
||||
bob = honcho.peer("bob")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const alice = await honcho.peer("alice")
|
||||
const bob = await honcho.peer("bob")
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## 4. Create a Session
|
||||
|
||||
Sessions can be used to organize messages amongst peers.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
session = honcho.session("session_1", config={"deriver_disabled": True})
|
||||
session.add_peers([alice, bob])
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const session = await honcho.session("session_1", {config:{"deriver_disabled": true}});
|
||||
await session.addPeers([alice, bob])
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Note>
|
||||
In Honcho, memory is a reasoning task. By default it runs inference over every message. To use Honcho just for context engineering, you can toggle off this behavior.
|
||||
</Note>
|
||||
|
||||
## 5. Add Messages
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
session.add_messages([
|
||||
alice.message("Hi Bob, how are you?"),
|
||||
bob.message("I'm good, thank you!"),
|
||||
alice.message("What are you doing today after work?"),
|
||||
bob.message("I'm going to the gym! I've been trying to get back in shape."),
|
||||
alice.message("That's great! I should probably start exercising too."),
|
||||
bob.message("You should! I find that evening workouts help me relax."),
|
||||
])
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
await session.addMessages([
|
||||
alice.message("Hi Bob, how are you?"),
|
||||
bob.message("I'm good, thank you!"),
|
||||
alice.message("What are you doing today after work?"),
|
||||
bob.message("I'm going to the gym! I've been trying to get back in shape."),
|
||||
alice.message("That's great! I should probably start exercising too."),
|
||||
bob.message("You should! I find that evening workouts help me relax."),
|
||||
])
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## 6. Get Context
|
||||
|
||||
Curating your peer's context window is remarkably simple. The `get_context` method pulls recent messages for you based on a token limit.
|
||||
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
context = session.get_context() # chain with .to_openAI() or .to_anthropic() to format for APIs
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const context = await session.getContext(); // chain with .toOpenAI() or .toAnthropic() to format for APIs
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
|
||||
|
||||
## 7. Putting it all together
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import os
|
||||
from openai import OpenAI
|
||||
from dotenv import load_dotenv
|
||||
from honcho import Honcho
|
||||
|
||||
# Load environment variables (e.g., OPENAI_API_KEY in .env file)
|
||||
load_dotenv()
|
||||
|
||||
# Create OpenAI client
|
||||
openai_client = OpenAI()
|
||||
|
||||
# Create your Honcho client
|
||||
honcho = Honcho()
|
||||
|
||||
# Create your peers
|
||||
alice = honcho.peer("alice")
|
||||
bob = honcho.peer("bob")
|
||||
|
||||
# Make a session, add peers to the session
|
||||
session = honcho.session("session_1", config={"deriver_disabled": True})
|
||||
session.add_peers([alice, bob])
|
||||
|
||||
# Add messages sent by your peers
|
||||
session.add_messages([
|
||||
alice.message("Hi Bob, how are you?"),
|
||||
bob.message("I'm good, thank you!"),
|
||||
alice.message("What are you doing today after work?"),
|
||||
bob.message("I'm going to the gym! I've been trying to get back in shape."),
|
||||
alice.message("That's great! I should probably start exercising too."),
|
||||
bob.message("You should! I find that evening workouts help me relax."),
|
||||
])
|
||||
|
||||
# Get context for LLM
|
||||
messages = session.get_context(tokens=2000).to_openai(assistant=bob)
|
||||
|
||||
# Add new user message and get AI response
|
||||
messages.append({
|
||||
"role": "user",
|
||||
"content": "Oh maybe I'll find them relaxing as well!"
|
||||
})
|
||||
|
||||
response = openai_client.chat.completions.create(
|
||||
model="gpt-4o",
|
||||
messages=messages
|
||||
)
|
||||
|
||||
# Add AI response back to session
|
||||
session.add_messages([
|
||||
user.message("Oh maybe I'll find them relaxing as well!"),
|
||||
assistant.message(response.choices[0].message.content)
|
||||
])
|
||||
|
||||
print(response.choices[0].message.content)
|
||||
# Expected Output: something like "Definitely! Plus, it's a great way to end the day."
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import * as dotenv from 'dotenv';
|
||||
import OpenAI from 'openai';
|
||||
import { Honcho } from '@honcho-ai/sdk';
|
||||
|
||||
// Load environment variables (e.g., OPENAI_API_KEY in .env file)
|
||||
dotenv.config();
|
||||
|
||||
// Create OpenAI client
|
||||
const openai = new OpenAI({
|
||||
apiKey: process.env.OPENAI_API_KEY,
|
||||
});
|
||||
|
||||
// Create your Honcho client
|
||||
const honcho = new Honcho({});
|
||||
|
||||
// Main async function to handle everything
|
||||
async function main() {
|
||||
try {
|
||||
// Create peers
|
||||
const alice = await honcho.peer("alice");
|
||||
const bob = await honcho.peer("bob");
|
||||
|
||||
// Make a session, add peers to the session
|
||||
const session = await honcho.session("session_1", {config:{"deriver_disabled": true}});
|
||||
await session.addPeers([alice, bob]);
|
||||
|
||||
// Add messages sent by your peers
|
||||
await session.addMessages([
|
||||
alice.message("Hi Bob, how are you?"),
|
||||
bob.message("I'm good, thank you!"),
|
||||
alice.message("What are you doing today after work?"),
|
||||
bob.message("I'm going to the gym! I've been trying to get back in shape."),
|
||||
alice.message("That's great! I should probably start exercising too."),
|
||||
bob.message("You should! I find that evening workouts help me relax."),
|
||||
]);
|
||||
|
||||
// Get context for LLM (await the context first, then call toOpenAI)
|
||||
const context = await session.getContext({ tokens: 2000 });
|
||||
const messages = context.toOpenAI(bob)
|
||||
// Add new user message
|
||||
messages.push({
|
||||
role: "user",
|
||||
content: "Oh maybe I'll find them relaxing as well!"
|
||||
});
|
||||
|
||||
// Get AI response
|
||||
const response = await openai.chat.completions.create({
|
||||
model: "gpt-4o",
|
||||
messages: messages,
|
||||
});
|
||||
|
||||
const aiResponse = response.choices[0].message.content;
|
||||
|
||||
// Add AI response back to session (user as alice, AI as bob)
|
||||
await session.addMessages([
|
||||
alice.message("Oh maybe I'll find them relaxing as well!"),
|
||||
bob.message(aiResponse!),
|
||||
]);
|
||||
|
||||
// Print the AI response
|
||||
console.log(aiResponse);
|
||||
} catch (error) {
|
||||
console.error('Error running the script:', error);
|
||||
}
|
||||
}
|
||||
|
||||
// Run the main function
|
||||
main();
|
||||
// Expected Output: something like "Definitely! Plus, it's a great way to end the day."
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## Recap
|
||||
|
||||
1. We set up our connection to Honcho.
|
||||
2. Created our peers.
|
||||
3. Made a session and added our peers.
|
||||
4. Added messages from our peers to the session.
|
||||
5. Used the `get_context` method to structure a stateful request to OpenAI.
|
||||
|
||||
We're just scratching the surface. Choose from one of the cards below to keep building with Honcho.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Get Context" icon="rocket"
|
||||
href="/v2/documentation/core-concepts/features/get-context">
|
||||
Learn more about the power and flexibility of the `get_context` method
|
||||
</Card>
|
||||
<Card title="Start Building" icon="wrench" href="https://app.honcho.dev">
|
||||
Sign up on the Honcho Platform for unlimited storage and retrieval
|
||||
</Card>
|
||||
<Card title="Honcho Memory" icon="brain" href="/v2/guides/overview">
|
||||
Leverage the advanced reasoning capabilities in Honcho
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
|
@ -1,61 +0,0 @@
|
|||
---
|
||||
title: Storing Data
|
||||
description: "Store Data in Honcho to Generate Memories and Insights"
|
||||
icon: "memory"
|
||||
---
|
||||
|
||||
The most basic building block of Honcho's data model is the `Message` object.
|
||||
A `Message` is sent by a `Peer` and saved in a `Session`
|
||||
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
from honcho import Honcho
|
||||
|
||||
honcho = Honcho()
|
||||
|
||||
peer = honcho.peer("sample-peer")
|
||||
|
||||
session = honcho.session("sample-session")
|
||||
|
||||
message = peer.message("Hello, world!", session_id=session.id)
|
||||
|
||||
session.add_messages([message])
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Honcho } from '@honcho-ai/sdk';
|
||||
|
||||
const honcho = new Honcho({});
|
||||
|
||||
const peer = await honcho.peer('sample-peer');
|
||||
|
||||
const session = await honcho.session('sample-session');
|
||||
|
||||
const message = peer.message('Hello, world!');
|
||||
|
||||
await session.addMessages([message]);
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Once a `Message` is saved in Honcho, it will kick off a background task that
|
||||
looks at the new data to generate insights about the `Peer` that sent the `Message`
|
||||
|
||||
This is the default behavior of Honcho and can be turned off by [configuring the
|
||||
Peer or Session](/v2/documentation/core-concepts/configuration)
|
||||
|
||||
This pattern of having a Peer, Session, and Messages is highly flexible and
|
||||
works for many different use cases and agent setups. Some use cases may only
|
||||
need a single Peer, but many Sessions. Others will only use a single `Session`
|
||||
for their entire app. These are flexible components that work in any situation.
|
||||
|
||||
## Chat Bots
|
||||
|
||||
A common use case for Honcho to is to build a chatbot like ChatGPT or Claude.
|
||||
In this case you can simply
|
||||
|
||||
- Make a `Peer` for the User
|
||||
- Make a `Peer` for the AI
|
||||
|
||||
Then you can make a `Session` for each thread of conversation and save
|
||||
`Messages` from the user and assistant in each turn of conversation
|
||||
|
|
@ -1,268 +0,0 @@
|
|||
---
|
||||
title: "Architecture & Intuition"
|
||||
description: "Understanding Honcho's data model and core concepts."
|
||||
icon: "sitemap"
|
||||
sidebarTitle: "Architecture"
|
||||
---
|
||||
|
||||
<Note> The goal of this page is to build an intuition for the primitives in Honcho and how they fit together </Note>
|
||||
|
||||
Honcho has 2 main components that work together to manage agent context and memory.
|
||||
|
||||
- **The Context Layer**: For storing and retrieving interaction history for your agents.
|
||||
- **The Memory Layer**: Background processing that builds representations of users and agents.
|
||||
|
||||
## Data Model
|
||||
|
||||
Honcho has a hierarchical data model centered around the entities below.
|
||||
|
||||
<div style={{ display: 'flex', justifyContent: 'center' }}>
|
||||
```mermaid
|
||||
graph TD
|
||||
W[Workspaces] -->|have| P[Peers]
|
||||
W -->|have| S[Sessions]
|
||||
|
||||
S -->|have| SM[Messages]
|
||||
|
||||
P <-.->|many-to-many| S
|
||||
|
||||
style W fill:#B6DBFF,stroke:#333,color:#000
|
||||
style P fill:#B6DBFF,stroke:#333,color:#000
|
||||
style S fill:#B6DBFF,stroke:#333,color:#000
|
||||
style SM fill:#B6DBFF,stroke:#333,color:#000
|
||||
```
|
||||
</div>
|
||||
|
||||
- A `Workspace` has `Peers` & `Sessions`
|
||||
- A `Peer` can be in multiple `Sessions` and can send `Messages` in a `Session`.
|
||||
- A `Session` can have many `Peers` and stores `Messages` sent by its `Peers`.
|
||||
|
||||
---
|
||||
|
||||
<div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
|
||||
<Icon icon="building" />
|
||||
<h3 style={{ margin: 0 }}>Workspaces</h3>
|
||||
</div>
|
||||
|
||||
Workspaces are the top-level containers that provide complete isolation between different applications or environments; they essentially serve as a namespace to isolate different workloads or environments.
|
||||
|
||||
|
||||
|
||||
**Key Features:**
|
||||
- **Isolation**: Complete data separation between workspaces
|
||||
- **Multi-tenancy**: Support multiple applications or environments
|
||||
- **Configuration**: Workspace-level settings and metadata
|
||||
- **Access Control**: Authentication scoped to workspace level
|
||||
|
||||
**Use Cases:**
|
||||
- Separate development/staging/production environments
|
||||
- Multi-tenant SaaS applications
|
||||
- Different product lines or use cases
|
||||
- Complete data separation between teams
|
||||
|
||||
---
|
||||
|
||||
<div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
|
||||
<Icon icon="user" />
|
||||
<h3 style={{ margin: 0 }}>Peers</h3>
|
||||
</div>
|
||||
|
||||
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
|
||||
- **Memory Storage**: Personal memory and context accumulation
|
||||
- **Configuration**: Per-peer behavioral settings
|
||||
- **Cross-Session Context**: Memory persists across all sessions
|
||||
|
||||
**Use Cases:**
|
||||
- Individual users in chatbot applications
|
||||
- AI agents interacting with users or other agents
|
||||
- Customer profiles in support systems
|
||||
- Student profiles in educational platforms
|
||||
- NPCs in role-playing games
|
||||
|
||||
---
|
||||
|
||||
<div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
|
||||
<Icon icon="message" />
|
||||
<h3 style={{ margin: 0 }}>Sessions</h3>
|
||||
</div>
|
||||
|
||||
Sessions represent individual conversation threads or interaction contexts between peers.
|
||||
|
||||
**Key Features:**
|
||||
- **Multi-Peer**: Support multiple peers in a single session
|
||||
- **Temporal Boundaries**: Clear start/end to conversation threads
|
||||
- **Context Scoping**: Session-specific memory and context
|
||||
- **Configuration**: Session-level behavioral controls
|
||||
|
||||
**Use Cases:**
|
||||
- Individual chat conversations
|
||||
- Support tickets
|
||||
- Meeting transcripts
|
||||
- Learning sessions
|
||||
- Single-Peer onboarding sessions where data is imported from an external source
|
||||
|
||||
---
|
||||
|
||||
<div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
|
||||
<Icon icon="envelope" />
|
||||
<h3 style={{ margin: 0 }}>Messages</h3>
|
||||
</div>
|
||||
|
||||
Messages are the fundamental units of interaction within sessions. They may
|
||||
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
|
||||
- **Attribution**: Clear association with sending peer
|
||||
- **Ordering**: Chronological sequence within sessions
|
||||
- **Processing**: Automatic background analysis and insight derivation
|
||||
|
||||
**Message Types:**
|
||||
- User messages
|
||||
- AI responses
|
||||
- System notifications
|
||||
- Rich media content
|
||||
- User actions (clicked, reacted, etc.)
|
||||
- File uploads (PDFs, text files, JSON documents)
|
||||
|
||||
|
||||
## Reasoning Layer
|
||||
|
||||
The raw data you store in Honcho is useful, but it's not in a format that's most
|
||||
useful for an LLM to consume. There may be too many tokens that need to be
|
||||
compacted, key facts about what happened may be hard to piece together because
|
||||
they involve messages from across different sessions, etc.
|
||||
|
||||
To solve this problem, Honcho has a reasoning layer that continually processes
|
||||
incoming data to form the most informationally dense and useful representations of `Peers`
|
||||
that we can then expose to agents. Honcho does the following tasks in
|
||||
the reasoning engine.
|
||||
|
||||
- **Fact Derivation**
|
||||
- **Generate Summaries**
|
||||
- **Generate Peer Cards**
|
||||
- **Dreaming**
|
||||
|
||||
|
||||
Honcho will reason about each `Message` it
|
||||
ingests to generate new facts and insights that are spelled out and easy to
|
||||
consume in an LLM prompt.
|
||||
|
||||
We refer to this module of Honcho as the `Deriver`, because it's constantly
|
||||
deriving new insights from messages. The sum total of all these generated
|
||||
insights are what we refer to as a `Representation`, all the data related to who
|
||||
and what a `Peer` is.
|
||||
|
||||
Depending on the configuration of a `Peer` or `Session`, the deriver will behave
|
||||
differently and update different representations.
|
||||
|
||||
Facts derived here are used in the Dialectic chat endpoint, get_context
|
||||
endpoint,
|
||||
|
||||
<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>
|
||||
|
||||
There are two types of tasks that the deriver currently does:
|
||||
|
||||
- **Representation Tasks**: Generate/update peer representations
|
||||
- **Summary Tasks**: Generate conversation summaries
|
||||
|
||||
### Local & Global Representations
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
<img src="/images/local-vs-global-reps.png" alt="Peer Representations" />
|
||||
|
||||
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 the user's mood today?") # ✅ Ideal
|
||||
|
||||
alice.chat("What is alice's mood today?") # ✅ Works -- but make sure to consider what peer "Alice" has been saying in their messages about name/identity.
|
||||
|
||||
alice.chat("What is your mood today?") # ❌ Likely to fail -- the dialectic agent may conflate itself and the user.
|
||||
```
|
||||
|
||||
<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>
|
||||
|
||||
## Next Steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Platform SDK" icon="code" href="/v2/documentation/reference/sdk">
|
||||
Learn how to use the SDK to interact with the data model
|
||||
</Card>
|
||||
<Card title="Glossary" icon="book" href="/v2/documentation/core-concepts/glossary">
|
||||
Reference for all technical terms and concepts
|
||||
</Card>
|
||||
<Card title="API Reference" icon="play" href="/v2/api-reference/introduction">
|
||||
Detailed API documentation and examples
|
||||
</Card>
|
||||
<Card title="Quickstart" icon="rocket" href="/v2/documentation/introduction/quickstart">
|
||||
Get started with your first integration
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
|
@ -1,77 +1,450 @@
|
|||
---
|
||||
title: "Honcho"
|
||||
title: "Honcho Overview"
|
||||
icon: "brain"
|
||||
sidebarTitle: "Overview"
|
||||
---
|
||||
|
||||
Honcho gives agents state-of-the-art memory.
|
||||
Honcho is an open source memory library with a managed service for building stateful agents. Use it with any model, framework, or architecture. You can represent any kind of entity as a stateful agent--users, AIs, groups of users, and more. Using Honcho as your memory system will earn your agents higher retention, more trust, and help you build data moats to out-compete incumbents.
|
||||
|
||||
It's is a flexible yet powerful library. Available through a managed platform and an open source repository for self-hosting.
|
||||
<Note>
|
||||
Honcho is a memory system that reasons. Read more on the approach [here](https://blog.plasticlabs.ai/blog/Memory-as-Reasoning).
|
||||
</Note>
|
||||
|
||||
Honcho can be understood by developers through two lenses--context and memory.
|
||||
## What Can I Use Honcho For?
|
||||
|
||||
Honcho streamlines the agent building process by offering elegant, flexible primitives for managing context. It also reasons over that context in order to give developers access to far richer context only accessible by doing so. Take the following scenario:
|
||||
|
||||
- You find a use case for LLMs that you want to build an application or agent around
|
||||
- It performs well but fails to retain state on the task, customers, or itself over time
|
||||
- You laboriously engineer a RAG solution that seems to help
|
||||
- Then a cycle like this begins...
|
||||
- Reports of edge cases, erroneous behavior, and other unpredictable problems that stem from context
|
||||
- You launch into an evals rabbithole and build internal benchmarks
|
||||
- Re-engineer your entire RAG solution
|
||||
- Repeat
|
||||
|
||||
All the while usage dwindles, customers churn, and motivation to solve the problem wanes. Break free from this cycle. Honcho is a general solution to solving context engineering, memory, and statefulness.
|
||||
|
||||
### Context Engineering
|
||||
|
||||
Honcho makes it easy for developers to intitialize, store, retrieve, and scale all the LLM interaction points in your AI app or agent. It has a hierarchical data model centered around the entities below.
|
||||
|
||||
|
||||
## Honcho Context
|
||||
```mermaid
|
||||
graph LR
|
||||
W[Workspaces] -->|have| P[Peers]
|
||||
W -->|have| S[Sessions]
|
||||
|
||||
Building LLM-powered systems is still a massive orchestration problem. Just getting a multi-user application off the ground requires extensive database and infrastructure knowledge. Managing context windows for each respective user and scaling that system is far from trivial.
|
||||
S -->|have| SM[Messages]
|
||||
|
||||
Honcho offers elegant, flexible primitives for initializing, storing, retrieving, and scaling all the LLM interaction points in your AI app or agent. Easy orchestration, plus unlimited storage and unlimited retrieval, all out-of-the-box.
|
||||
P <-.->|many-to-many| S
|
||||
|
||||
Don't waste time redundantly building complex systems. Focus on what makes your product unique.
|
||||
style W fill:#B6DBFF,stroke:#333,color:#000
|
||||
style P fill:#B6DBFF,stroke:#333,color:#000
|
||||
style S fill:#B6DBFF,stroke:#333,color:#000
|
||||
style SM fill:#B6DBFF,stroke:#333,color:#000
|
||||
```
|
||||
|
||||
- A Workspace has Peers & Sessions
|
||||
- A Peer can be in multiple Sessions and can send Messages in a Session.
|
||||
- A Session can have many Peers and stores Messages sent by its Peers.
|
||||
|
||||
A [Peer](https://blog.plasticlabs.ai/blog/Beyond-the-User-Assistant-Paradigm;-Introducing-Peers) is the object Honcho uses to represent any entity--user, AI, group of people--anything you can think of as being the same from time $t$ to $t+1$. Each of the storage primitives along with peers are easy to configure and extend to fit your application's needs.
|
||||
|
||||
### Memory
|
||||
|
||||
Honcho is built around custom models that are selectively reasoning about context written to it. These models produce formal logic that powers the memory system. Each peer is the container for a *representation*(TODO: link to concept page)--the collection of reasoning that's been done over context written to it.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/reasoning.png" style={{ borderRadius: '0.5rem' }} />
|
||||
</Frame>
|
||||
|
||||
|
||||
## Honcho Memory
|
||||
The *deriver* (TODO: link to concept page) orchestrates all this reasoning in the background when you write messages to sessions or peers.
|
||||
|
||||
AI users want tasks completed in line with their evolving preferences. They want agents who can learn about them continuously over time. So, agents need as complete a picture of each user as possible on-demand.
|
||||
Let's start with a simple implementation.
|
||||
|
||||
Honcho is built around proprietary reasoning models that ensure the right context is always available. They create modular reasoning traces and compose with them to uncover new insights. Scaffolded reasoning is uniquely traversable, enabling fast context assembly, complete with citation, on-the-fly.
|
||||
## Quickstart
|
||||
|
||||
All this happens ambiently—Honcho stores and reasons over everything you write to it so it can recall and synthesize anything later.
|
||||
<Note>
|
||||
Running the code below requires an API key. Create and account and get your API key at [app.honcho.dev](https://app.honcho.dev) under "API KEYS".
|
||||
|
||||
Every new tenant gets \$100.00 in free credits on sign up. The code below costs ~\$0.04 to run, so don't worry--still plenty of free credits for iterating.
|
||||
</Note>
|
||||
|
||||
#### 1. Install the SDK
|
||||
|
||||
<CodeGroup>
|
||||
```bash Python (uv)
|
||||
uv add honcho-ai
|
||||
```
|
||||
|
||||
```bash Python (pip)
|
||||
pip install honcho-ai
|
||||
```
|
||||
|
||||
```bash TypeScript (npm)
|
||||
npm install @honcho-ai/sdk
|
||||
```
|
||||
|
||||
```bash TypeScript (yarn)
|
||||
yarn add @honcho-ai/sdk
|
||||
```
|
||||
|
||||
```bash TypeScript (pnpm)
|
||||
pnpm add @honcho-ai/sdk
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
#### 2. Initialize the Client
|
||||
|
||||
The Honcho client is the main entry point for interacting with Honcho's API. It uses a workspace called `default` unless specified, so let's create a `first-honcho-test` workspace for this quickstart.
|
||||
|
||||
TODO: change default environment to production, require an API key.
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
from honcho import Honcho
|
||||
|
||||
# Initialize client
|
||||
honcho = Honcho(workspace="first-honcho-test")
|
||||
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import { Honcho } from '@honcho-ai/sdk';
|
||||
|
||||
// Initialize client
|
||||
const honcho = new Honcho({ workspace = "first-honcho-test" });
|
||||
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
|
||||
## Key Features
|
||||
#### 3. Create Peers
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Flexible Primitives" icon="puzzle-piece">
|
||||
Supports any user model: user-assistant, multi-agent workflows, group chats, agents and sub-agents.
|
||||
</Card>
|
||||
<Card title="Modular Architecture" icon="layer-group">
|
||||
Easy to scale vertically and horizontally.
|
||||
</Card>
|
||||
<Card title="No Data Structure Management" icon="wand-magic-sparkles">
|
||||
Throw data into Honcho as messages—it figures out the structure and adapts to changes.
|
||||
</Card>
|
||||
<Card title="Directional Relationships" icon="arrows-left-right">
|
||||
Track what Alice thinks of Bob, not just Alice's preferences or Bob's preferences.
|
||||
</Card>
|
||||
<Card title="Self-Healing" icon="heart-pulse">
|
||||
If Honcho gets something wrong, it learns and corrects through continued use.
|
||||
</Card>
|
||||
<Card title="Unopinionated Data" icon="scale-balanced">
|
||||
Rule-based reasoning toward certain conclusions.
|
||||
</Card>
|
||||
<Card title="Traversable Storage" icon="magnifying-glass">
|
||||
Query the exact relevant context you need.
|
||||
</Card>
|
||||
<Card title="Any Stack" icon="cubes">
|
||||
Model-agnostic, framework-agnostic, composable with any stack—never forces you into proprietary tools.
|
||||
</Card>
|
||||
<Card title="Any Deployment" icon="cloud">
|
||||
Whether you've built a full platform or run agents somewhere else—Honcho works with your architecture.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
user = honcho.peer("user")
|
||||
assistant = honcho.peer("assistant")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
const user = await honcho.peer("user")
|
||||
const assistant = await honcho.peer("assistant")
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
#### 4. Add Messages to Sessions
|
||||
|
||||
We've generated an example conversation dataset with 14 messages across 4 sessions. At a high level, the conversation contains a user chatting with an assistant to get help debugging software infrastructure problems for work *and* jam strategy on a side project they're working on. Spoiler alert--the user is way more interested in their side project.
|
||||
|
||||
Create a file called `conversation.json` and add the content in the accordion below. Then we'll loop through the sessions and messages in that file and write them to Honcho.
|
||||
|
||||
|
||||
## Solve Memory
|
||||
<Accordion title="Example conversation.json">
|
||||
|
||||
In Honcho, memory is a reasoning task. Beyond static storage and retrieval or naive fact extraction, Honcho arrives at conclusions only accessible via rigorous reasoning.
|
||||
|
||||
When your agent needs user context, Honcho returns rich results, drawing on its self-improving body of composable reasoning and synthesizing exactly what's needed.
|
||||
|
||||
Memory is table stakes--it's the system that constructs context to make decisions about how to continue. Honcho is a state-of-the-art memory solution built in an AI-native way. Build your agents with a reasoning system that uniquely leverages LLMs to solve memory.
|
||||
```json Example Conversation
|
||||
{
|
||||
"sessions": [
|
||||
{
|
||||
"id": "session_1",
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": "containers getting OOM killed in CI after someone on my team updated the base image. quick fix?"
|
||||
},
|
||||
{
|
||||
"role": "assistant",
|
||||
"content": "OOM kills after a base image update usually means the new image has higher memory requirements. Quick fix: bump the memory limit in your CI config. If you need to unblock fast, you could also pin back to the previous base image version temporarily."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "session_2",
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": "hey, been playing with honcho for a side project. do you know if there's a limit on how many users i can have?"
|
||||
},
|
||||
{
|
||||
"role": "assistant",
|
||||
"content": "Honcho's free tier is based on context ingested, not number of users - so you can have as many users as you want, you're just limited by how much content you're processing. What are you building?"
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"content": "ok so basically it's a personal finance assistant that actually remembers your situation - like it knows you're saving for a house, that you hate subscriptions, that you always regret impulse buys over $50. i've been thinking a lot about the UX, like when should it proactively bring up past context vs wait for you to ask? and how do you balance feeling \"known\" vs feeling surveilled? i have a whole notion doc on this lol"
|
||||
},
|
||||
{
|
||||
"role": "assistant",
|
||||
"content": "That's a really thoughtful approach to the personalization problem! The \"known vs surveilled\" tension is exactly right - the best experiences feel like talking to a friend who remembers, not a system that tracks. Proactive context works best when it's in service of the user's stated goals."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "session_3",
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": "do i need to update docker-compose too or just the CI yaml for that memory thing"
|
||||
},
|
||||
{
|
||||
"role": "assistant",
|
||||
"content": "Just the CI yaml for the memory limit - docker-compose is separate and only matters if you're hitting the same OOM issue locally."
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"content": "k. oh btw 3 friends are using the finance app now, they keep asking when they can pay me lol. one of them said it's the first budgeting thing that \"gets\" her"
|
||||
},
|
||||
{
|
||||
"role": "assistant",
|
||||
"content": "That's awesome - \"when can I pay you\" is the best kind of validation. And that quote about it being the first thing that \"gets\" her is exactly the value prop of personalized memory. Sounds like you're onto something real."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "session_4",
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": "if i wanted to charge like $5/mo for the finance app, would honcho's pricing still make sense at that price point? trying to figure out unit economics early"
|
||||
},
|
||||
{
|
||||
"role": "assistant",
|
||||
"content": "You should be fine at that price point. Unlike other memory frameworks that charge you to access your own data, Honcho only charges for the reasoning layer - ingestion and inference. Storage and retrieval are free. So your unit economics are mostly about how often you're synthesizing insights, not how much history you're keeping."
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"content": "ok interesting. wish i had more time to work on this"
|
||||
},
|
||||
{
|
||||
"role": "assistant",
|
||||
"content": "Yeah, sounds like you've got something worth making time for. The early traction is real."
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
|
||||
<CardGroup cols={2}> <Card title="Honcho Context Quickstart" icon="rocket"
|
||||
href="/v2/documentation/honcho-context/quickstart"> Get up and running with
|
||||
Honcho in minutes </Card> <Card title="Honcho Memory Quickstart" icon="brain"
|
||||
href="/v2/documentation/honcho-memory/quickstart"> Leverage Honcho for Memory in minutes. </Card> </CardGroup>
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
import json
|
||||
|
||||
# Load conversation data
|
||||
with open("conversation.json", "r") as f:
|
||||
data = json.load(f)
|
||||
|
||||
# Process each session
|
||||
for session_data in data["sessions"]:
|
||||
session = honcho.session(session_data["id"])
|
||||
session.add_peers([user, assistant])
|
||||
|
||||
# Add messages with correct roles
|
||||
messages = []
|
||||
for msg in session_data["messages"]:
|
||||
if msg["role"] == "user":
|
||||
messages.append(user.message(msg["content"]))
|
||||
elif msg["role"] == "assistant":
|
||||
messages.append(assistant.message(msg["content"]))
|
||||
|
||||
session.add_messages(messages)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
import * as fs from 'fs';
|
||||
|
||||
const data = JSON.parse(fs.readFileSync("conversation.json", "utf-8"));
|
||||
|
||||
for (const sessionData of data.sessions) {
|
||||
const session = honcho.session(sessionData.id);
|
||||
session.addPeers([user, assistant]);
|
||||
|
||||
const messages = sessionData.messages.map((msg: any) =>
|
||||
msg.role === "user" ? user.message(msg.content) : assistant.message(msg.content)
|
||||
);
|
||||
|
||||
session.addMessages(messages);
|
||||
}
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
#### 5. Query for Insights
|
||||
|
||||
Now ask Honcho what it's learned - this is where the magic happens:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
response = user.chat("What should I know about this user? 3 sentences max")
|
||||
print(response)
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
user.chat("What should I know about this user? 3 sentences max").then((response) => {
|
||||
console.log(response);
|
||||
})
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Tip>
|
||||
Honcho needs a short amount of time to process messages you write to it. There are several utilities to (TODO: FIX LINK) <Link href="@v2/documentation/core-concepts/features/queue-status.mdx">check the status</Link> of the queue. Honcho also offers numerous ways to query reasoning to fit latency needs.
|
||||
</Tip>
|
||||
|
||||
The response will look something like this:
|
||||
|
||||
> User is a personal finance app developer building a personalized finance assistant that's generating real demand (friends are already asking when they can pay). They're notably thoughtful about product design, carefully considering the UX balance between making users feel "known" versus "surveilled" when their app proactively surfaces remembered context like savings goals and spending regrets. They're business-minded and working through unit economics early, exploring a $5/month subscription model with usage-based cost structure focused on insight generation frequency rather than data storage—though they wish they had more time to dedicate to the project.
|
||||
|
||||
Honcho synthesizes the signal based on the conclusions it was able to come to on the backend. Not only does it capture the basics of the conversation, but it reasons about the user to come to further conclusions. It identifies the user as "notably thoughtful about product design", "business-minded" from the discussion of unit economics, and surfaces the signal that they desire to work on the project more.
|
||||
|
||||
This is rich personal context for domain-specific agents to do what they want with.
|
||||
- A life coach agent might see "they wish they had more time to dedicate to the project" and "friends are already asking when they can pay" and ask "have you thought about what it would take to go full-time?"
|
||||
- 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](TODO: link to evals page here) performance on memory benchmarks, and our custom models allow us to optimize speed and cost.
|
||||
|
||||
|
||||
## Recap
|
||||
|
||||
Let's go over what we covered and implemented:
|
||||
|
||||
- Became familiarized with the data model and reasoning backend of Honcho
|
||||
- Signed up for the managed service, got an API key
|
||||
- Wrote code to use the data model, ingested some messages, and queried the representation
|
||||
|
||||
<Accordion title="Full Scripts">
|
||||
|
||||
<CodeGroup>
|
||||
|
||||
```python Python
|
||||
# uv sync
|
||||
# uv run python test.py
|
||||
|
||||
import json
|
||||
import time
|
||||
import uuid
|
||||
|
||||
from honcho import Honcho
|
||||
from dotenv import load_dotenv
|
||||
|
||||
load_dotenv()
|
||||
|
||||
# Initialize Honcho client with a unique workspace
|
||||
workspace_id = f"docs-example-{uuid.uuid4().hex[:8]}"
|
||||
honcho = Honcho(environment="production", workspace_id=workspace_id)
|
||||
|
||||
# Create peers to represent the user and assistant
|
||||
user = honcho.peer("user")
|
||||
assistant = honcho.peer("assistant")
|
||||
|
||||
# Load conversation data from JSON file
|
||||
with open("conversation.json", "r") as f:
|
||||
conversation_data = json.load(f)
|
||||
|
||||
# Import historical conversation sessions
|
||||
for session_data in conversation_data["sessions"]:
|
||||
session = honcho.session(session_data["id"])
|
||||
session.add_peers([user, assistant])
|
||||
|
||||
# Convert messages to peer messages with correct attribution
|
||||
messages = []
|
||||
for msg in session_data["messages"]:
|
||||
if msg["role"] == "user":
|
||||
messages.append(user.message(msg["content"]))
|
||||
elif msg["role"] == "assistant":
|
||||
messages.append(assistant.message(msg["content"]))
|
||||
|
||||
session.add_messages(messages)
|
||||
|
||||
# Wait for Honcho to process the conversation history
|
||||
def wait_for_processing():
|
||||
status = honcho.get_deriver_status()
|
||||
while status.pending_work_units > 0 or status.in_progress_work_units > 0:
|
||||
time.sleep(1)
|
||||
status = honcho.poll_deriver_status()
|
||||
|
||||
print("Processing conversation history...")
|
||||
start_time = time.time()
|
||||
wait_for_processing()
|
||||
elapsed = int(time.time() - start_time)
|
||||
print(f"Done in {elapsed}s! Querying user insights...\n")
|
||||
|
||||
# Query insights about the user based on conversation history
|
||||
response = user.chat("What should I know about this user? 3 sentences max")
|
||||
print(response)
|
||||
```
|
||||
|
||||
```typescript Typescript
|
||||
// npm install
|
||||
// npx ts-node test.ts
|
||||
|
||||
import * as fs from 'fs';
|
||||
import { randomUUID } from 'crypto';
|
||||
import * as dotenv from 'dotenv';
|
||||
import { Honcho } from '@honcho-ai/sdk';
|
||||
|
||||
dotenv.config();
|
||||
|
||||
// Initialize Honcho client with a unique workspace
|
||||
const workspaceId = `docs-example-${randomUUID().slice(0, 8)}`;
|
||||
const honcho = new Honcho({
|
||||
environment: "production",
|
||||
workspaceId,
|
||||
});
|
||||
|
||||
// Create peers to represent the user and assistant
|
||||
const user = await honcho.peer("user");
|
||||
const assistant = await honcho.peer("assistant");
|
||||
|
||||
// Load conversation data from JSON file
|
||||
const conversationData = JSON.parse(fs.readFileSync("conversation.json", "utf-8"));
|
||||
|
||||
// Import historical conversation sessions
|
||||
for (const sessionData of conversationData.sessions) {
|
||||
const session = await honcho.session(sessionData.id);
|
||||
await session.addPeers([user, assistant]);
|
||||
|
||||
// Convert messages to peer messages with correct attribution
|
||||
const messages = [];
|
||||
for (const msg of sessionData.messages) {
|
||||
if (msg.role === "user") {
|
||||
messages.push(user.message(msg.content));
|
||||
} else if (msg.role === "assistant") {
|
||||
messages.push(assistant.message(msg.content));
|
||||
}
|
||||
}
|
||||
|
||||
await session.addMessages(messages);
|
||||
}
|
||||
|
||||
// Wait for Honcho to process the conversation history
|
||||
async function waitForProcessing() {
|
||||
let status = await honcho.getDeriverStatus();
|
||||
while (status.pendingWorkUnits > 0 || status.inProgressWorkUnits > 0) {
|
||||
await new Promise(resolve => setTimeout(resolve, 1000));
|
||||
status = await honcho.pollDeriverStatus();
|
||||
}
|
||||
}
|
||||
|
||||
console.log("Processing conversation history...");
|
||||
const startTime = Date.now();
|
||||
await waitForProcessing();
|
||||
const elapsed = Math.floor((Date.now() - startTime) / 1000);
|
||||
console.log(`Done in ${elapsed}s! Querying user insights...\n`);
|
||||
|
||||
// Query insights about the user based on conversation history
|
||||
const response = await user.chat("What should I know about this user? 3 sentences max");
|
||||
console.log(response);
|
||||
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
</Accordion>
|
||||
|
||||
We're just scratching the surface. The data objects have a number of cool features that make building stateful agents easier. There are several ways to query both context and reasoning in order to power memory for agents. And everything has been built with the intention of giving the developer maximum control--leverage as much or as little of the reasoning as you want, tightly control token usage, latency, and more.
|
||||
|
||||
Welcome to Honcho. We're excited to have you at the frontier of AI with us 🫡.
|
||||
|
||||
TODO: cards to concepts?
|
||||
|
|
@ -1,425 +0,0 @@
|
|||
---
|
||||
title: 'Guided Tutorial'
|
||||
description: 'Step-by-step tutorial for building with Honcho'
|
||||
icon: 'graduation-cap'
|
||||
---
|
||||
|
||||
This comprehensive tutorial will walk you through building a complete AI application with Honcho, from basic setup to advanced features.
|
||||
|
||||
## What We'll Build
|
||||
|
||||
By the end of this tutorial, you'll have created a personal AI assistant that:
|
||||
- Learns about users through conversation and remembers facts across sessions
|
||||
- Automatically formats conversation context for any LLM (OpenAI, Anthropic, etc.)
|
||||
- Answers questions about what it knows using natural language queries
|
||||
- Handles multi-party conversations with theory-of-mind modeling
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.8 or higher
|
||||
- Basic understanding of Python
|
||||
- OpenAI API key (or another LLM provider)
|
||||
|
||||
## Part 1: Basic Setup
|
||||
|
||||
### Install Dependencies
|
||||
|
||||
<CodeGroup>
|
||||
```bash pip
|
||||
pip install honcho-ai openai python-dotenv
|
||||
```
|
||||
|
||||
```bash poetry
|
||||
poetry add honcho-ai openai python-dotenv
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Environment Setup
|
||||
|
||||
Create a `.env` file in your project directory:
|
||||
|
||||
```bash
|
||||
OPENAI_API_KEY=your_openai_api_key_here
|
||||
HONCHO_API_KEY=your_honcho_api_key_here
|
||||
```
|
||||
|
||||
### Initialize Honcho
|
||||
|
||||
```python
|
||||
import os
|
||||
from dotenv import load_dotenv
|
||||
from honcho import Honcho
|
||||
import openai
|
||||
|
||||
# Load environment variables
|
||||
load_dotenv()
|
||||
openai.api_key = os.getenv("OPENAI_API_KEY")
|
||||
|
||||
# Initialize Honcho with your app workspace
|
||||
honcho = Honcho(workspace_id="personal-assistant-tutorial")
|
||||
```
|
||||
|
||||
## Part 2: Peer Management
|
||||
|
||||
### Create and Manage Peers
|
||||
|
||||
```python
|
||||
def get_user_peer(username):
|
||||
"""Get or create a peer representing a user"""
|
||||
# Peers are created lazily - no API call until used
|
||||
user_peer = honcho.peer(f"user-{username}")
|
||||
print(f"Created peer for user: {username}")
|
||||
return user_peer
|
||||
|
||||
def get_assistant_peer():
|
||||
"""Get or create the assistant peer"""
|
||||
assistant_peer = honcho.peer("assistant")
|
||||
print("Created assistant peer")
|
||||
return assistant_peer
|
||||
|
||||
# Create peers for our conversation
|
||||
alice = get_user_peer("alice")
|
||||
assistant = get_assistant_peer()
|
||||
|
||||
print(f"User peer ID: {alice.id}")
|
||||
print(f"Assistant peer ID: {assistant.id}")
|
||||
```
|
||||
|
||||
## Part 3: Session Management
|
||||
|
||||
### Create Conversation Sessions
|
||||
|
||||
```python
|
||||
def start_new_session(session_name=None):
|
||||
"""Start a new conversation session"""
|
||||
# Create session with descriptive ID
|
||||
session_id = session_name or f"chat-{int(time.time())}"
|
||||
session = honcho.session(session_id)
|
||||
|
||||
# Add both peers to the session
|
||||
session.add_peers([alice, assistant])
|
||||
|
||||
print(f"Started new session: {session.id}")
|
||||
return session
|
||||
|
||||
import time
|
||||
# Start a session
|
||||
session = start_new_session("daily-checkin")
|
||||
```
|
||||
|
||||
### Message Handling
|
||||
|
||||
```python
|
||||
def add_conversation_turn(session, user_message, assistant_response=None):
|
||||
"""Add a conversation turn to the session"""
|
||||
messages_to_add = [alice.message(user_message)]
|
||||
|
||||
if assistant_response:
|
||||
messages_to_add.append(assistant.message(assistant_response))
|
||||
|
||||
session.add_messages(messages_to_add)
|
||||
print(f"Added {len(messages_to_add)} messages to session")
|
||||
|
||||
# Add user message
|
||||
add_conversation_turn(session, "Hi! I'm working on a Python project today.")
|
||||
```
|
||||
|
||||
## Part 4: LLM Integration with Context
|
||||
|
||||
### Store Information in Peer Representations
|
||||
|
||||
```python
|
||||
def teach_assistant_about_user(assistant_peer, user_peer, facts):
|
||||
"""Add facts about the user to the assistant's knowledge"""
|
||||
# Format facts as messages to build the assistant's representation
|
||||
fact_messages = []
|
||||
for fact in facts:
|
||||
fact_messages.append(assistant_peer.message(f"I learned that {user_peer.id} {fact}"))
|
||||
|
||||
# Add these to the assistant's global knowledge
|
||||
assistant_peer.add_messages(fact_messages)
|
||||
print(f"Taught assistant {len(facts)} facts about {user_peer.id}")
|
||||
|
||||
def extract_facts_from_message(user_message):
|
||||
"""Extract facts about the user from their message using LLM"""
|
||||
prompt = f"""
|
||||
Extract discrete facts about the user from this message:
|
||||
"{user_message}"
|
||||
|
||||
Return only factual statements about the user, no inferences.
|
||||
Format as a simple list of facts starting with action verbs or descriptors.
|
||||
If no facts can be extracted, return an empty list.
|
||||
Example: "is working on a Python project", "likes morning coffee"
|
||||
"""
|
||||
|
||||
response = openai.chat.completions.create(
|
||||
model="gpt-3.5-turbo",
|
||||
messages=[{"role": "user", "content": prompt}],
|
||||
temperature=0.1
|
||||
)
|
||||
|
||||
facts_text = response.choices[0].message.content.strip()
|
||||
|
||||
# Parse facts (simple line-by-line approach)
|
||||
facts = [fact.strip("- ").strip() for fact in facts_text.split('\n') if fact.strip()]
|
||||
return [fact for fact in facts if fact and len(fact) > 5]
|
||||
|
||||
# Extract and store facts
|
||||
user_input = "Hi! I'm working on a Python project today."
|
||||
facts = extract_facts_from_message(user_input)
|
||||
print(f"Extracted facts: {facts}")
|
||||
|
||||
# Teach the assistant these facts
|
||||
if facts:
|
||||
teach_assistant_about_user(assistant, alice, facts)
|
||||
```
|
||||
|
||||
## Part 5: LLM Integration with Context
|
||||
|
||||
### Generate Responses Using Built-in Context
|
||||
|
||||
```python
|
||||
def generate_response_with_context(session, assistant_peer, user_message):
|
||||
"""Generate AI response using Honcho's built-in context management"""
|
||||
|
||||
# Get formatted conversation context - Honcho handles the complexity!
|
||||
context = session.get_context(tokens=2000)
|
||||
messages = context.to_openai(assistant=assistant_peer)
|
||||
|
||||
# Add the current user message
|
||||
messages.append({"role": "user", "content": user_message})
|
||||
|
||||
# Call your LLM with the properly formatted context
|
||||
response = openai.chat.completions.create(
|
||||
model="gpt-3.5-turbo",
|
||||
messages=messages,
|
||||
temperature=0.7
|
||||
)
|
||||
|
||||
return response.choices[0].message.content
|
||||
|
||||
# Generate response using built-in context
|
||||
user_input = "How's my project going?"
|
||||
ai_response = generate_response_with_context(session, assistant, user_input)
|
||||
|
||||
print(f"AI Response: {ai_response}")
|
||||
|
||||
# Add the complete conversation turn to the session
|
||||
add_conversation_turn(session, user_input, ai_response)
|
||||
```
|
||||
|
||||
### Query Peer Knowledge Directly
|
||||
|
||||
```python
|
||||
def get_personalized_insight(assistant_peer, user_peer, query):
|
||||
"""Query what the assistant knows about a specific user"""
|
||||
# Honcho's chat handles context retrieval automatically
|
||||
response = assistant_peer.chat(
|
||||
f"Based on what I know about {user_peer.id}: {query}",
|
||||
target=user_peer
|
||||
)
|
||||
return response
|
||||
|
||||
# Get personalized insights without manual context building
|
||||
insight = get_personalized_insight(
|
||||
assistant,
|
||||
alice,
|
||||
"What programming projects has this user worked on?"
|
||||
)
|
||||
print(f"Programming insights: {insight}")
|
||||
```
|
||||
|
||||
## Part 6: Complete Conversation Loop
|
||||
|
||||
### Put It All Together
|
||||
|
||||
```python
|
||||
def chat_with_assistant(user_peer, assistant_peer, message_text, session=None):
|
||||
"""Complete conversation flow with memory and personalization"""
|
||||
|
||||
# Use existing session or create new one
|
||||
if not session:
|
||||
session = start_new_session()
|
||||
|
||||
# Extract facts from user message and teach assistant
|
||||
facts = extract_facts_from_message(message_text)
|
||||
if facts:
|
||||
teach_assistant_about_user(assistant_peer, user_peer, facts)
|
||||
|
||||
# Generate response using Honcho's built-in context management
|
||||
ai_response = generate_response_with_context(session, assistant_peer, message_text)
|
||||
|
||||
# Add the conversation turn to session
|
||||
add_conversation_turn(session, message_text, ai_response)
|
||||
|
||||
return ai_response
|
||||
|
||||
# Test the complete flow
|
||||
response = chat_with_assistant(
|
||||
alice,
|
||||
assistant,
|
||||
"I finished the authentication module for my Python project!"
|
||||
)
|
||||
print(f"Assistant: {response}")
|
||||
|
||||
# Continue the conversation
|
||||
response2 = chat_with_assistant(
|
||||
alice,
|
||||
assistant,
|
||||
"What should I work on next?",
|
||||
session # Continue in same session
|
||||
)
|
||||
print(f"Assistant: {response2}")
|
||||
```
|
||||
|
||||
## Part 7: Advanced Features
|
||||
|
||||
### Multi-Session Memory
|
||||
|
||||
```python
|
||||
def query_user_history(assistant_peer, user_peer, query):
|
||||
"""Query what the assistant knows about the user across all sessions"""
|
||||
response = assistant_peer.chat(
|
||||
f"Based on everything I know about {user_peer.id}, {query}",
|
||||
target=user_peer
|
||||
)
|
||||
return response
|
||||
|
||||
# Query across all conversations
|
||||
history_query = query_user_history(
|
||||
assistant,
|
||||
alice,
|
||||
"what programming languages and technologies has this user mentioned?"
|
||||
)
|
||||
print(f"User's programming history: {history_query}")
|
||||
```
|
||||
|
||||
### Session-Specific Context
|
||||
|
||||
```python
|
||||
def query_session_specific(assistant_peer, session, query):
|
||||
"""Query what happened in a specific session"""
|
||||
response = assistant_peer.chat(
|
||||
query,
|
||||
session_id=session.id
|
||||
)
|
||||
return response
|
||||
|
||||
# Query about current session
|
||||
session_summary = query_session_specific(
|
||||
assistant,
|
||||
session,
|
||||
"What did we discuss in this conversation?"
|
||||
)
|
||||
print(f"Session summary: {session_summary}")
|
||||
```
|
||||
|
||||
### Working with Multiple Users
|
||||
|
||||
```python
|
||||
def create_group_session(user_peers, assistant_peer):
|
||||
"""Create a session with multiple users and an assistant"""
|
||||
group_session = honcho.session("group-discussion")
|
||||
|
||||
# Add all peers to the session
|
||||
all_peers = user_peers + [assistant_peer]
|
||||
group_session.add_peers(all_peers)
|
||||
|
||||
return group_session
|
||||
|
||||
# Create multiple user peers
|
||||
bob = honcho.peer("user-bob")
|
||||
charlie = honcho.peer("user-charlie")
|
||||
|
||||
# Create group session
|
||||
group_session = create_group_session([alice, bob, charlie], assistant)
|
||||
|
||||
# Add group conversation
|
||||
group_session.add_messages([
|
||||
alice.message("I think we should use Python for the backend"),
|
||||
bob.message("I prefer TypeScript, it's more type-safe"),
|
||||
charlie.message("What about performance considerations?"),
|
||||
assistant.message("Both are good choices. Let me help you compare them based on your requirements.")
|
||||
])
|
||||
|
||||
# Query different perspectives
|
||||
alice_view = assistant.chat(
|
||||
"What does alice think about the technology discussion?",
|
||||
target=alice,
|
||||
session_id=group_session.id
|
||||
)
|
||||
print(f"Alice's perspective: {alice_view}")
|
||||
```
|
||||
|
||||
## Part 8: Advanced Features
|
||||
|
||||
### Direct Knowledge Queries
|
||||
|
||||
```python
|
||||
# Instead of complex manual context building, use peer.chat() directly
|
||||
response = assistant.chat("What programming languages does alice prefer and why?", target=alice)
|
||||
print(f"Alice's language preferences: {response}")
|
||||
|
||||
# Query session-specific knowledge
|
||||
session_insights = assistant.chat(
|
||||
"What was the main topic of discussion in this session?",
|
||||
session_id=session.id
|
||||
)
|
||||
print(f"Session insights: {session_insights}")
|
||||
```
|
||||
|
||||
### Alternative LLM Formats
|
||||
|
||||
```python
|
||||
# Honcho supports multiple LLM formats out of the box
|
||||
def use_anthropic_format(session, assistant_peer, user_message):
|
||||
"""Example using Anthropic's message format"""
|
||||
context = session.get_context(tokens=1500)
|
||||
messages = context.to_anthropic(assistant=assistant_peer)
|
||||
|
||||
# Now you can use these messages with Anthropic's API
|
||||
# anthropic_response = anthropic.messages.create(...)
|
||||
|
||||
return messages
|
||||
|
||||
# Get Anthropic-formatted messages
|
||||
anthropic_messages = use_anthropic_format(session, assistant, "Hello!")
|
||||
print(f"Formatted for Anthropic: {len(anthropic_messages)} messages")
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
Congratulations! You've built a complete personal AI assistant with Honcho that automatically handles memory, context, and LLM integration. Here are some ideas to extend it further:
|
||||
|
||||
1. **Web Interface**: Build a web UI using Flask/FastAPI - the SDK makes it easy to integrate
|
||||
2. **Streaming Responses**: Use `peer.chat(..., stream=True)` for real-time conversations
|
||||
3. **Multi-Modal Support**: Integrate with vision models while leveraging Honcho's memory
|
||||
4. **Advanced Theory-of-Mind**: Explore peer modeling with `observe_others=False` configurations
|
||||
5. **Production Deployment**: Scale with workspaces, metadata, and batch operations
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**"No module named 'honcho'"**
|
||||
- Make sure you installed the package: `pip install honcho-ai`
|
||||
|
||||
**API authentication errors**
|
||||
- Check your `HONCHO_API_KEY` environment variable
|
||||
- Verify your API key is valid
|
||||
|
||||
**Empty context or knowledge queries**
|
||||
- Ensure you've added messages to peers before querying
|
||||
- Check that peers are added to sessions before conversation
|
||||
- Verify session has messages before getting context
|
||||
|
||||
**Rate limiting or timeout issues**
|
||||
- The SDK handles retries automatically
|
||||
- Consider adding delays between large batch operations
|
||||
|
||||
## Resources
|
||||
|
||||
- [SDK Reference](/v2/documentation/reference/sdk)
|
||||
- [API Reference](/v2/api-reference/introduction)
|
||||
- [More Examples](/v2/guides/overview)
|
||||
- [Discord Community](http://discord.gg/plasticlabs)
|
||||
Loading…
Reference in New Issue