Step Function Improvement on Docs (#241)

* feat: Release PR for v2.4.0

* chore: initial re-organization pass

* chore: in progress edits

* fix: WIP Restructure

* fix: docs introduction section

* fix: Populates new features pages

* fix: Code Rabbit grammatical catches

* chore: make system diagram visible by default
This commit is contained in:
Vineeth Voruganti 2025-11-05 17:40:53 -05:00 committed by GitHub
parent a25be3c136
commit 822059b81a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
26 changed files with 566 additions and 276 deletions

View File

@ -30,7 +30,6 @@ This guide helps you understand which versions of Honcho's API are compatible wi
</CardGroup>
## Version Compatibility Table
| Honcho API Version | TypeScript SDK | Python SDK |

View File

@ -3,27 +3,20 @@
"theme": "mint",
"name": "Honcho",
"colors": {
"primary": "#86BCF2",
"primary": "#66AAFF",
"dark": "#151E27",
"light": "#B5D9FD"
"light": "#86BCF2"
},
"favicon": "/favicon.svg",
"contextual": {
"options": [
"copy",
"view",
"chatgpt",
"claude"
]
"options": ["copy", "view", "chatgpt", "claude"]
},
"navigation": {
"versions": [
{
"version": "v2.4.2",
"api": {
"openapi": [
"openapi.documented.yml"
]
"openapi": ["openapi.documented.yml"]
},
"tabs": [
{
@ -41,10 +34,19 @@
"group": "Core Concepts",
"pages": [
"v2/documentation/core-concepts/architecture",
"v2/documentation/core-concepts/glossary",
"v2/documentation/core-concepts/features",
"v2/documentation/core-concepts/features/storing-data",
"v2/documentation/core-concepts/features/dialectic-endpoint",
"v2/documentation/core-concepts/features/get-context",
"v2/documentation/core-concepts/features/search",
"v2/documentation/core-concepts/features/working-rep",
"v2/documentation/core-concepts/features/streaming-response",
"v2/documentation/core-concepts/features/using-filters",
"v2/documentation/core-concepts/features/file-uploads",
"v2/documentation/core-concepts/features/queue-status",
"v2/documentation/core-concepts/features/local-vs-global",
"v2/documentation/core-concepts/configuration",
"v2/documentation/core-concepts/summarizer"
"v2/documentation/core-concepts/summarizer",
"v2/documentation/core-concepts/glossary"
]
},
{
@ -61,54 +63,21 @@
"groups": [
{
"group": "Getting Started",
"pages": [
"v2/guides/overview",
"v2/guides/mcp"
]
"pages": ["v2/guides/overview", "v2/guides/mcp"]
},
{
"group": "Application Interfaces",
"pages": [
"v2/guides/discord",
"v2/guides/telegram"
]
},
{
"group": "Design Patterns",
"pages": [
"v2/guides/dialectic-endpoint",
"v2/guides/get-context",
"v2/guides/search",
"v2/guides/working-rep",
"v2/guides/streaming-response",
"v2/guides/using-filters",
"v2/guides/file-uploads"
]
}
]
},
{
"tab": "Contributing",
"groups": [
{
"group": "Contributing",
"pages": [
"v2/contributing/guidelines",
"v2/contributing/self-hosting",
"v2/contributing/configuration",
"v2/contributing/license"
]
"pages": ["v2/guides/discord", "v2/guides/telegram"]
}
]
},
{
"tab": "API Reference",
"groups": [
{
"group": "API Documentation",
"pages": [
"v2/api-reference/introduction"
]
"pages": ["v2/api-reference/introduction"]
},
{
"group": "workspaces",
@ -192,15 +161,27 @@
]
}
]
},
{
"tab": "Contributing",
"groups": [
{
"group": "Contributing",
"pages": [
"v2/contributing/guidelines",
"v2/contributing/self-hosting",
"v2/contributing/configuration",
"v2/contributing/license"
]
}
]
}
]
},
{
"version": "v1.1.0",
"api": {
"openapi": [
"openapi.json"
]
"openapi": ["openapi.json"]
},
"tabs": [
{
@ -230,23 +211,15 @@
"groups": [
{
"group": "Getting Started",
"pages": [
"v1/guides/overview",
"v1/guides/streaming-response"
]
"pages": ["v1/guides/overview", "v1/guides/streaming-response"]
},
{
"group": "Application Interfaces",
"pages": [
"v1/guides/discord",
"v1/guides/honcho-mcp"
]
"pages": ["v1/guides/discord", "v1/guides/honcho-mcp"]
},
{
"group": "Personal Memory",
"pages": [
"v1/guides/dialectic-endpoint"
]
"pages": ["v1/guides/dialectic-endpoint"]
}
]
},
@ -255,9 +228,7 @@
"groups": [
{
"group": "API Documentation",
"pages": [
"v1/api-reference/introduction"
]
"pages": ["v1/api-reference/introduction"]
},
{
"group": "apps",
@ -305,9 +276,7 @@
},
{
"group": "keys",
"pages": [
"v1/api-reference/endpoint/keys/create-key"
]
"pages": ["v1/api-reference/endpoint/keys/create-key"]
},
{
"group": "metamessages",
@ -360,9 +329,9 @@
"global": {
"anchors": [
{
"anchor": "Managed Platform",
"anchor": "Dashboard",
"href": "https://app.honcho.dev",
"icon": "book-open-cover"
"icon": "table-columns"
},
{
"anchor": "Community",

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 38 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 414 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 38 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 418 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 37 KiB

View File

@ -7,17 +7,15 @@ 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 3 main components that work together to manage agent identity and context.
Honcho has 2 main components that work together to manage agent identity and context.
- **The Storage API**: The Memory layer for storing interaction history for your agents
- **The Deriver**: The background processing layer that builds representations of users and agents
- **The Dialectic API**: The natural language API for chatting with representations
- **The Memory Layer**: The Memory layer for storing interaction history for your agents
- **The Reasoning Layer**: The background processing layer that builds representations of users and agents
Below we'll deep dive into these different areas, discussing the data
primitives, the flow of data through the system, artifacts Honcho produces, and
how to use them.
## Data Model
Honcho has a hierarchical data model centered around the entities below.
@ -37,9 +35,9 @@ Honcho has a hierarchical data model centered around the entities below.
style SM fill:#e8f5e9,stroke:#2e7d32,color:#000
```
There are `Workspaces` at the top that contain `Peers` and `Sessions`. A `Peer`
can be part of many `Sessions` and a `Session` can have many `Peers`. `Sessions`
hold messages that are sent by `Peers`.
A `Workspaces` 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`.
### <Icon icon="building" /> Workspaces
@ -126,19 +124,38 @@ with a single peer and structure the data as messages.
- File uploads (PDFs, text files, JSON documents)
## Deriver
## Reasoning Layer
At the core of developing representations of Peers, we have the Deriver. The
Deriver refers to a set of processes in Honcho that enqueue new messages sent
by peers and reasons over them to extract facts, insights, and context.
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 to generate
context-aware responses that can correctly reference both concrete facts
extracted from messages and social insights deduced from facts, tone, and
opinion.
Facts derived here are used in the Dialectic chat endpoint, 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.
@ -149,7 +166,7 @@ There are two types of tasks that the deriver currently does:
- **Representation Tasks**: Generate/update peer representations
- **Summary Tasks**: Generate conversation summaries
### Peer Representations
### 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

View File

@ -1,5 +1,5 @@
---
title: 'Configuration'
title: 'Configure Reasoning'
description: 'Customizing how Honcho handles peers and sessions'
icon: 'wrench'
---

View File

@ -1,44 +0,0 @@
---
title: 'Features'
description: 'Key features and capabilities of Honcho'
icon: 'star'
---
This page is a quick overview of the features within Honcho. In-depth
guides are available for each feature in the [Spellbooks - Design Patterns](../../guides/overview#design-patterns) section.
### Local vs Global Representation
Peers in Honcho are abstract entities that can represent humans, agents, or NPCs. Honcho has a two-layer approach to forming representations of Peers.
- **Global Representation**: Representation owned by a Peer that is constructed from everything the Peer has sent within Honcho.
- **Local Representation**: The representation that a Peer forms of other Peers, based on the messages those other Peers have sent (as observed by the Peer forming the representation).
- At the Session level, you can configure which Peers are able to observe messages from other Peers in that Session. This determines which Peers form representations of others within the Session.
### Queue Status
To help developers understand when a Peer's representation is fully up to date, Honcho exposes the ability to poll the status of Peer-centric queues that construct representations.
- If no Session is specified, the queue status reflects pending work for the Peer's global representation.
- If a Session is specified, the queue status reflects pending work for the Peer's working representation in that Session.
### Search
Honcho implements a powerful search endpoint that allows you to search for messages across a workspace, session, or peer with complex [filters](/v2/guides/using-filters).
The search process combines full-text and semantic search using reciprocal rank fusion. By default, all messages ingested into Honcho have embeddings generated and stored in the database, enabling semantic search -- if this feature is disabled, the search process will only use full-text search.
Results are returned in the form of a list of Message objects, and you may choose how many results to return. The default is 10 results, with a maximum of 100.
In the SDK, search is available on `Workspace`, `Session`, and `Peer` objects, and an optional `filters` parameter may be used to apply a narrower search scope such as a time range or developer-defined metadata attached to messages.
Note that results are not ordered by recency, only relevance. Results can be sorted by timestamp or a filter on the `created_at` field can limit results to recent messages.
[Look here for examples of how to use search in the SDK](/v2/guides/search).
### Scoped API Keys
Builders can create scoped API keys to control access to different resources within Honcho.
- **Workspace-Level Keys**: Access to everything scoped to a Workspace.
- **Peer-Level Keys**: Access to everything scoped to a Peer.
- **Session-Level Keys**: Access to everything scoped to a Session.
### Get Context
Honcho provides a powerful context retrieval feature that delivers formatted conversation context from sessions, making it easy to integrate with LLMs like OpenAI, Anthropic, and others.
- By default, the context includes a blend of summary and messages which covers the entire history of the session.
- Summaries are generated automatically at intervals, and recent messages are included based on your specified token budget for the context.
- You can set any token limit, and if you prefer, you can disable summaries so that the context consists entirely of the most recent messages up to your chosen limit.

View File

@ -1,5 +1,5 @@
---
title: 'Working with Session Context'
title: 'Get Context'
description: 'Learn how to use get_context() to retrieve and format conversation context for LLM integration'
icon: 'messages'
---

View File

@ -0,0 +1,68 @@
---
title: Local vs Global Representations
description: Model directional relationships between Peers in Honcho
icon: location-pin
---
One of the unique affordances of Honcho is that it allows developers to model
directional relationships between Peers. What I mean by this is you can model
how one `Peer` thinks about another `Peer`.
There are many use cases where you don't want every agent or human to know
everything about another user such as games or multi-agent workflows. To
illustrate this, the following examples shows 2 conversations.
Conversation #1 (With Bob and Alice)
```
Alice: I had a great breakfast today.
Bob: What did you eat?
Alice: I had pancakes and eggs and bacon
```
Conversation #2 (With Alice and Charlie)
```
Alice: I actually didn't eat any breakfast today.
Charlie: Oh that's too bad.
Alice: But I lied to Bob and told him I did, so back me up if you see them.
```
Alice told Bob a lie in this conversation. If we stored both of these
conversations in Honcho with Alice, Bob, and Charlie as `Peers` and let them
use Honcho to get insights on each other then Bob would immediately know this
deception. For example:
<CodeGroup>
```python Python
# Bob could run
alice.chat("What did Alice eat today?")
# Response: Alice did not eat anything today
```
</CodeGroup>
This is a problem. Bob shouldn't be able to know everything about Alice in this
situation. So to support these situations we support what we call **Local
Representations**.
By default insights generated for a `Peer` are scoped globally. This means every
message sent by that `Peer` in any conversation updates the same representation
of that `Peer`. However, we can enable **Local Representations** so Bob can
form a representation Alice based only on what they observe Alice do.
This feature is illustrated in the graphic below:
<img src="/images/local-vs-global-reps.png" alt="Peer Representations" />
We can enable local representation for a `Peer` by setting `observe_others=True`.
This is shown in the [Configure
Reasoning](/v2/documentation/core-concepts/configuration) page.
Now if we used Bob's local representation of Alice then Bob would only get
insights on what they've seen Alice say to them.
```python
bob.chat(target="alice", query="What did Alice eat today?")
# Response: Alice ate pancakes, eggs, and bacon
```
<Note>
Local Representations are turned off by default
</Note>

View File

@ -0,0 +1,132 @@
---
title: Queue Status
description: Learn how to check the status of the Deriver
icon: lines-leaning
---
Whenever `Messages` are stored in Honcho, a background process called the
[Deriver](/docs/v2/documentation/core-concepts/architecture#reasoning-layer) is
triggered to reason about the conversation and generate insights.
The Deriver is an asynchronous process and, depending on load may not immediately
generated insights for the latest message you've sent. To help with this, Honcho
provides several utilities to check the status of the Deriver.
<CodeGroup>
```python Python
from honcho import Honcho
honcho = Honcho()
status = honcho.get_deriver_status()
honcho.poll_deriver_status()
```
```typescript typescript
import { Honcho } from '@honcho-ai/sdk';
const honcho = new Honcho({});
const status = await honcho.getDeriverStatus();
await honcho.pollDeriverStatus();
```
</CodeGroup>
Output types
<CodeGroup>
```python Python
class DeriverStatus(BaseModel):
completed_work_units: int
"""Completed work units"""
in_progress_work_units: int
"""Work units currently being processed"""
pending_work_units: int
"""Work units waiting to be processed"""
total_work_units: int
"""Total work units"""
sessions: Optional[Dict[str, Sessions]] = None
"""Per-session status when not filtered by session"""
```
```typescript TypeScript
Promise<{
totalWorkUnits: number
completedWorkUnits: number
inProgressWorkUnits: number
pendingWorkUnits: number
sessions?: Record<string, DeriverStatus.Sessions>
}>
```
</CodeGroup>
Whenever a `Message` is sent it will generate several tasks. These could
be tasks such as generating insights, cleaning up a representation, summarizing
a conversation etc. These tasks are defined based on who is sending the
message, what `Session` the message is in, and potentially who is observing the
message. We call the combination of these parameters a `work_unit`
This has a few different implications.
- tasks within the same work_unit are processed sequentially, but multiple
work_units will be processed in parallel
- If local representations are turned in a Session then a `Message` will
generate an additional work unit for every `Peer` that has `observe_others=True`
The `get_deriver_status` and `poll_deriver_status` methods can take additional
parameters to scope the status to a specific work unit
<CodeGroup>
```python Python
def get_deriver_status(
self,
observer_id: str | None = None,
sender_id: str | None = None,
session_id: str | None = None,
) -> DeriverStatus:
```
```typescript TypeScript
export const DeriverStatusOptionsSchema = z.object({
observerId: z.string().optional(),
senderId: z.string().optional(),
sessionId: z.string().optional(),
timeoutMs: z
.number()
.positive('Timeout must be a positive number')
.optional(),
})
```
</CodeGroup>
Additionally, there are deriver status and polling deriver status methods
available on the `Session` objects in each of the SDKs.
Below are the function signatures for the session level deriver status method
<CodeGroup>
```python python
@validate_call
def get_deriver_status(
self,
observer_id: str | None = None,
sender_id: str | None = None,
) -> DeriverStatus:
```
```typescript TypeScript
async getDeriverStatus(
options?: Omit<DeriverStatusOptions, 'sessionId'>
): Promise<{
totalWorkUnits: number
completedWorkUnits: number
inProgressWorkUnits: number
pendingWorkUnits: number
sessions?: Record<string, DeriverStatus.Sessions>
}>
```
</CodeGroup>

View File

@ -0,0 +1,61 @@
---
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

View File

@ -5,108 +5,102 @@ icon: "brain"
sidebarTitle: "Overview"
---
When building agents developers often run into the same walls:
Honcho is an AI-native memory library for building agents with
[state-of-the-art](https://blog.plasticlabs.ai/research/Introducing-Neuromancer-XR)
long-term memory.
> "My agent forgets everything between chats"
Agents using Honcho have perfect recall with a wide variety of tools to traverse
their history and get the exact context they need when they need it.
You need memory: session management, message storage, context handling. It's table stakes, but surprisingly complex to get right.
It then goes beyond basic memory by reasoning about the stored history
to expand the latent information available to your agent. Agents using Honcho
will understand who they are, who they are interacting with, what happened, and
when it happened — all without you having to think about it.
> "My agent treats everyone exactly the same"
Use it to build
You need personalization: user modeling, preference learning, behavioral adaptation. Now you're building a [social cognition](../core-concepts/glossary#social-cognition) engine.
- Highly personalized experiences
- Agents with social cognition
- Agents with rich identity that evolve over time
- Multi-agent systems with complex social dynamics
> "I'm writing infrastructure instead of features"
You need Honcho
<img src="/images/agent_hierarchy.png" alt="Honcho's Hiearchy of Agents" />
Honcho delivers production-ready memory infrastructure from day one. Store
conversations, manage sessions, get perfectly formatted context for any LLM.
But here's the magic: while your agents are chatting, Honcho is learning. It
builds Theory of Mind models automatically, transforming raw conversations into
rich psychological understanding.
```python
# Start simple - just add messages
# Start simple by just adding messages
session.add_messages([alice.message("I learn best with examples")])
# Get powerful - query user psychology
# Honcho will automatically reason about the message to generate insights about Alice
# Get insights by chatting with the agent
insight = peer.chat("How should I explain this concept?")
# > "This user learns best through concrete examples..."
```
Your agents evolve from goldfish to counselor, on the same infrastructure. That's Honcho.
Designed for developers and agents alike:
- **Natural Language Queries**: Chat with Honcho in natural language via the [Dialectic API](../core-concepts/architecture#dialectic-api) and let agents backchannel
- **Automatic Context Management**: Smart summarization that respects token limits
- **Native multi-agent support**: Break out of User/Assistant Paradigms and build complex multi-agent systems
- **Natural Language Queries**: Chat with Honcho in natural language via the [Dialectic API](../core-concepts/architecture#dialectic-api) to get insights about your users and agents
- **Automatic Context Management**: Smart conversation summaries to have infinite chats
- **Native multi-agent support**: Sessions can natively have as many participants as you need
- **Agent-first interfaces**: MCP connections and APIs designed for agents to consume and use as tools
- **Provider Agnostic**: Works with any LLM or Agent Framework
## How It Works
### Storage
<Accordion title="High Level Diagram" defaultOpen="true">
<Frame>
<img src="/images/overview/honcho-overview.svg" alt="High Level Honcho Diagram" />
</Frame>
</Accordion>
Developers use Honcho to store information about their users and application via
two integrated layers:
At a high level Honcho works very simply:
<img src="/images/basic_honcho_flowchart.png" alt="Basic Honcho Flowchart" />
1. Store messages sent by users and agents in Honcho
2. Honcho reasons about the messages to generate insights about each entity in
the system
3. At runtime your agents can leverage insights from Honcho to get the exact
context they need
**Memory Layer**: Captures all user interactions - messages, preferences, and
behavioral patterns - in a peer-centric data model that scales from individual
conversations to complex multi-agent scenarios. This also queues up messages for
the reasoning layer to process.
There are several API endpoints to leverage the memory & insights in Honcho.
**Reasoning Layer**: Continuously analyzes stored interactions to build
psychological profiles using [theory of mind](../core-concepts/glossary#theory-of-mind)
inference, extracting patterns about communication style, decision-making
preferences, and mental models.
### Get Context
### Retrieval
This is the easiest way to leverage Honcho. simply call get context and get the
most relevant information for your conversation. This endpoint is highly
customizable so you can specify parameters such as:
Once data is stored and generated within Honcho, the API exposes several
different ways to retrieve and use those insights.
- A number of tokens you want
- An option to include summaries of the conversation
- An option to get a profile of a specific user (Peer Card & Representation)
**[Dialectic API](/v2/guides/dialectic-endpoint)**: This is the
flagship endpoint that allows developers to send natural language queries to
Honcho to chat with the representation of each user in your system to get
dynamic, in-context actionable insights.
### Search
Example Queries
This endpoint lets you search across Honcho for relevant messages using a
hybrid search strategy that combines full-text and semantic search.
You can optionally scope the endpoint to a specific workspace, peer, or session.
### Working Representation
This endpoint gives you a snapshot of a user or what we call a
**Representation**. Essentially, a list of explicit and deductive facts about
the user that are relevant to the current conversation.
Plug this into your prompt to get a quick overview of the user.
### Dialectic API
This endpoint lets you chat with Honcho about any entity in your system. Honcho
will leverage what it has remembered and learned about the entity to provide in-context actionable insights.
This is especially helpful when you want your agent to back-channel with Honcho to
change its behavior at runtime.
Example Queries:
- "What's the best way to explain technical concepts to this user?"
- "Is this user more task-oriented or relationship-oriented?"
- "What time of day is this user most engaged?"
- "How does this user prefer to receive feedback?"
- "What are this user's core values based on our conversations?"
**[Get Context](/v2/guides/get-context)**: This endpoint abstracts context window
constraints and continuously retrieves the most relevant and recent data from a
conversation. Provide a token budget and Honcho will return a combination of
summaries and messages that provide session context. Use this for creating
long-running conversations. We crafted our summaries to provide the most
[coverage of a session possible](../core-concepts/summarizer).
**[Search](/v2/guides/search)**: This endpoint allows you to search across Honcho
for relevant messages either at the workspace, peer, or session level. This
endpoint uses a hybrid search strategy that combines text search and cosine
similarity.
**[Working Representations](/v2/guides/working-rep)**: Get a cached, snapshot
of a user in the context of a session. Instead of waiting for an LLM to
synthesize an in-context response via the Dialectic endpoint, use this to get
recent insights you can plug into your context window.
## Ideal For
**Personalized AI assistants** that need to understand individual psychology, not just remember conversations.
**Customer-facing agents** that must adapt their approach based on user communication preferences and emotional context.
**Multi-agent systems** where AI needs to understand human collaborators' working styles and decision-making patterns.
**NPCs** where you want autonomous agents with a rich and deep personality that isn't the average sycophantic llm
## Getting Started
@ -115,7 +109,7 @@ Ready to integrate Honcho into your application?
<CardGroup cols={2}> <Card title="Quickstart Guide" icon="rocket"
href="/v2/documentation/introduction/quickstart"> Get up and running with
Honcho in minutes </Card> <Card title="Core Concepts" icon="brain"
href="/v2/documentation/core-concepts/glossary"> Understand Honcho's
href="/v2/documentation/core-concepts/architecture"> Understand Honcho's
fundamental concepts </Card> </CardGroup>
## Community & Support

View File

@ -62,7 +62,7 @@ The Honcho client is the main entry point for interacting with Honcho's API. By
from honcho import Honcho
# Initialize client (uses demo environment and default workspace)
client = Honcho()
honcho = Honcho()
```
@ -70,7 +70,7 @@ client = Honcho()
import { Honcho } from '@honcho-ai/sdk';
// Initialize client (uses demo environment and default workspace)
const client = new Honcho({});
const honcho = new Honcho({});
```
</CodeGroup>
@ -83,7 +83,7 @@ import os
from honcho import Honcho
# Production environment with API key
client = Honcho(
honcho = Honcho(
api_key=os.environ["HONCHO_API_KEY"],
environment="production",
# Create a workspace, otherwise set to "default"
@ -95,7 +95,7 @@ client = Honcho(
import { Honcho } from '@honcho-ai/sdk';
// Production environment with API key
const client = new Honcho({
const honcho = new Honcho({
apiKey: process.env.HONCHO_API_KEY!,
environment: "production",
// Create a workspace, otherwise set to "default"
@ -110,13 +110,13 @@ Peers represent individual users, AI agents, or any conversational entity in you
<CodeGroup>
```python Python
alice = client.peer("alice")
bob = client.peer("bob")
alice = honcho.peer("alice")
bob = honcho.peer("bob")
```
```typescript TypeScript
const alice = await client.peer("alice")
const bob = await client.peer("bob")
const alice = await honcho.peer("alice")
const bob = await honcho.peer("bob")
```
</CodeGroup>
@ -126,12 +126,12 @@ Sessions are independent conversations that can include multiple peers:
<CodeGroup>
```python Python
session = client.session("session_1")
session = honcho.session("session_1")
session.add_peers([alice, bob])
```
```typescript TypeScript
const session = await client.session("session_1")
const session = await honcho.session("session_1")
await session.addPeers([alice, bob])
```
</CodeGroup>
@ -171,7 +171,7 @@ Now ask Honcho what it's learned - this is where the magic happens:
<CodeGroup>
```python Python
# Ask what Bob is like
response = alice.chat("Tell me about Bob's interests and habits")
response = bob.chat("Tell me about Bob's interests and habits")
print(response)
# Returns rich context like:
@ -182,36 +182,128 @@ print(response)
```
```typescript TypeScript
(async () => {
// Ask what Bob is like
const response = await alice.chat("Tell me about Bob's interests and habits");
console.log(response);
bob.chat("Tell me about Bob's interests and habits").then((response) => {
console.log(response);
// Returns rich context like:
// "Bob is health-conscious and has been working on getting back in shape.
// He regularly goes to the gym, particularly in the evenings, and finds
// exercise helps him relax. He's encouraging about fitness and willing
// to share advice about workout routines."
})
```
</CodeGroup>
// Returns rich context like:
// "Bob is health-conscious and has been working on getting back in shape.
// He regularly goes to the gym, particularly in the evenings, and finds
// exercise helps him relax. He's encouraging about fitness and willing
// to share advice about workout routines."
})();
## 7. Putting it all together
<CodeGroup>
```python Python
import os
from honcho import Honcho
# Create your client
honcho = Honcho(
api_key=os.environ["HONCHO_API_KEY"],
environment="production",
# Create a workspace, otherwise set to "default"
# workspaceId="your-workspace-id"
)
# Get your Peers
alice = honcho.peer("alice")
bob = honcho.peer("bob")
# Make a Session and add your Peers
session = honcho.session("session_1")
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 insights about your Peers
response = bob.chat("Tell me about Bob's interests and habits")
print(response)
# Returns rich context like:
# "Bob is health-conscious and has been working on getting back in shape.
# He regularly goes to the gym, particularly in the evenings, and finds
# exercise helps him relax. He's encouraging about fitness and willing
# to share advice about workout routines."
```
```typescript TypeScript
import { Honcho } from '@honcho-ai/sdk';
// Create your client
const honcho = new Honcho({
apiKey: process.env.HONCHO_API_KEY!,
environment: "production",
// Create a workspace, otherwise set to "default"
// workspace: "your-workspace-id"
});
// Get your Peers
const alice = await honcho.peer("alice")
const bob = await honcho.peer("bob")
// Make a Session and add your peers
const session = await honcho.session("session_1")
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 insights about your peers
bob.chat("Tell me about Bob's interests and habits").then((response) => {
console.log(response);
// Returns rich context like:
// "Bob is health-conscious and has been working on getting back in shape.
// He regularly goes to the gym, particularly in the evenings, and finds
// exercise helps him relax. He's encouraging about fitness and willing
// to share advice about workout routines."
})
```
</CodeGroup>
## What Just Happened?
Honcho automatically built rich psychological profiles from just a few messages:
You just got through building a simple conversation between two people, Alice
and Bob. We:
- **Theory of Mind Processing**: Understanding personality, preferences, and patterns
- **Ambient Learning**: No surveys or explicit training - just natural conversation
- **Rich Context**: Far more detailed than simple conversation history
1. Set up our connection to Honcho.
2. Setup who the participants of our conversation are, these are called `Peers`.
3. Made a `Session` and added our `Peers` to it.
4. Sent messages from our `Peers`
5. Chat with Honcho to get insights about one of the `Peers` in the conversation
The response isn't just retrieving stored text - it's synthesizing insights about Bob's personality, habits, and communication style.
As soon as you save a message in Honcho, it will start to reason about it to
pull out insights and develop a profile of the user. This is the default
behavior and can be toggled off via [the configuration](/v2/documentation/core-concepts/configuration).
## Next Steps
This covers the core concepts: **peers**, **sessions**, **messages**, and **dialectic queries**.
- For production use, [sign up for the managed platform](https://app.honcho.dev) or get an [overview here](../reference/platform).
- For detailed API reference, check out our [SDK documentation](../reference/sdk).
- For more examples, explore our [guides](../guides/overview).
---
<CardGroup cols={3}>
<Card title="Architecture" icon="rocket"
href="/v2/documentation/core-concepts/architecture">
Learn about the data primitives in Honcho and how they work together
</Card>
<Card title="Start Building" icon="brain" href="https://app.honcho.dev">
Sign up for Managed Honcho and get started building agents now.
</Card>
<Card title="Guides" icon="book" href="/v2/guides/overview">
Check out spellbooks to see different examples apps built with Honcho
</Card>
</CardGroup>

View File

@ -5,7 +5,17 @@ description: "Universal starter prompt for building with Honcho"
sidebarTitle: 'Vibecoding Setup'
---
Copy this prompt into Cursor, Claude, or any AI coding assistant to start building with Honcho.
These docs are designed to be easily consumable for LLMs. Each page has a button
the lets you copy the page as Markdown or paste directly into ChatGPT or Claude.
Additionally, we follow the llms.txt standard. There are both an llms.txt and
llms-full.txt available.
- [llms.txt](/llms.txt)
- [llms-full.txt](/llms-full.txt)
Additionally, we provide a starter prompt to paste into a coding assistant to
quickly get started building with Honcho.
## 🚀 Universal Starter Prompt

View File

@ -1,8 +1,8 @@
---
title: "Managed Honcho Platform"
title: "The Honcho Dashboard"
icon: "rocket"
description: "Build socially intelligent agents without worrying about infrastructure"
sidebarTitle: "Platform Overview"
sidebarTitle: "Dashboard Overview"
---
<Card title="Sign up to start using Honcho!" icon="rocket" href="https://app.honcho.dev">

View File

@ -11,40 +11,20 @@ AI development often feels like magic - you craft the right prompt and get exact
Whether you're integrating Honcho into existing platforms, exploring advanced features, or getting up and running quickly, these guides provide concrete examples and implementation patterns.
## What You'll Find Here
Each spellbook focuses on a specific use case with working code you can adapt to your needs. The goal is to get you from idea to working prototype as quickly as possible, then provide the depth you need to scale and customize.
### Getting Started
**[Overview](/v2/guides/overview)** - You are here
**[MCP Integration](/v2/guides/mcp)** - Get Honcho running with a single prompt in Cursor or Claude Code
### Application Interfaces
## Application Interfaces
Ready-to-use integration patterns for popular platforms:
**[Discord Bot](/v2/guides/discord)** - Build a Discord bot that remembers users across conversations
**[Telegram Bot](/v2/guides/telegram)** - Create a Telegram bot with persistent user understanding
### Design Patterns
Implementation patterns for Honcho's core capabilities:
**[Dialectic Endpoint](/v2/guides/dialectic-endpoint)** - Query user psychology in natural language
**[Working with Session Context](/v2/guides/get-context)** - Manage conversation flow and context windows
**[Search](/v2/guides/search)** - Search your data using natural language
**[Working Representations](/v2/guides/working-rep)** - Understanding and customizing user models
**[Streaming Responses](/v2/guides/streaming-response)** - Handle real-time interactions efficiently
**[Using Filters](/v2/guides/using-filters)** - Control what data gets processed and how
**[File Uploads](/v2/guides/file-uploads)** - Upload PDF, text, or JSON files to create messages
## Philosophy
These aren't just API documentation - they're implementation patterns that solve real problems. Each spellbook focuses on a specific use case with working code you can adapt to your needs.
The goal is to get you from idea to working prototype as quickly as possible, then provide the depth you need to scale and customize.
<CardGroup cols={3}>
<Card title="Discord Bot" icon="discord" href="/v2/guides/discord">
Build a Discord bot that remembers users across conversations
</Card>
<Card title="Telegram Bot" icon="telegram" href="/v2/guides/telegram">
Create a Telegram bot with persistent user understanding
</Card>
<Card title="MCP" icon="link" href="/v2/guides/mcp">
Get Honcho running with a single prompt in Cursor or Claude Code
</Card>
</CardGroup>