diff --git a/docs/changelog/compatibility-guide.mdx b/docs/changelog/compatibility-guide.mdx index 2b9f67a7..883ee2d6 100644 --- a/docs/changelog/compatibility-guide.mdx +++ b/docs/changelog/compatibility-guide.mdx @@ -30,7 +30,6 @@ This guide helps you understand which versions of Honcho's API are compatible wi - ## Version Compatibility Table | Honcho API Version | TypeScript SDK | Python SDK | diff --git a/docs/docs.json b/docs/docs.json index 74f0f139..323fca93 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -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", diff --git a/docs/images/overview/honcho-overview-dark.svg b/docs/images/overview/honcho-overview-dark.svg new file mode 100644 index 00000000..753eb87b --- /dev/null +++ b/docs/images/overview/honcho-overview-dark.svg @@ -0,0 +1,4 @@ + + +Store Messages inHonchoIngestionHoncho Store Messages in LongTerm MemoryLong Term Memory StoreSends Message toReasoning EngineHoncho APIHonchoReasoningEngineMessagesPeer CardsSummariesRepresentationsSends Derived Insights to LongTerm MemoryMessagesHoncho APIGet ContextChatSearchWorking RepresentationsRetreival diff --git a/docs/images/overview/honcho-overview-light.png b/docs/images/overview/honcho-overview-light.png new file mode 100644 index 00000000..3a5b50e5 Binary files /dev/null and b/docs/images/overview/honcho-overview-light.png differ diff --git a/docs/images/overview/honcho-overview-light.svg b/docs/images/overview/honcho-overview-light.svg new file mode 100644 index 00000000..704f7ec9 --- /dev/null +++ b/docs/images/overview/honcho-overview-light.svg @@ -0,0 +1,4 @@ + + +Store Messages inHonchoIngestionHoncho Store Messages in LongTerm MemoryLong Term Memory StoreSends Message toReasoning EngineHoncho APIHonchoReasoningEngineMessagesPeer CardsSummariesRepresentationsSends Derived Insights to LongTerm MemoryMessagesHoncho APIGet ContextChatSearchWorking RepresentationsRetreival diff --git a/docs/images/overview/honcho-overview-no-background.png b/docs/images/overview/honcho-overview-no-background.png new file mode 100644 index 00000000..320ee0d8 Binary files /dev/null and b/docs/images/overview/honcho-overview-no-background.png differ diff --git a/docs/images/overview/honcho-overview.svg b/docs/images/overview/honcho-overview.svg new file mode 100644 index 00000000..a861b327 --- /dev/null +++ b/docs/images/overview/honcho-overview.svg @@ -0,0 +1,4 @@ + + +Store Messages inHonchoHoncho StoreMessages in LongTerm MemoryLong Term Memory StoreSends Message toReasoning EngineHoncho APIHonchoReasoningEngineMessagesPeer CardsSummariesRepresentationsSends DerivedInsights to LongTerm MemoryMessagesHoncho APIGet ContextChatSearchWorking Representations diff --git a/docs/_snippets/overview-shields.mdx b/docs/snippets/overview-shields.mdx similarity index 100% rename from docs/_snippets/overview-shields.mdx rename to docs/snippets/overview-shields.mdx diff --git a/docs/v2/documentation/core-concepts/architecture.mdx b/docs/v2/documentation/core-concepts/architecture.mdx index 5980d90b..1b6c7eaf 100644 --- a/docs/v2/documentation/core-concepts/architecture.mdx +++ b/docs/v2/documentation/core-concepts/architecture.mdx @@ -7,17 +7,15 @@ sidebarTitle: "Architecture" The goal of this page is to build an intuition for the primitives in Honcho and how they fit together -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`. ### 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, 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 diff --git a/docs/v2/documentation/core-concepts/configuration.mdx b/docs/v2/documentation/core-concepts/configuration.mdx index ff57dc8e..bc8635b9 100644 --- a/docs/v2/documentation/core-concepts/configuration.mdx +++ b/docs/v2/documentation/core-concepts/configuration.mdx @@ -1,5 +1,5 @@ --- -title: 'Configuration' +title: 'Configure Reasoning' description: 'Customizing how Honcho handles peers and sessions' icon: 'wrench' --- diff --git a/docs/v2/documentation/core-concepts/features.mdx b/docs/v2/documentation/core-concepts/features.mdx deleted file mode 100644 index cc1d402e..00000000 --- a/docs/v2/documentation/core-concepts/features.mdx +++ /dev/null @@ -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. diff --git a/docs/v2/guides/dialectic-endpoint.mdx b/docs/v2/documentation/core-concepts/features/dialectic-endpoint.mdx similarity index 100% rename from docs/v2/guides/dialectic-endpoint.mdx rename to docs/v2/documentation/core-concepts/features/dialectic-endpoint.mdx diff --git a/docs/v2/guides/file-uploads.mdx b/docs/v2/documentation/core-concepts/features/file-uploads.mdx similarity index 100% rename from docs/v2/guides/file-uploads.mdx rename to docs/v2/documentation/core-concepts/features/file-uploads.mdx diff --git a/docs/v2/guides/get-context.mdx b/docs/v2/documentation/core-concepts/features/get-context.mdx similarity index 99% rename from docs/v2/guides/get-context.mdx rename to docs/v2/documentation/core-concepts/features/get-context.mdx index 6722a548..fb4e7fab 100644 --- a/docs/v2/guides/get-context.mdx +++ b/docs/v2/documentation/core-concepts/features/get-context.mdx @@ -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' --- diff --git a/docs/v2/documentation/core-concepts/features/local-vs-global.mdx b/docs/v2/documentation/core-concepts/features/local-vs-global.mdx new file mode 100644 index 00000000..e5670229 --- /dev/null +++ b/docs/v2/documentation/core-concepts/features/local-vs-global.mdx @@ -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: + + + ```python Python + # Bob could run + alice.chat("What did Alice eat today?") + # Response: Alice did not eat anything today + ``` + + +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: +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 +``` + + + Local Representations are turned off by default + diff --git a/docs/v2/documentation/core-concepts/features/queue-status.mdx b/docs/v2/documentation/core-concepts/features/queue-status.mdx new file mode 100644 index 00000000..ed28161f --- /dev/null +++ b/docs/v2/documentation/core-concepts/features/queue-status.mdx @@ -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. + + +```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(); +``` + + +Output types + + +```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 + }> + +``` + + +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 + + +```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(), +}) + +``` + + +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 + + +```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 + ): Promise<{ + totalWorkUnits: number + completedWorkUnits: number + inProgressWorkUnits: number + pendingWorkUnits: number + sessions?: Record + }> +``` + diff --git a/docs/v2/guides/search.mdx b/docs/v2/documentation/core-concepts/features/search.mdx similarity index 100% rename from docs/v2/guides/search.mdx rename to docs/v2/documentation/core-concepts/features/search.mdx diff --git a/docs/v2/documentation/core-concepts/features/storing-data.mdx b/docs/v2/documentation/core-concepts/features/storing-data.mdx new file mode 100644 index 00000000..0ec7f4b4 --- /dev/null +++ b/docs/v2/documentation/core-concepts/features/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/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 diff --git a/docs/v2/guides/streaming-response.mdx b/docs/v2/documentation/core-concepts/features/streaming-response.mdx similarity index 100% rename from docs/v2/guides/streaming-response.mdx rename to docs/v2/documentation/core-concepts/features/streaming-response.mdx diff --git a/docs/v2/guides/using-filters.mdx b/docs/v2/documentation/core-concepts/features/using-filters.mdx similarity index 100% rename from docs/v2/guides/using-filters.mdx rename to docs/v2/documentation/core-concepts/features/using-filters.mdx diff --git a/docs/v2/guides/working-rep.mdx b/docs/v2/documentation/core-concepts/features/working-rep.mdx similarity index 100% rename from docs/v2/guides/working-rep.mdx rename to docs/v2/documentation/core-concepts/features/working-rep.mdx diff --git a/docs/v2/documentation/introduction/overview.mdx b/docs/v2/documentation/introduction/overview.mdx index 1fb4f199..e94a85de 100644 --- a/docs/v2/documentation/introduction/overview.mdx +++ b/docs/v2/documentation/introduction/overview.mdx @@ -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 - -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 + + + High Level Honcho Diagram + + -Developers use Honcho to store information about their users and application via -two integrated layers: +At a high level Honcho works very simply: -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? Get up and running with Honcho in minutes Understand Honcho's +href="/v2/documentation/core-concepts/architecture"> Understand Honcho's fundamental concepts ## Community & Support diff --git a/docs/v2/documentation/introduction/quickstart.mdx b/docs/v2/documentation/introduction/quickstart.mdx index 30175b5e..fb5ff35a 100644 --- a/docs/v2/documentation/introduction/quickstart.mdx +++ b/docs/v2/documentation/introduction/quickstart.mdx @@ -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({}); ``` @@ -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 ```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") ``` @@ -126,12 +126,12 @@ Sessions are independent conversations that can include multiple peers: ```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]) ``` @@ -171,7 +171,7 @@ Now ask Honcho what it's learned - this is where the magic happens: ```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." +}) +``` + - // 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 + + +```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." +}) ``` ## 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). - ---- + + + Learn about the data primitives in Honcho and how they work together + + + Sign up for Managed Honcho and get started building agents now. + + + Check out spellbooks to see different examples apps built with Honcho + + diff --git a/docs/v2/documentation/introduction/vibecoding.mdx b/docs/v2/documentation/introduction/vibecoding.mdx index 31f98ff6..7127c8e6 100644 --- a/docs/v2/documentation/introduction/vibecoding.mdx +++ b/docs/v2/documentation/introduction/vibecoding.mdx @@ -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 diff --git a/docs/v2/documentation/reference/platform.mdx b/docs/v2/documentation/reference/platform.mdx index 98b3cbb3..3b01717a 100644 --- a/docs/v2/documentation/reference/platform.mdx +++ b/docs/v2/documentation/reference/platform.mdx @@ -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" --- diff --git a/docs/v2/guides/overview.mdx b/docs/v2/guides/overview.mdx index 79a08be8..dcaf5b48 100644 --- a/docs/v2/guides/overview.mdx +++ b/docs/v2/guides/overview.mdx @@ -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. + + + Build a Discord bot that remembers users across conversations + + + Create a Telegram bot with persistent user understanding + + +Get Honcho running with a single prompt in Cursor or Claude Code + +