diff --git a/docs/docs.json b/docs/docs.json index 886a8179..712525eb 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -26,13 +26,15 @@ "group": "Introduction", "pages": [ "v2/documentation/introduction/overview", + "v2/documentation/introduction/quickstart", "v2/documentation/introduction/vibecoding" ] }, { "group": "Core Concepts", "pages": [ - "v2/documentation/core-concepts/deriver", + "v2/documentation/core-concepts/architecture", + "v2/documentation/core-concepts/reasoning", "v2/documentation/core-concepts/representation" ] }, @@ -59,6 +61,8 @@ "group": "Guides", "pages": [ "v2/guides/file-uploads", + "v2/guides/storing-data", + "v2/guides/workspace-organization", { "group": "Integrations", "pages": [ diff --git a/docs/images/architecture.png b/docs/images/architecture.png new file mode 100644 index 00000000..032eb81f Binary files /dev/null and b/docs/images/architecture.png differ diff --git a/docs/images/reasoning.png b/docs/images/reasoning.png index 48da51d4..699e6a73 100644 Binary files a/docs/images/reasoning.png and b/docs/images/reasoning.png differ diff --git a/docs/v2/documentation/core-concepts/architecture.mdx b/docs/v2/documentation/core-concepts/architecture.mdx new file mode 100644 index 00000000..f3fb4a93 --- /dev/null +++ b/docs/v2/documentation/core-concepts/architecture.mdx @@ -0,0 +1,127 @@ +--- +title: "Architecture & Intuition" +description: "Understanding Honcho's core concepts and data model." +icon: "sitemap" +sidebarTitle: "Architecture" +--- + +Honcho is a memory infrastructure that continuously reasons about data to build rich representations of peers (users, agents, or any entity) over time. This document explains the data model, system components, and how data flows through Honcho. + +## Data Model + +Honcho has a hierarchical data model centered around the entities below. + +```mermaid + graph LR + 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 +``` + +- 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 + +### Workspaces + +Workspaces are the top-level containers in Honcho. They provide complete isolation between different applications or environments, essentially serving as a namespace to keep different workloads separate. You might use separate workspaces for development, staging, and production environments, or to isolate different product lines. They also enable multi-tenant SaaS applications where each customer gets their own isolated workspace with complete data separation. + +Authentication is scoped to the workspace level, and configuration settings can be applied workspace-wide to control behavior across all peers and sessions within that workspace. + +--- + +### Peers + +Peers are the most important entity in Honcho--everything revolves around building and maintaining peer representations. A peer represents any individual user, agent, or entity in a workspace. Treating humans and agents the same way lets you build arbitrary combinations for multi-agent or group chat scenarios. + +Each peer has a unique identifier within a workspace and is a container for reasoning across all their sessions. This cross-session context means conclusions drawn about a peer in one session can inform interactions in completely different sessions. Peers can be configured to control whether Honcho forms a representation of them. + +You can use peers for any entity that persists over time--individual users in chatbot applications, AI agents interacting with users or other agents, customer profiles in support systems, student profiles in educational platforms, or even NPCs in role-playing games. + +--- + +### Sessions + +Sessions represent interaction threads or contexts between peers. A session can involve multiple peers and provides temporal boundaries for when a set of interactions starts and ends. This lets you scope context and memory to specific interactions while still maintaining longer-term peer representations that span sessions. + +Use sessions to scope things like support tickets, meeting transcripts, learning sessions, or conversations. You can also use single-peer sessions as a way to import external data--create a session with just one peer and structure emails, documents, or files as messages to enrich that peer's representation. + +Session-level configuration gives you fine-grained control over perspective-taking behavior. You can configure whether a peer should form representations of other peers in the session, and whether other peers should form representations of them. + +--- + +### Messages + +Messages are the fundamental units of interaction within sessions. While they typically represent back-and-forth communication between peers, you can also use messages to ingest any information that provides context--emails, documents, files, user actions, system notifications, or rich media content. + +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 theory-of-mind informed responses about a peer, and the get_context endpoint (`/sessions/{session_id}/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. + +When you create messages, they're immediately written to PostgreSQL and reasoning tasks are added to background queues. Background workers then generate logic, summaries, and new insights to improve representations. These conclusions and insights get stored in vector collections for retrieval. This async approach ensures fast writes while still providing rich reasoning capabilities. + +When you need context from Honcho, you query through the chat endpoint or get_context endpoint. Honcho retrieves relevant observations and conclusions from vector storage along with recent messages, then assembles everything into coherent context ready to inject into agent prompts. + +![Honcho Architecture](/images/architecture.png) + +The diagram above shows how agents write messages to Honcho, which triggers reasoning that updates peer representations. Agents can then query representations to get additional context for their next response. Black arrows represent read/write of regular data (messages, storage), while red arrows represent read/write of reasoned-over data (logic, peer representations). + +## Perspective Taking + +One of Honcho's unique capabilities is modeling how different peers perceive each other based on their interactions. When multiple peers interact in a session, Honcho can build self-representations (a peer's representation built from all messages they've sent across all sessions) and other-representations (a peer's representation of another peer, built only from messages they've observed from that peer). + +TODO: Diagram here + +This perspective-taking ability enables sophisticated multi-agent scenarios where each peer maintains distinct representations of the other participants they've interacted with. + + +Perspective taking can be configured at the peer or session level depending on your application's needs. + + +## 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. + +## 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 continuous inference (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). + +## Next Steps + + + + Sign up for the Honcho platform and start building + + + Get started with your first integration + + + Learn how Honcho reasons about messages to build memory + + + Understand what peer representations are and how they work + + diff --git a/docs/v2/documentation/core-concepts/deriver.mdx b/docs/v2/documentation/core-concepts/deriver.mdx deleted file mode 100644 index 3fa13533..00000000 --- a/docs/v2/documentation/core-concepts/deriver.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "Deriver" -icon: "gears" -sidebarTitle: "Deriver" ---- diff --git a/docs/v2/documentation/core-concepts/reasoning.mdx b/docs/v2/documentation/core-concepts/reasoning.mdx new file mode 100644 index 00000000..c0f85f67 --- /dev/null +++ b/docs/v2/documentation/core-concepts/reasoning.mdx @@ -0,0 +1,96 @@ +--- +title: "Honcho Reasoning" +icon: "gears" +sidebarTitle: "Reasoning" +--- + +Honcho is a memory system that *reasons*. You can read more on the philosophy behind the approach [here](https://blog.plasticlabs.ai/blog/Memory-as-Reasoning), but practically speaking, the system runs inference on data in the background to produce the highest quality context for simulating statefulness. This document explains why reasoning is necessary and how Honcho implements it. + + +If you'd like to experience this methodology first-hand, try out [Honcho Chat](https://honcho.chat)--an interface to your personal memory. Read more [here](https://blog.plasticlabs.ai/blog/Introducing-Honcho-Chat)! + + +## Why Reasoning? + +Traditional RAG systems treat memory as static storage--they retrieve what was explicitly said and surface it when semantically similar queries appear. Some approaches try to store structured "facts" in relational databases or knowledge graphs, but these assume you already know what's worth storing and how to structure it. Either way, once stored, those artifacts are static. You can only get back what was put in, not what logically follows. These systems are brittle, deal poorly with contradictions and incomplete information, and miss the dynamic nature of understanding. + +Honcho uses formal logic to power its system because we believe you need reasoning to access insights that are only accessible by *rigorously thinking* about your data. Static retrieval can't surface implicit connections, struggles when new information contradicts old data, and fails when you need to make predictions under uncertainty. + +Formal logic reasoning is AI-native--it performs the rigorous, compute-intensive type of reasoning that humans struggle with, instantly and consistently. Honcho uses this capability to generate new insights that go beyond simple recall, transforming retrieved context into something richer and more useful. + +## Formal Logic Framework + +Honcho's memory system is powered by custom models trained to perform three types of formal, logical reasoning: deduction, induction, and abduction. The system takes what was explicitly stated and uses them as premises to deduce conclusions based on what the model can be certain about. It then uses those conclusions as premises to identify patterns, or induce probabilistic conclusions. And it can use all of those to arrive at the simplest explanations for previous conclusions, or abductive conclusions. + +Why formal logic specifically? LLMs are uniquely well-suited for this type of reasoning. Deduction, induction, and abduction tasks are well-represented in pretraining data, making them economical and reliable. LLMs can maintain consistent reasoning across thousands of observations without cognitive fatigue or belief resistance--formal logic is actually harder for humans to do reliably, which is where models demonstrate clear advantages. The structured outputs are also composable, meaning logical conclusions can be stored, retrieved, and combined programmatically for dynamic context assembly. + +Here's an example of the data structure the reasoning models generate: + +```json +{ + "thinking": "", + "explicit": [ + { + "content": "premise 1" + }, + ... + { + "content": "premise n" + } + ], + "deductive": [ + { + "premises": [ + "premise 1", + ... + "premise n" + ], + "conclusion": "conclusion 1" + }, + ... + ] +} +``` + +The reasoning models output their "thinking" followed by things that were explicitly stated, which serve as premises to scaffold deductive conclusions. It's this reasoning foundation that further reasoning is scaffolded. Currently that includes peer cards (personality summaries and psychological profiles), duplicate checking (identifying redundant or contradictory information), induction (pattern recognition across multiple messages), and abduction (inferring the simplest explanations for observed behavior). + +The reasoning that Honcho does is something we're constantly iterating and improving on. Our goal is simple--provide the richest, most relevant context in the fastest, cheapest way possible in order to simulate statefulness in whatever setting you need. + +## How It Works + +When you write messages to Honcho, they're stored immediately and enqueued for background processing. Reasoning is computationally expensive, so processing asynchronously ensures fast writes while still providing rich reasoning capabilities. Messages are stored immediately without blocking, and session-based queues maintain chronological consistency so reasoning tasks affecting the same peer representation are always processed in order. + +The reasoning models extract explicit premises from message content, draw deductive conclusions from those premises, and use those conclusions to generate higher-order reasoning. These artifacts--observations, conclusions, summaries, peer cards--are stored as part of peer representations and indexed in vector collections for retrieval. + +![Diagram for reasoning in Honcho](/images/reasoning.png) + +The diagram above shows how agents write messages to Honcho, which triggers reasoning that updates peer representations. Agents can then query representations to get additional context for their next response. + +## Balances & Design Choices + +Off-the-shelf LLMs can perform reasoning, but they aren't optimized for it. Honcho uses custom models trained specifically for structured output (consistent JSON schema with premises and conclusions), logical rigor (following formal reasoning rules rather than plausible-sounding text), and efficiency (smaller, faster models tuned for this specific task). This allows Honcho to reason more reliably and at lower cost than general-purpose frontier LLMs. + +The approach balances quality with practical constraints. Custom models are smaller and cheaper to run, background processing means reasoning doesn't block user interactions, and structured conclusions are more token-efficient than raw conversation history. Not every message requires full reasoning--we batch where appropriate to optimize update frequency. + +Honcho's reasoning capabilities are actively being improved. Current areas of development include enhanced inductive and abductive reasoning, multi-hop reasoning, and temporal reasoning. The system is designed to be extensible--new reasoning capabilities can be added without breaking existing functionality. + + +If you find that the data you're uploading to Honcho isn't being reasoned over to your liking, we'd love to improve it for you and get your data ingested for free--reach out via [Discord](https://discord.gg/plasticlabs) or [email](mailto:support@plasticlabs.ai)! + + +## Next Steps + + + + Sign up for the Honcho platform and start building + + + Get started with your first integration + + + See how reasoning fits into Honcho's overall architecture + + + Learn how reasoning produces peer representations + + diff --git a/docs/v2/documentation/core-concepts/representation.mdx b/docs/v2/documentation/core-concepts/representation.mdx index 61e656db..b711cb75 100644 --- a/docs/v2/documentation/core-concepts/representation.mdx +++ b/docs/v2/documentation/core-concepts/representation.mdx @@ -1,5 +1,88 @@ --- title: "Peer Representations" icon: "user-magnifying-glass" -sidebarTitle: "Peer Representations" +sidebarTitle: "Representations" --- + +TODO: this is all ai generated, i haven't reviewed it + +A peer representation is the collection of reasoning Honcho has done about a peer over time. It's not a static profile or a snapshot--it's the accumulated output of continuous formal logical reasoning about everything that peer has said and done. + +When you write messages to Honcho, the reasoning models extract premises, draw conclusions, and generate insights. All of that reasoning--observations, conclusions, summaries, peer cards--gets stored as the peer's representation. Think of it as Honcho's understanding of who that peer is, what they care about, and how they behave, built through formal logic rather than simple storage. + +## What's in a Representation? + +A peer representation is made up of several types of artifacts that Honcho generates through reasoning: + +**Observations** are explicit premises extracted directly from messages. If a user says "I'm saving for a house," that's an observation. These serve as the foundation for further reasoning. + +**Conclusions** are insights derived through formal logic. Deductive conclusions are things Honcho can be certain about based on the observations. Inductive conclusions identify patterns across multiple messages. Abductive conclusions infer the simplest explanations for observed behavior. For example, if a user frequently mentions work deadlines and rarely mentions hobbies, Honcho might inductively conclude they're time-constrained or career-focused. + +**Summaries** capture the essence of sessions. Short summaries are generated every 20 messages by default, and long summaries every 60 messages. These help compress conversation history into dense, queryable context. + +**Peer cards** are personality summaries and psychological profiles. They synthesize multiple conclusions into a cohesive understanding of the peer's characteristics, preferences, and behavioral patterns. + +The reasoning flows from observations to conclusions to higher-order artifacts. Each layer builds on what came before, creating a rich, queryable representation. + +## How Representations Are Built + +Representations grow and evolve as you write data to Honcho. Here's the process: + +Messages come in attributed to a peer and stored in a session. Those messages get enqueued for background reasoning. The reasoning models extract explicit premises from the message content, then use those premises to draw deductive conclusions. Those conclusions become the basis for inductive and abductive reasoning, generating patterns and explanations. + +All of these artifacts--observations, conclusions, summaries--are indexed in vector storage as part of the peer's representation. When you query Honcho for context about a peer, it retrieves relevant pieces of that representation and composes them into a response. + +Representations are containers for reasoning, not just memory storage. They're dynamic--as new messages come in, Honcho reasons about them in the context of existing conclusions, refining and extending its understanding. Contradictions get reconciled, patterns get reinforced or revised, and the representation becomes more accurate over time. + +## Perspective-Taking + +Honcho can model how different peers perceive each other based on their interactions. This enables sophisticated multi-peer scenarios where understanding is relative, not absolute. + +There are two types of representations: + +**Self-representations** are built from all messages a peer has sent across all their sessions. This is Honcho's understanding of the peer itself, informed by everything that peer has said and done in your system. + +**Other-representations** are a peer's understanding of another peer, built only from messages they've observed from that peer. If Alice and Bob are in a session together, Bob's other-representation of Alice is based solely on what Alice said in sessions Bob was part of. Bob's representation of Alice might be completely different from Carol's representation of Alice if they've observed different interactions. + +This perspective-taking ability is configured through the `observe_me` and `observe_others` settings. A peer's `observe_me` configuration controls whether Honcho forms a representation of them at all. The `observe_others` configuration (set at the session level) controls whether a peer should form representations of other peers in that session. + +Why would you want this? In multi-agent systems, different agents might need different understandings of the same peer based on their role. A support agent might see a user as frustrated and time-sensitive, while a sales agent in a different context sees the same user as curious and exploratory. Perspective-taking lets you model these different viewpoints accurately. + +## Querying Representations + +There are two main ways to access what Honcho knows about a peer: + +The **chat endpoint** (`/peers/{peer_id}/chat`) lets you query representations with natural language. You can ask "What should I know about this user?" or "What motivates this peer?" and Honcho will retrieve relevant conclusions from the representation and synthesize an answer. This is useful when you want insights about a peer to inform how your agent should interact with them. + +The **get_context endpoint** (`/sessions/{session_id}/context`) retrieves structured context for a specific session, including recent messages, summaries, and reasoning about the peers involved. This is what you use when building the prompt for your agent's next response--it gives you everything you need in one call. + +Use the chat endpoint when you want to understand a peer. Use get_context when you want to build a contextualized response. + +## Why Representations Work + +Traditional memory systems store facts and retrieve them when queries are semantically similar. Honcho's representation approach is fundamentally different. + +Representations are built through reasoning, which means they can surface insights that were never explicitly stated. If a user mentions they're saving for a house in one session and complains about subscription costs in another, Honcho can conclude they're budget-conscious without anyone saying "I'm budget-conscious." The reasoning connects the dots. + +Representations handle contradictions gracefully. If new information conflicts with old conclusions, the reasoning process reconciles them. Facts stored in a database just sit there--reasoning adapts. + +Representations enable prediction under uncertainty. Traditional systems can only retrieve what was put in. Honcho can infer what's likely to be true based on patterns and logical reasoning, even when data is incomplete. + +This is why representations are more powerful than memory--they're not just storage, they're understanding. + +## Next Steps + + + + Sign up for the Honcho platform and start building + + + See representations in action with a working example + + + Understand how representations fit into Honcho's architecture + + + Learn how to query representations with natural language + + diff --git a/docs/v2/documentation/features/advanced/queue-status.mdx b/docs/v2/documentation/features/advanced/queue-status.mdx index 8656934f..856c1034 100644 --- a/docs/v2/documentation/features/advanced/queue-status.mdx +++ b/docs/v2/documentation/features/advanced/queue-status.mdx @@ -1,9 +1,11 @@ --- title: Queue Status -description: Learn how to check the status of the Deriver +description: Learn how to check the status of the ~~Deriver~~ Reasoning icon: "lines-leaning" --- +TODO: gotta rename this function and update these docs + 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. diff --git a/docs/v2/documentation/introduction/overview.mdx b/docs/v2/documentation/introduction/overview.mdx index 6633ffd1..4a19ca6b 100644 --- a/docs/v2/documentation/introduction/overview.mdx +++ b/docs/v2/documentation/introduction/overview.mdx @@ -12,7 +12,7 @@ Honcho is a memory system that reasons. Read more on the approach [here](https:/ ## 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: +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 formal logical reasoning. 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 @@ -23,428 +23,48 @@ Honcho streamlines the agent building process by offering elegant, flexible prim - 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. +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 context engineering, memory, and statefulness. -### Context Engineering +## How Honcho Works -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 has four core primitives that work together: +- **Workspaces** - Top-level containers that isolate different applications or environments +- **Peers** - Any entity that persists over time (users, agents, or any identity) +- **Sessions** - Interaction threads between peers with temporal boundaries +- **Messages** - Units of data that trigger reasoning and build peer [representations](/v2/documentation/core-concepts/representation) -```mermaid - graph LR - W[Workspaces] -->|have| P[Peers] - W -->|have| S[Sessions] +When you write messages to Honcho, they're stored and processed in the background. Custom reasoning models perform formal logical reasoning (deduction, induction, abduction) to generate insights about each peer. These insights--observations, conclusions, summaries--are stored as peer representations that you can query to provide rich context for your agents. - S -->|have| SM[Messages] +![Honcho Architecture](/images/architecture.png) - P <-.->|many-to-many| S +The diagram above shows the flow: agents write messages to Honcho, which triggers reasoning that updates peer representations. Agents can then query those representations to get additional context for their next response. - 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 -``` +## Why Reasoning? -- 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. +Traditional RAG systems retrieve what was explicitly said, but they miss insights that are only accessible by *rigorously thinking* about your data. Static retrieval can't surface implicit connections, struggles when new information contradicts old data, and fails when you need to make predictions under uncertainty. -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. +Honcho uses formal logic to generate new insights by combining premises. This reasoning is AI-native--it performs the rigorous, compute-intensive type of reasoning that humans struggle with, instantly and consistently. The result is memory that goes beyond simple recall to provide truly contextual understanding. -### Memory +## Get Started -Honcho is built around custom models that are selectively reasoning about context written to it. These models produce formal logic that power 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. +Honcho gives you maximum control over your agent's memory. The data model is flexible and composable, the reasoning layer is powerful yet cost-effective, and everything is built to give developers control over token usage, latency, and personalization depth. - - - - - -The *deriver* (TODO: link to concept page) orchestrates all this reasoning in the background when you write messages to sessions or peers. - -Let's start with a simple implementation. - -## Quickstart - - -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. - - -#### 1. Install the SDK - - -```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 -``` - - -#### 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. - - -```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" }); - -``` - - - -#### 3. Create Peers - - -```python Python -user = honcho.peer("user") -assistant = honcho.peer("assistant") -``` - -```typescript TypeScript -const user = await honcho.peer("user") -const assistant = await honcho.peer("assistant") -``` - - -#### 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. - - - - - ```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." - } - ] - } - ] - } - ``` - - - - -```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); -} -``` - - -#### 5. Query for Insights - -Now ask Honcho what it's learned - this is where the magic happens: - - -```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); -}) -``` - - - -Honcho needs a short amount of time to process messages you write to it. There are several utilities to (TODO: FIX LINK) check the status of the queue. Honcho also offers numerous ways to query reasoning to fit latency needs. - - -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 - - - - - -```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); - -``` - - - - -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. +We're just scratching the surface here. Dive into the quickstart to see Honcho in action, explore the architecture to understand how it all fits together, or jump straight to building. Welcome to Honcho. We're excited to have you at the frontier of AI with us 🫡. -TODO: cards to concepts? + + + Sign up for the Honcho platform and get your API key + + + Build your first stateful agent in minutes + + + Deep dive into how Honcho's primitives fit together + + + Learn how Honcho reasons about data to build memory + + diff --git a/docs/v2/documentation/introduction/quickstart.mdx b/docs/v2/documentation/introduction/quickstart.mdx new file mode 100644 index 00000000..e02b9e02 --- /dev/null +++ b/docs/v2/documentation/introduction/quickstart.mdx @@ -0,0 +1,403 @@ +--- +title: "Quickstart" +icon: "bolt" +sidebarTitle: "Quickstart" +--- + +Let's start with a simple implementation. + + +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. + + +#### 1. Install the SDK + + +```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 +``` + + +#### 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. + + +```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" }); + +``` + + + +#### 3. Create Peers + + +```python Python +user = honcho.peer("user") +assistant = honcho.peer("assistant") +``` + +```typescript TypeScript +const user = await honcho.peer("user") +const assistant = await honcho.peer("assistant") +``` + + +#### 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. + + + + + ```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." + } + ] + } + ] + } + ``` + + + + +```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); +} +``` + + +#### 5. Query for Insights + +Now ask Honcho what it's learned - this is where the magic happens: + + +```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); +}) +``` + + + +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. + + +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. + + +## Next Steps + +You just saw how Honcho reasons about data to build rich peer representations. In this quickstart, you: + +- Set up a workspace with peers (user and assistant) +- Ingested messages across multiple sessions +- Queried the reasoning to get synthesized insights about the user + +Here's the full working code if you want to run it yourself: + + + + + +```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); + +``` + + + + +From here, you can explore how to use Honcho's features in your own applications: + + + + Learn how to fetch the right context for your agent's next response + + + Deep dive into how Honcho's primitives fit together + + + Query representations with natural language + + + Integration patterns and advanced use cases + + diff --git a/docs/v2/guides/storing-data.mdx b/docs/v2/guides/storing-data.mdx new file mode 100644 index 00000000..4590060c --- /dev/null +++ b/docs/v2/guides/storing-data.mdx @@ -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` + + + + ```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]); +``` + + +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/features/advanced/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 \ No newline at end of file diff --git a/src/schemas.py b/src/schemas.py index 8b6068da..fef98374 100644 --- a/src/schemas.py +++ b/src/schemas.py @@ -112,6 +112,7 @@ class PeerCardResponse(BaseModel): class PeerConfig(BaseModel): + # TODO: Update description - should say "Whether honcho forms a representation of the peer itself" observe_me: bool = Field( default=True, description="Whether honcho should form a global theory-of-mind representation of this peer", @@ -187,10 +188,12 @@ class SessionBase(BaseModel): class SessionPeerConfig(BaseModel): + # TODO: Update description - should say "Whether this peer forms representations of other peers in the session" observe_others: bool = Field( default=False, description="Whether this peer should form a session-level theory-of-mind representation of other peers in the session", ) + # TODO: Update description - should say "Whether other peers in this session form a representation of this peer" observe_me: bool | None = Field( default=None, description="Whether other peers in this session should try to form a session-level theory-of-mind representation of this peer",