README and docs updates (#308)
* docs: initial updates * chore: fix broken link * feat: add honcho-integration SKILL.md --------- Co-authored-by: Vineeth Voruganti <13438633+VVoruganti@users.noreply.github.com> Co-authored-by: Benjamin McCormick <docterformer@protonmail.com>
This commit is contained in:
vintro
GitHub
parent
578ef2c665
commit
669b1886d6
70
README.md
70
README.md
|
|
@ -12,30 +12,23 @@
|
|||
[](https://pypi.org/project/honcho-ai/)
|
||||
[](https://npmjs.org/package/@honcho-ai/sdk)
|
||||
[](https://discord.gg/plasticlabs)
|
||||
[](https://arxiv.org/abs/2310.06983)
|
||||
|
||||
Honcho is an AI-native memory library for building agents with perfect memory and
|
||||
social cognition.
|
||||
Honcho is an open source memory library with a managed service for building stateful
|
||||
agents. Use it with any model, framework, or architecture. It enables agents to build
|
||||
and maintain state about any entity--users, agents, groups, ideas, and more. And because
|
||||
it's a continual learning system, it understands entities that change over time. Using
|
||||
Honcho as your memory system will earn your agents higher retention, more trust, and
|
||||
help you build data moats to out-compete incumbents.
|
||||
|
||||
It provides [state-of-the-art
|
||||
memory](https://blog.plasticlabs.ai/research/Introducing-Neuromancer-XR) and
|
||||
then goes beyond storage by reasoning about the stored data to build
|
||||
rich psychological profiles of each user in your system.
|
||||
|
||||
Use it to build
|
||||
|
||||
- Highly personalized experiences
|
||||
- Agents with social cognition
|
||||
- Agents with rich identity that evolve over time
|
||||
- Multi-agent systems with complex social dynamics
|
||||
> Honcho has defined the Pareto Frontier of Agent Memory. Watch the [video](https://x.com/honchodotdev/status/2002090546521911703?s=20), check out our [evals page](https://evals.honcho.dev/), and read the [blog post](https://blog.plasticlabs.ai/research/Benchmarking-Honcho) for more detail.
|
||||
|
||||
## TL;DR - Getting Started
|
||||
|
||||
With Honcho you can easily setup your application's workflow, save your
|
||||
interaction history, and leverage generated insights to inform the behavior of
|
||||
interaction history, and leverage the reasoning it does to inform the behavior of
|
||||
your agents
|
||||
|
||||
> Typescript examples are available in our [docs](https://docs.honcho.dev)
|
||||
> Typescript examples are available in our [docs](https://docs.honcho.dev).
|
||||
|
||||
1. Install the SDK
|
||||
|
||||
|
|
@ -53,8 +46,8 @@ from honcho import Honcho
|
|||
|
||||
####### Storing Data in Honcho
|
||||
|
||||
# 1. Initialize your Honcho client, by default SDK will use the demo environment and workspace named "default"
|
||||
honcho = Honcho(environment="demo", workspace_id="my-app-testing")
|
||||
# 1. Initialize your Honcho client
|
||||
honcho = Honcho(workspace_id="my-app-testing")
|
||||
|
||||
# 2.. Initialize Peers
|
||||
alice = honcho.peer("alice")
|
||||
|
|
@ -64,20 +57,20 @@ tutor = honcho.peer("tutor")
|
|||
|
||||
session = honcho.session("session-1")
|
||||
|
||||
session.add_messages(
|
||||
session.add_messages([
|
||||
alice.message("Hey there can you help me with my math homework"),
|
||||
tutor.message("Absolutely send me your first problem!"),
|
||||
.
|
||||
.
|
||||
.
|
||||
)
|
||||
])
|
||||
```
|
||||
|
||||
3. Leverage insights from Honcho to inform your agent's behavior
|
||||
3. Leverage reasoning from Honcho to inform your agent's behavior
|
||||
|
||||
```python
|
||||
|
||||
### 1. Use the Dialectic API to ask questions about your users in natural language
|
||||
### 1. Use the chat endpoint to ask questions about your users in natural language
|
||||
response = alice.chat("What learning styles does the user respond to best?")
|
||||
|
||||
### 2. Use Get context to get most recent messages and summaries to continue a conversation
|
||||
|
|
@ -96,7 +89,7 @@ response = client.chat.completions.create(
|
|||
### 3. Search for similar messages
|
||||
results = alice.search("Math Homework")
|
||||
|
||||
### 4. Get a cached working representation of a Peer for the Session
|
||||
### 4. Get a cached representation of a Peer for the Session
|
||||
alice_representation = session.working_rep("alice")
|
||||
|
||||
```
|
||||
|
|
@ -157,13 +150,8 @@ the documentation.
|
|||
|
||||
## Usage
|
||||
|
||||
When you first install the SDKs they will be ready to go, pointing at
|
||||
[https://demo.honcho.dev](https://demo.honcho.dev) which is a demo server of Honcho. This server has no
|
||||
authentication, no SLA, and should only be used for testing and getting familiar
|
||||
with Honcho.
|
||||
|
||||
For a production ready version of Honcho sign up for an account at
|
||||
[https://app.honcho.dev](https://app.honcho.dev) and get started. When you sign up you'll be prompted to
|
||||
Sign up for an account at
|
||||
[https://app.honcho.dev](https://app.honcho.dev) and get started with $100 free credits. When you sign up you'll be prompted to
|
||||
join an organization which will have a dedicated instance of Honcho.
|
||||
|
||||
Provision API keys and change your base url to point to
|
||||
|
|
@ -492,7 +480,7 @@ and Insights.
|
|||
|
||||
### Peer Paradigm
|
||||
|
||||
Honcho uses a peer-based model where both users and agents are represented as "peers". This unified approach enables:
|
||||
Honcho uses an entity-centric model where both users and agents are represented as "[peers](https://blog.plasticlabs.ai/blog/Beyond-the-User-Assistant-Paradigm;-Introducing-Peers)". This unified approach enables:
|
||||
|
||||
- Multi-participant sessions with mixed human and AI agents
|
||||
- Configurable observation settings (which peers observe which others)
|
||||
|
|
@ -501,8 +489,8 @@ Honcho uses a peer-based model where both users and agents are represented as "p
|
|||
|
||||
#### Key Features
|
||||
|
||||
- **Rich Reasoning System**: Multiple implementation methods that extract facts from interactions and build comprehensive models of peer psychology
|
||||
- **Dialectic API**: Provides reasoned informed responses that integrate long-term facts with current context
|
||||
- **Rich Reasoning System**: Multiple implementation methods that extract conclusions from interactions and build comprehensive representations of peers
|
||||
- **Chat API**: Provides reasoning-informed responses that integrate conclusions with current context
|
||||
- **Background Processing**: Asynchronous processing pipeline for expensive operations like representation updates and session summarization
|
||||
- **Multi-Provider Support**: Configurable LLM providers for different use cases
|
||||
|
||||
|
|
@ -510,7 +498,7 @@ Honcho uses a peer-based model where both users and agents are represented as "p
|
|||
|
||||
Honcho contains several different primitives used for storing application and
|
||||
peer data. This data is used for managing conversations, modeling peer
|
||||
psychology, building RAG applications, and more.
|
||||
identity, building RAG applications, and more.
|
||||
|
||||
The philosophy behind Honcho is to provide a platform that is peer-centric and
|
||||
easily scalable from a single user to a million.
|
||||
|
|
@ -544,7 +532,7 @@ much of the mapping here.
|
|||
|
||||
#### Workspaces
|
||||
|
||||
This is the top level construct of Honcho (formerly called Apps). Developers can register different
|
||||
This is the top level construct of Honcho. Developers can register different
|
||||
`Workspaces` for different assistants, agents, AI enabled features, etc. It is a way to
|
||||
isolate data between use cases and provide multi-tenant capabilities.
|
||||
|
||||
|
|
@ -600,8 +588,6 @@ A high level summary of the pipeline is as follows:
|
|||
3. Session-based queue processing ensures proper ordering
|
||||
4. Results are stored internally
|
||||
|
||||
To read more about how this works read our [Research Paper](https://arxiv.org/abs/2310.06983)
|
||||
|
||||
### Retrieving Data & Insights
|
||||
|
||||
Honcho exposes several different ways to retrieve data from the system to best
|
||||
|
|
@ -611,10 +597,10 @@ serve the needs of any given application.
|
|||
|
||||
In long-running conversations with an LLM, the context window can fill up
|
||||
quickly. To address this, Honcho provides a `get_context`
|
||||
endpoint that returns a combination of messages and summaries from a
|
||||
session, up to a provided token limit.
|
||||
endpoint that returns a combination of messages, conclusions, summaries from a
|
||||
session up to a provided token limit.
|
||||
|
||||
Use this to keep sessions going indefinitely.
|
||||
Use this to keep sessions going indefinitely. If you'd like to see this in action, try out [Honcho Chat](https://honcho.chat).
|
||||
|
||||
#### Search
|
||||
|
||||
|
|
@ -627,7 +613,7 @@ the results.
|
|||
#### Dialectic API
|
||||
|
||||
The flagship interface for using these insights is through
|
||||
the [Dialectic Endpoint](https://blog.plasticlabs.ai/blog/Introducing-Honcho's-Dialectic-API).
|
||||
the [Dialectic Endpoint](https://blog.plasticlabs.ai/archive/ARCHIVED;-Introducing-Honcho's-Dialectic-API).
|
||||
|
||||
This is a regular API endpoint (`/peers/{peer_id}/chat`) that takes natural language requests to get data
|
||||
about the `Peer`. This robust design lets us use this single endpoint for all
|
||||
|
|
@ -645,7 +631,7 @@ API include:
|
|||
#### Working Representations
|
||||
|
||||
For low-latency use cases,
|
||||
Honcho provides access to a `get_working_representation` endpoint that
|
||||
Honcho provides access to a `get_representation` endpoint that
|
||||
returns a static document with insights about a `Peer` in the context of a
|
||||
particular session.
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,452 @@
|
|||
---
|
||||
name: honcho-integration
|
||||
description: Integrate Honcho memory and social cognition into existing Python or TypeScript codebases. Use when adding Honcho SDK, setting up peers, configuring sessions, or implementing the dialectic chat endpoint for AI agents.
|
||||
allowed-tools: Read, Glob, Grep, Bash(uv:*), Bash(bun:*), Bash(npm:*), Edit, Write, WebFetch, AskUserQuestion
|
||||
---
|
||||
|
||||
# Honcho Integration Guide
|
||||
|
||||
This skill helps you integrate Honcho into existing Python or TypeScript applications. Honcho provides AI-native memory for stateful agents—it uses custom reasoning models to learn continually.
|
||||
|
||||
## Integration Workflow
|
||||
|
||||
Follow these phases in order:
|
||||
|
||||
### Phase 1: Codebase Exploration
|
||||
|
||||
Before asking the user anything, explore the codebase to understand:
|
||||
|
||||
1. **Language & Framework**: Is this Python or TypeScript? What frameworks are used (FastAPI, Express, Next.js, etc.)?
|
||||
2. **Existing AI/LLM code**: Search for existing LLM integrations (OpenAI, Anthropic, LangChain, etc.)
|
||||
3. **Entity structure**: Identify users, agents, bots, or other entities that interact
|
||||
4. **Session/conversation handling**: How does the app currently manage conversations?
|
||||
5. **Message flow**: Where are messages sent/received? What's the request/response cycle?
|
||||
|
||||
Use Glob and Grep to find:
|
||||
|
||||
- `**/*.py` or `**/*.ts` files with "openai", "anthropic", "llm", "chat", "message"
|
||||
- User/session models or types
|
||||
- API routes handling chat or conversation endpoints
|
||||
|
||||
### Phase 2: Interview (REQUIRED)
|
||||
|
||||
After exploring the codebase, use the **AskUserQuestion** tool to clarify integration requirements. Ask these questions (adapt based on what you learned in Phase 1):
|
||||
|
||||
**Question Set 1 - Entities & Peers**
|
||||
|
||||
Ask about which entities should be Honcho peers:
|
||||
|
||||
- header: "Peers"
|
||||
- question: "Which entities should Honcho track and build representations for?"
|
||||
- options based on what you found (e.g., "End users only", "Users + AI assistant", "Users + multiple AI agents", "All participants including third-party services")
|
||||
- Include a follow-up if they have multiple AI agents: should any AI peers be observed?
|
||||
|
||||
**Question Set 2 - Integration Pattern**
|
||||
|
||||
Ask how they want to use Honcho context:
|
||||
|
||||
- header: "Pattern"
|
||||
- question: "How should your AI access Honcho's user context?"
|
||||
- options:
|
||||
- "Tool call (Recommended)" - "Agent queries Honcho on-demand via function calling"
|
||||
- "Pre-fetch" - "Fetch user context before each LLM call with predefined queries"
|
||||
- "get_context()" - "Include conversation history and representations in prompt"
|
||||
- "Multiple patterns" - "Combine approaches for different use cases"
|
||||
|
||||
**Question Set 3 - Session Structure**
|
||||
|
||||
Ask about conversation structure:
|
||||
|
||||
- header: "Sessions"
|
||||
- question: "How should conversations map to Honcho sessions?"
|
||||
- options based on their app (e.g., "One session per chat thread", "One session per user", "Multiple users per session (group chat)", "Custom session logic")
|
||||
|
||||
**Question Set 4 - Specific Queries (if using pre-fetch pattern)**
|
||||
|
||||
If they chose pre-fetch, ask what context matters:
|
||||
|
||||
- header: "Context"
|
||||
- question: "What user context should be fetched for the AI?"
|
||||
- multiSelect: true
|
||||
- options: "Communication style", "Expertise level", "Goals/priorities", "Preferences", "Recent activity summary", "Custom queries"
|
||||
|
||||
### Phase 3: Implementation
|
||||
|
||||
Based on interview responses, implement the integration:
|
||||
|
||||
1. Install the SDK
|
||||
2. Create Honcho client initialization
|
||||
3. Set up peer creation for identified entities
|
||||
4. Implement the chosen integration pattern(s)
|
||||
5. Add message storage after exchanges
|
||||
6. Update any existing conversation handlers
|
||||
|
||||
### Phase 4: Verification
|
||||
|
||||
- Ensure all message exchanges are stored to Honcho
|
||||
- Verify AI peers have `observe_me=False` (unless user specifically wants AI observation)
|
||||
- Check that the workspace ID is consistent across the codebase
|
||||
- Confirm environment variable for API key is documented
|
||||
|
||||
---
|
||||
|
||||
## Before You Start
|
||||
|
||||
1. **Check the latest SDK versions** at <https://docs.honcho.dev/changelog/introduction>
|
||||
- Python SDK: `honcho-ai`
|
||||
- TypeScript SDK: `@honcho-ai/sdk`
|
||||
|
||||
2. **Get an API key** ask the user to get a Honcho API key from <https://app.honcho.dev> and add it to the environment.
|
||||
|
||||
## Installation
|
||||
|
||||
### Python (use uv)
|
||||
|
||||
```bash
|
||||
uv add honcho-ai
|
||||
```
|
||||
|
||||
### TypeScript (use bun)
|
||||
|
||||
```bash
|
||||
bun add @honcho-ai/sdk
|
||||
```
|
||||
|
||||
## Core Integration Patterns
|
||||
|
||||
### 1. Initialize with a Single Workspace
|
||||
|
||||
Use ONE workspace for your entire application. The workspace name should reflect your app/product.
|
||||
|
||||
**Python:**
|
||||
|
||||
```python
|
||||
from honcho import Honcho
|
||||
import os
|
||||
|
||||
honcho = Honcho(
|
||||
workspace_id="your-app-name",
|
||||
api_key=os.environ["HONCHO_API_KEY"],
|
||||
environment="production"
|
||||
)
|
||||
```
|
||||
|
||||
**TypeScript:**
|
||||
|
||||
```typescript
|
||||
import { Honcho } from '@honcho-ai/sdk';
|
||||
|
||||
const honcho = new Honcho({
|
||||
workspaceId: "your-app-name",
|
||||
apiKey: process.env.HONCHO_API_KEY,
|
||||
environment: "production"
|
||||
});
|
||||
```
|
||||
|
||||
### 2. Create Peers for ALL Entities
|
||||
|
||||
Create peers for **every entity** in your business logic - users AND AI assistants.
|
||||
|
||||
**Python:**
|
||||
|
||||
```python
|
||||
# Human users
|
||||
user = honcho.peer("user-123")
|
||||
|
||||
# AI assistants - set observe_me=False so Honcho doesn't model the AI
|
||||
assistant = honcho.peer("assistant", config={"observe_me": False})
|
||||
support_bot = honcho.peer("support-bot", config={"observe_me": False})
|
||||
```
|
||||
|
||||
**TypeScript:**
|
||||
|
||||
```typescript
|
||||
// Human users
|
||||
const user = await honcho.peer("user-123");
|
||||
|
||||
// AI assistants - set observe_me=False
|
||||
const assistant = await honcho.peer("assistant", { config: { observe_me: false } });
|
||||
const supportBot = await honcho.peer("support-bot", { config: { observe_me: false } });
|
||||
```
|
||||
|
||||
### 3. Multi-Peer Sessions
|
||||
|
||||
Sessions can have multiple participants. Configure observation settings per-peer.
|
||||
|
||||
**Python:**
|
||||
|
||||
```python
|
||||
from honcho import SessionPeerConfig
|
||||
|
||||
session = honcho.session("conversation-123")
|
||||
|
||||
# User is observed (Honcho builds a model of them)
|
||||
user_config = SessionPeerConfig(observe_me=True, observe_others=True)
|
||||
|
||||
# AI is NOT observed (no model built of the AI)
|
||||
ai_config = SessionPeerConfig(observe_me=False, observe_others=True)
|
||||
|
||||
session.add_peers([
|
||||
(user, user_config),
|
||||
(assistant, ai_config)
|
||||
])
|
||||
```
|
||||
|
||||
**TypeScript:**
|
||||
|
||||
```typescript
|
||||
const session = await honcho.session("conversation-123");
|
||||
|
||||
await session.addPeers([
|
||||
[user, { observeMe: true, observeOthers: true }],
|
||||
[assistant, { observeMe: false, observeOthers: true }]
|
||||
]);
|
||||
```
|
||||
|
||||
### 4. Add Messages to Sessions
|
||||
|
||||
**Python:**
|
||||
|
||||
```python
|
||||
session.add_messages([
|
||||
user.message("I'm having trouble with my account"),
|
||||
assistant.message("I'd be happy to help. What seems to be the issue?"),
|
||||
user.message("I can't reset my password")
|
||||
])
|
||||
```
|
||||
|
||||
**TypeScript:**
|
||||
|
||||
```typescript
|
||||
await session.addMessages([
|
||||
user.message("I'm having trouble with my account"),
|
||||
assistant.message("I'd be happy to help. What seems to be the issue?"),
|
||||
user.message("I can't reset my password")
|
||||
]);
|
||||
```
|
||||
|
||||
## Using Honcho for AI Agents
|
||||
|
||||
### Pattern A: Dialectic Chat as a Tool Call (Recommended for Agents)
|
||||
|
||||
Make Honcho's chat endpoint available as a **tool** for your AI agent. This lets the agent query user context on-demand.
|
||||
|
||||
**Python (OpenAI function calling):**
|
||||
|
||||
```python
|
||||
import openai
|
||||
from honcho import Honcho
|
||||
|
||||
honcho = Honcho(workspace_id="my-app", api_key=os.environ["HONCHO_API_KEY"])
|
||||
|
||||
# Define the tool for your agent
|
||||
honcho_tool = {
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": "query_user_context",
|
||||
"description": "Query Honcho to retrieve relevant context about the user based on their history and preferences. Use this when you need to understand the user's background, preferences, past interactions, or goals.",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"query": {
|
||||
"type": "string",
|
||||
"description": "A natural language question about the user, e.g. 'What are this user's main goals?' or 'What communication style does this user prefer?'"
|
||||
}
|
||||
},
|
||||
"required": ["query"]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
def handle_honcho_tool_call(user_id: str, query: str) -> str:
|
||||
"""Execute the Honcho chat tool call."""
|
||||
peer = honcho.peer(user_id)
|
||||
return peer.chat(query)
|
||||
|
||||
# Use in your agent loop
|
||||
def run_agent(user_id: str, user_message: str):
|
||||
messages = [{"role": "user", "content": user_message}]
|
||||
|
||||
response = openai.chat.completions.create(
|
||||
model="gpt-4",
|
||||
messages=messages,
|
||||
tools=[honcho_tool]
|
||||
)
|
||||
|
||||
# Handle tool calls
|
||||
if response.choices[0].message.tool_calls:
|
||||
for tool_call in response.choices[0].message.tool_calls:
|
||||
if tool_call.function.name == "query_user_context":
|
||||
import json
|
||||
args = json.loads(tool_call.function.arguments)
|
||||
result = handle_honcho_tool_call(user_id, args["query"])
|
||||
# Continue conversation with tool result...
|
||||
```
|
||||
|
||||
**TypeScript (OpenAI function calling):**
|
||||
|
||||
```typescript
|
||||
import OpenAI from 'openai';
|
||||
import { Honcho } from '@honcho-ai/sdk';
|
||||
|
||||
const honcho = new Honcho({
|
||||
workspaceId: "my-app",
|
||||
apiKey: process.env.HONCHO_API_KEY
|
||||
});
|
||||
|
||||
const honchoTool: OpenAI.ChatCompletionTool = {
|
||||
type: "function",
|
||||
function: {
|
||||
name: "query_user_context",
|
||||
description: "Query Honcho to retrieve relevant context about the user based on their history and preferences.",
|
||||
parameters: {
|
||||
type: "object",
|
||||
properties: {
|
||||
query: {
|
||||
type: "string",
|
||||
description: "A natural language question about the user"
|
||||
}
|
||||
},
|
||||
required: ["query"]
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
async function handleHonchoToolCall(userId: string, query: string): Promise<string> {
|
||||
const peer = await honcho.peer(userId);
|
||||
return await peer.chat(query);
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern B: Pre-fetch Context with Targeted Queries
|
||||
|
||||
For simpler integrations, fetch user context before the LLM call using pre-defined queries.
|
||||
|
||||
**Python:**
|
||||
|
||||
```python
|
||||
def get_user_context_for_prompt(user_id: str) -> dict:
|
||||
"""Fetch key user attributes via targeted Honcho queries."""
|
||||
peer = honcho.peer(user_id)
|
||||
|
||||
return {
|
||||
"communication_style": peer.chat("What communication style does this user prefer? Be concise."),
|
||||
"expertise_level": peer.chat("What is this user's technical expertise level? Be concise."),
|
||||
"current_goals": peer.chat("What are this user's current goals or priorities? Be concise."),
|
||||
"preferences": peer.chat("What key preferences should I know about this user? Be concise.")
|
||||
}
|
||||
|
||||
def build_system_prompt(user_context: dict) -> str:
|
||||
return f"""You are a helpful assistant. Here's what you know about this user:
|
||||
|
||||
Communication style: {user_context['communication_style']}
|
||||
Expertise level: {user_context['expertise_level']}
|
||||
Current goals: {user_context['current_goals']}
|
||||
Key preferences: {user_context['preferences']}
|
||||
|
||||
Tailor your responses accordingly."""
|
||||
```
|
||||
|
||||
**TypeScript:**
|
||||
|
||||
```typescript
|
||||
async function getUserContextForPrompt(userId: string): Promise<Record<string, string>> {
|
||||
const peer = await honcho.peer(userId);
|
||||
|
||||
const [style, expertise, goals, preferences] = await Promise.all([
|
||||
peer.chat("What communication style does this user prefer? Be concise."),
|
||||
peer.chat("What is this user's technical expertise level? Be concise."),
|
||||
peer.chat("What are this user's current goals or priorities? Be concise."),
|
||||
peer.chat("What key preferences should I know about this user? Be concise.")
|
||||
]);
|
||||
|
||||
return {
|
||||
communicationStyle: style,
|
||||
expertiseLevel: expertise,
|
||||
currentGoals: goals,
|
||||
preferences: preferences
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern C: Get Context for LLM Integration
|
||||
|
||||
Use `get_context()` for conversation history with built-in LLM formatting.
|
||||
|
||||
**Python:**
|
||||
|
||||
```python
|
||||
import openai
|
||||
|
||||
session = honcho.session("conversation-123")
|
||||
user = honcho.peer("user-123")
|
||||
assistant = honcho.peer("assistant", config={"observe_me": False})
|
||||
|
||||
# Get context formatted for your LLM
|
||||
context = session.get_context(
|
||||
tokens=2000,
|
||||
peer_target=user.id, # Include representation of this user
|
||||
summary=True # Include conversation summaries
|
||||
)
|
||||
|
||||
# Convert to OpenAI format
|
||||
messages = context.to_openai(assistant=assistant)
|
||||
|
||||
# Or Anthropic format
|
||||
# messages = context.to_anthropic(assistant=assistant)
|
||||
|
||||
# Add the new user message
|
||||
messages.append({"role": "user", "content": "What should I focus on today?"})
|
||||
|
||||
response = openai.chat.completions.create(
|
||||
model="gpt-4",
|
||||
messages=messages
|
||||
)
|
||||
|
||||
# Store the exchange
|
||||
session.add_messages([
|
||||
user.message("What should I focus on today?"),
|
||||
assistant.message(response.choices[0].message.content)
|
||||
])
|
||||
```
|
||||
|
||||
## Streaming Responses
|
||||
|
||||
**Python:**
|
||||
|
||||
```python
|
||||
response_stream = peer.chat("What do we know about this user?", stream=True)
|
||||
|
||||
for chunk in response_stream.iter_text():
|
||||
print(chunk, end="", flush=True)
|
||||
```
|
||||
|
||||
## Integration Checklist
|
||||
|
||||
When integrating Honcho into an existing codebase:
|
||||
|
||||
- [ ] Install SDK with `uv add honcho-ai` (Python) or `bun add @honcho-ai/sdk` (TypeScript)
|
||||
- [ ] Set up `HONCHO_API_KEY` environment variable
|
||||
- [ ] Initialize Honcho client with a single workspace ID
|
||||
- [ ] Create peers for all entities (users AND AI assistants)
|
||||
- [ ] Set `observe_me=False` for AI peers
|
||||
- [ ] Configure sessions with appropriate peer observation settings
|
||||
- [ ] Choose integration pattern:
|
||||
- [ ] Tool call pattern for agentic systems
|
||||
- [ ] Pre-fetch pattern for simpler integrations
|
||||
- [ ] get_context() for conversation history
|
||||
- [ ] Store messages after each exchange to build user models
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
1. **Multiple workspaces**: Use ONE workspace per application
|
||||
2. **Forgetting AI peers**: Create peers for AI assistants, not just users
|
||||
3. **Observing AI peers**: Set `observe_me=False` for AI peers unless you specifically want Honcho to model your AI's behavior
|
||||
4. **Not storing messages**: Always call `add_messages()` to feed Honcho's reasoning engine
|
||||
5. **Blocking on processing**: Messages are processed asynchronously; use `get_deriver_status()` if you need to wait
|
||||
|
||||
## Resources
|
||||
|
||||
- Documentation: <https://docs.honcho.dev>
|
||||
- Latest SDK versions: <https://docs.honcho.dev/changelog/introduction>
|
||||
- API Reference: <https://docs.honcho.dev/v2/api-reference/introduction>
|
||||
|
|
@ -6,6 +6,10 @@ sidebarTitle: "Overview"
|
|||
|
||||
Honcho is an open source memory library with a managed service for building stateful agents. Use it with any model, framework, or architecture. It enables agents to build and maintain state about any entity--users, agents, groups, ideas, and more. And because it's a continual learning system, it understands entities that change over time. Using Honcho as your memory system will earn your agents higher retention, more trust, and help you build data moats to out-compete incumbents.
|
||||
|
||||
<Note>
|
||||
Honcho has defined the Pareto Frontier of Agent Memory. Watch the [video](https://x.com/honchodotdev/status/2002090546521911703?s=20), check out our [evals page](https://evals.honcho.dev/), and read the [blog post](https://blog.plasticlabs.ai/research/Benchmarking-Honcho) for more detail.
|
||||
</Note>
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Get an API Key" icon="key" href="https://app.honcho.dev">
|
||||
Sign up and start building with Honcho
|
||||
|
|
@ -15,10 +19,6 @@ Honcho is an open source memory library with a managed service for building stat
|
|||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Note>
|
||||
Honcho is a memory system that reasons. Read more on the approach [here](https://blog.plasticlabs.ai/blog/Memory-as-Reasoning).
|
||||
</Note>
|
||||
|
||||
## Why Use Honcho?
|
||||
|
||||
Honcho streamlines the agent building process by offering elegant, flexible primitives for managing context. It also reasons over that context to give developers access to far richer insights only accessible through reasoning.
|
||||
|
|
@ -41,6 +41,10 @@ Break free from this cycle. Honcho is a general solution to context engineering,
|
|||
|
||||
## How Honcho Works
|
||||
|
||||
<Note>
|
||||
Honcho is a memory system that reasons. Read more on the approach [here](https://blog.plasticlabs.ai/blog/Memory-as-Reasoning).
|
||||
</Note>
|
||||
|
||||
Honcho has four storage primitives that work together:
|
||||
|
||||
```mermaid
|
||||
|
|
|
|||
|
|
@ -244,7 +244,7 @@ This is rich personal context for domain-specific agents to do what they want wi
|
|||
- A productivity agent might see the same pattern and say "let's protect your weekend time for the finance app."
|
||||
- A financial advisor agent might see it and ask "what runway would you need to make the leap?"
|
||||
|
||||
Honcho acts almost like a detective--it reasons about new and existing evidence in order to form conclusions that can be used to make a *case*. These conclusions wait to be composed dynamically based on how you, the ~~judge~~ developer, query it. This approach is what drives our [pareto-frontier](TODO: link to evals page here) performance on memory benchmarks, and our custom models allow us to optimize speed and cost.
|
||||
Honcho acts almost like a detective--it reasons about new and existing evidence in order to form conclusions that can be used to make a *case*. These conclusions wait to be composed dynamically based on how you, the ~~judge~~ developer, query it. This approach is what drives our [pareto-frontier](https://evals.honcho.dev) performance on memory benchmarks, and our custom models allow us to optimize speed and cost.
|
||||
|
||||
|
||||
## Next Steps
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: "AI-Powered Honcho Setup"
|
||||
icon: "wand-magic-sparkles"
|
||||
description: "Universal starter prompt for building with Honcho"
|
||||
description: "Universal starter prompt and Claude Code skill for building with Honcho"
|
||||
sidebarTitle: 'Vibecoding Setup'
|
||||
---
|
||||
|
||||
|
|
@ -12,7 +12,42 @@ We follow the llms.txt standard. There are both an llms.txt and llms-full.txt av
|
|||
- [llms.txt](/llms.txt)
|
||||
- [llms-full.txt](/llms-full.txt)
|
||||
|
||||
We also provide a starter prompt to paste into a coding assistant to quickly get started building with Honcho.
|
||||
---
|
||||
|
||||
## Claude Code Skill
|
||||
|
||||
If you're using [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), you can install the Honcho integration skill for a guided, interactive setup experience. The skill will explore your codebase, ask targeted questions about your integration needs, and implement Honcho step by step.
|
||||
|
||||
### Installation
|
||||
|
||||
<CodeGroup>
|
||||
```bash Global Installation (all projects)
|
||||
# Add to your global skills directory
|
||||
curl -o ~/.claude/skills/honcho-integration.md https://raw.githubusercontent.com/plastic-labs/honcho/main/docs/SKILL.md
|
||||
```
|
||||
|
||||
```bash Project-specific Installation
|
||||
# Add to your project's .claude directory
|
||||
mkdir -p .claude/skills
|
||||
curl -o .claude/skills/honcho-integration.md https://raw.githubusercontent.com/plastic-labs/honcho/main/docs/SKILL.md
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
### Usage
|
||||
|
||||
Once installed, invoke the skill in Claude Code:
|
||||
|
||||
```
|
||||
/honcho-integration
|
||||
```
|
||||
|
||||
The skill will:
|
||||
1. **Explore your codebase** to understand your language, framework, and existing AI/LLM integrations
|
||||
2. **Interview you** about which entities should be peers, your preferred integration pattern, and session structure
|
||||
3. **Implement the integration** based on your answers
|
||||
4. **Verify the setup** to ensure everything is configured correctly
|
||||
|
||||
---
|
||||
|
||||
## Universal Starter Prompt
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue