RomanNum3ral
/
honcho
mirror of https://github.com/plastic-labs/honcho.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

chore: docs TODOs cleanup

This commit is contained in:
Benjamin McCormick 2025-12-10 12:13:44 -05:00
parent 9950a1cfc4
commit 5bcde13d0f
5 changed files with 31 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
docs/v2/documentation/core-concepts/architecture.mdx
View File

@ -64,19 +64,6 @@ Messages are the fundamental units of interaction within sessions. While they ty
Every message is attributed to a specific peer and ordered chronologically within its session. When messages are created, they trigger automatic background reasoning that updates peer representations. Messages support rich metadata and structured data through JSONB fields, making them flexible enough to capture whatever information matters for your use case.
## System Components
TODO: devs tell me if this section is legit or not pls
At a high level, Honcho has three main components that work together.
The API layer is your primary interface--a REST API for managing workspaces, peers, sessions, and messages, plus specialized endpoints for querying representations. The chat endpoint (`/peers/{peer_id}/chat`) gives you reasoning-informed responses about a peer, and the get_context endpoint (`/sessions/{session_id}/get_context`) retrieves relevant context for generating agent responses. Authentication uses JWTs that can be scoped to workspace, peer, or session level for fine-grained access control.
Storage runs on PostgreSQL with pgvector for semantic search. All the structured data--workspaces, peers, sessions, messages--lives in relational tables, while reasoning outputs are stored as vectors in internal collections for similarity search. Token counts are tracked automatically for usage monitoring, and JSONB metadata fields let you extend primitives with custom data.
Background reasoning processes messages asynchronously to build and update peer representations. Messages get enqueued for reasoning without blocking writes, and session-based queues ensure chronological ordering. Honcho runs multiple types of reasoning tasks--representation updates, summarization, peer card generation, and more. Tasks are processed in parallel across different peers, but tasks affecting the same peer representation are always processed serially in order of message creation to maintain consistency.
## Data Flow
Understanding how data moves through Honcho helps clarify the architecture.
@ -91,11 +78,11 @@ The diagram above shows how agents write messages to Honcho, which triggers reas
## Configuration & Extensibility
Honcho is designed to be flexible. Settings cascade hierarchically from workspace to peer to session, so you can set defaults at the workspace level and override them for specific peers or sessions. Feature flags let you enable or disable reasoning modes, perspective tracking, and other capabilities. You can bring your own LLM provider--OpenAI, Anthropic, or custom endpoints--and metadata fields let you extend any primitive with custom JSONB data. TODO: devs fact check pls-->Batch operations let you create up to 100 messages in a single API call for efficient bulk ingestion.
Honcho is designed to be flexible. Settings cascade hierarchically from workspace to peer to session, so you can set defaults at the workspace level and override them for specific peers or sessions. Feature flags let you enable or disable reasoning modes, perspective tracking, and other capabilities. You can bring your own LLM provider--OpenAI, Anthropic, or custom endpoints--and metadata fields let you extend any primitive with custom JSON data. Batch operations let you create up to 100 messages in a single API call for efficient bulk ingestion.
## Design Principles
Honcho's architecture follows a few core principles. Everything revolves around building representations of peers (peer-centric). Memory isn't just storage--it's continual learning (reasoning-first). Expensive operations happen in the background so they don't block user interactions (async by default). The system works with any LLM provider (provider-agnostic) and is built for isolation and scalability from the ground up (multi-tenant). Users and agents are both represented as peers, which enables flexible scenarios you couldn't easily model with a traditional user-assistant paradigm (unified paradigm).
Honcho's architecture follows a few core principles. Everything revolves around building representations of peers (peer-centric). Memory isn't just storage--it's continual learning (reasoning-first). Long-lived operations happen in the background so they don't block user interactions (async by default). The system works with any LLM provider (provider-agnostic) and is built for isolation and scalability from the ground up (multi-tenant). Users and agents are both represented as peers, which enables flexible scenarios you couldn't easily model with a traditional user-assistant paradigm (unified paradigm).
## Next Steps

22
docs/v2/documentation/features/advanced/toggle-reasoning.mdx
View File

@ -12,13 +12,13 @@ Configuration follows a hierarchy: **message > session > workspace > global defa
Honcho uses a hierarchical configuration system where more specific settings override more general ones:
TODO: should peer be included here?
1. **Global Defaults**: Built-in system defaults
2. **Workspace Configuration**: Settings that apply to all sessions in a workspace
3. **Session Configuration**: Settings that apply to all messages in a session
4. **Message Configuration**: Settings that apply to a specific message
Separately, you can configure the reasoning status of a peer. This overrides defaults and workspace configuration, but not session or message configuration.
<Info>
All configuration fields are optional. If not specified, the value is inherited from the next level up in the hierarchy.
</Info>
@ -60,14 +60,12 @@ const session = await honcho.session("private-session", {
### Peer Card Configuration
TODO: is create a catch-all for update?
Controls how peer cards (containing key biographical information) are generated and used.
| Field | Type | Description |
|-------|------|-------------|
| `use` | `bool` | Whether to use peer cards during the reasoning process. |
| `create` | `bool` | Whether to generate peer cards based on message content. |
| `create` | `bool` | Whether to generate and update peer cards based on message content. |
<CodeGroup>
```python Python
@ -123,8 +121,6 @@ const session = await honcho.session("verbose-session", {
### Dream Configuration
TODO: fill out code blocks? or get rid of them? having them there for comments seems silly
Controls the "dreaming" process that consolidates and refines representations. Available at workspace and session levels only.
| Field | Type | Description |
@ -134,11 +130,19 @@ Controls the "dreaming" process that consolidates and refines representations. A
<CodeGroup>
```python Python
# Disable dreams for a workspace
# (done via API when creating/updating workspace)
honcho.set_config({
"dream": {
"enabled": False
}
})
```
```typescript TypeScript
// Disable dreams for a workspace
// (done via API when creating/updating workspace)
await honcho.setConfig({
dream: {
enabled: false
}
});
```
</CodeGroup>

12
docs/v2/documentation/features/chat.mdx
View File

@ -167,12 +167,10 @@ const goals = await peer.chat("What are the user's main goals or objectives?");
When you call `peer.chat(query)`:
TODO: update with agentic approach?
1. Honcho searches through the peer's representation--conclusions drawn from reasoning over their messages
1. Honcho searches through the peer's peer card and representation--conclusions drawn from reasoning over their messages
2. Retrieves conclusions semantically relevant to your query
3. Synthesizes them into a coherent natural language answer
4. Returns the answer to your application
3. Combines them with segments of source messages, if needed, to gather more context
4. Synthesizes them into a coherent natural language response to your query
Honcho [reasoning](/v2/documentation/core-concepts/reasoning) runs continuously in the background, processing new messages and updating representations. The chat endpoint always has access to Honcho's latest conclusions about the peer.
@ -182,7 +180,7 @@ Honcho [reasoning](/v2/documentation/core-concepts/reasoning) runs continuously
Instead of "Tell me about the user", ask "What communication style does the user prefer?" You'll get more actionable answers.
### Let your LLM formulate queries
The chat endpoint shines when your LLM decides what it needs to know. This creates dynamic, context-aware personalization.
The chat endpoint shines when your LLM decides what it needs to know. This creates dynamic, context-aware personalization. An excellent way to achieve this, if building an agent, is to give access to the Honcho chat endpoint as just another tool.
### Use for runtime decisions
Don't just use chat for LLM prompts - use it to drive application logic, routing, and feature flags based on user behavior.
@ -190,4 +188,4 @@ Don't just use chat for LLM prompts - use it to drive application logic, routing
### Combine with get_context()
Use `get_context()` for conversation context and `peer.chat()` for specific insights. They complement each other.
For more ideas on using the chat endpoint, see our blog post on [flexible agent communication](https://blog.plasticlabs.ai/blog/Introducing-Honcho's-chat-API#how-it-works).
For more ideas on using the chat endpoint, see our [guides](/v2/guides/overview).

23
docs/v2/documentation/features/get-context.mdx
View File

@ -6,9 +6,8 @@ icon: 'messages'
The `get_context()` method is a powerful feature that retrieves formatted conversation context from sessions, making it easy to integrate with LLMs like OpenAI, Anthropic, and others. This guide covers everything you need to know about working with session context.
TODO: if reasoning is on by default (which we're changing the package to do), doesn't this mean that a working rep gets assembled?
By default, the context includes a blend of summary and messages which covers the entire history of the session. Summaries are automatically generated at intervals and recent messages are included depending on how many tokens the context is intended to be. You can specify any token limit you want, and can disable summaries to fill that limit entirely with recent messages.
By default, the context includes a blend of summary and messages which covers the entire history of the session. Summaries are automatically generated at intervals and recent messages are included depending on how many tokens the context is intended to be. You can specify any token limit you want, and can disable summaries to fill that limit entirely with recent messages. To get representation data, you need to specify a target peer.
## Basic Usage
@ -143,17 +142,14 @@ context = session.get_context(
### Semantic Search with Last Message
Use `last_user_message` to fetch semantically relevant conclusions based on the most recent message:
TODO: Update code here
Use `last_user_message` to fetch semantically relevant conclusions based on the most recent message (requires `peer_target`):
<CodeGroup>
```python Python
# Get context with semantic search based on last message
context = session.get_context(
tokens=2000,
peer_target="user-123",
last_user_message="What are my account preferences?",
last_user_message="What are my coding preferences?",
search_top_k=10, # Number of relevant observations
search_max_distance=0.8, # Max semantic distance (0.0-1.0)
include_most_derived=True, # Include most recent observations
@ -163,15 +159,16 @@ context = session.get_context(
```typescript TypeScript
(async () => {
// Get context with semantic search based on last message
const context = await session.getContext({
tokens: 2000,
peerTarget: "user-123",
lastUserMessage: "What are my account preferences?",
searchTopK: 10, // Number of relevant observations
searchMaxDistance: 0.8, // Max semantic distance (0.0-1.0)
includeMostDerived: true, // Include most recent observations
maxObservations: 25 // Cap total observations
lastUserMessage: "What are my coding preferences?",
representationOptions: {
searchTopK: 10, // Number of relevant observations
searchMaxDistance: 0.8, // Max semantic distance (0.0-1.0)
includeMostDerived: true, // Include most recent observations
maxObservations: 25 // Cap total observations
}
});
})();
```

5
docs/v2/documentation/introduction/quickstart.mdx
View File

@ -44,8 +44,6 @@ pnpm add @honcho-ai/sdk
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
@ -60,7 +58,6 @@ import { Honcho } from '@honcho-ai/sdk';
// Initialize client
const honcho = new Honcho({ workspace = "first-honcho-test", apiKey = HONCHO_API_KEY });
```
</CodeGroup>
@ -233,7 +230,7 @@ user.chat("What should I know about this user? 3 sentences max").then((response)
</CodeGroup>
<Tip>
Honcho needs a short amount of time to process messages you write to it. There are several utilities to [check the status](/v2/documentation/features/advanced/queue-status) of the queue. Honcho also offers numerous ways to query reasoning to fit latency needs, see the [Get Context](/v2/documentation/features/get-context) page.
Honcho needs a short amount of time to process messages you write to it. There are several utilities to [check the status](/v2/documentation/features/advanced/queue-status) of the queue. Honcho also offers numerous ways to query reasoning to fit latency needs: see the [Get Context](/v2/documentation/features/get-context) page.
</Tip>
The response will look something like this: