diff --git a/docs/images/alice-bob.png b/docs/images/alice-bob.png deleted file mode 100644 index d15f158a..00000000 Binary files a/docs/images/alice-bob.png and /dev/null differ diff --git a/docs/images/observe_config.png b/docs/images/observe_config.png new file mode 100644 index 00000000..29e387a8 Binary files /dev/null and b/docs/images/observe_config.png differ diff --git a/docs/v2/documentation/core-concepts/architecture.mdx b/docs/v2/documentation/core-concepts/architecture.mdx index 21e32292..7e4bc771 100644 --- a/docs/v2/documentation/core-concepts/architecture.mdx +++ b/docs/v2/documentation/core-concepts/architecture.mdx @@ -71,7 +71,7 @@ TODO: devs tell me if this section is legit or not pls At a high level, Honcho has three main components that work together. -The API layer is your primary interface--a REST API for managing workspaces, peers, sessions, and messages, plus specialized endpoints for querying representations. The chat endpoint (`/peers/{peer_id}/chat`) gives you reasoning-informed responses about a peer, and the get_context endpoint (`/sessions/{session_id}/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. +The API layer is your primary interface--a REST API for managing workspaces, peers, sessions, and messages, plus specialized endpoints for querying representations. The chat endpoint (`/peers/{peer_id}/chat`) gives you reasoning-informed responses about a peer, and the get_context endpoint (`/sessions/{session_id}/get_context`) retrieves relevant context for generating agent responses. Authentication uses JWTs that can be scoped to workspace, peer, or session level for fine-grained access control. Storage runs on PostgreSQL with pgvector for semantic search. All the structured data--workspaces, peers, sessions, messages--lives in relational tables, while reasoning outputs are stored as vectors in internal collections for similarity search. Token counts are tracked automatically for usage monitoring, and JSONB metadata fields let you extend primitives with custom data. diff --git a/docs/v2/documentation/core-concepts/reasoning.mdx b/docs/v2/documentation/core-concepts/reasoning.mdx index 96abc0c7..4e2e1ca3 100644 --- a/docs/v2/documentation/core-concepts/reasoning.mdx +++ b/docs/v2/documentation/core-concepts/reasoning.mdx @@ -12,6 +12,8 @@ If you'd like to experience this methodology first-hand, try out [Honcho Chat](h ## Why Reasoning? +TODO: workshop, i think it's a bit wordy? + 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. @@ -22,7 +24,7 @@ Formal logic reasoning is AI-native--it performs the rigorous, compute-intensive 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. +Why formal logic specifically? LLMs are uniquely well-suited for this reasoning task--it's well-represented in the pretraining data. LLMs can maintain consistent reasoning across thousands of observations without cognitive fatigue or belief resistance--which is extremely hard for humans to do reliably. The 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: diff --git a/docs/v2/documentation/core-concepts/representation.mdx b/docs/v2/documentation/core-concepts/representation.mdx index fee26fd2..30d84c6e 100644 --- a/docs/v2/documentation/core-concepts/representation.mdx +++ b/docs/v2/documentation/core-concepts/representation.mdx @@ -4,13 +4,13 @@ icon: "user-magnifying-glass" sidebarTitle: "Representations" --- -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 reasoning about every message that's been written to the peer. Representations evolve dynamically as new messages come in, with Honcho reasoning about them in the context of existing conclusions, reconciling contradictions and refining understanding. +A representation is the collection of reasoning Honcho has done about a peer over time. It's the continual learning about a peer over every message that's been written to it. Representations evolve dynamically as new messages come in, with Honcho reasoning about them in the background. -When you write messages to Honcho, the reasoning models extract premises, draw conclusions, and generate insights. All of that reasoning 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. +When you write messages to Honcho, the reasoning models extract premises, draw conclusions, and scaffold new conclusions as well. All of that reasoning 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: +A peer representation is made up of several types of artifacts that Honcho generates through [*reasoning*](/v2/documentation/core-concepts/reasoning): **Conclusions** are insights derived through formal logic. Deductive conclusions are things Honcho can be certain about based on the premises. 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. @@ -18,49 +18,33 @@ A peer representation is made up of several types of artifacts that Honcho gener **Peer cards** contain key biographical information. They essentially cache the most basic information about a peer (name, occupation, interests) to ensure the model never loses its grounding. -TODO: workshop this--The reasoning flows from premises to conclusions to higher-order artifacts. Each layer builds on what came before, creating a rich, queryable representation. - - -For details on how reasoning works (deduction, induction, abduction), see the [Reasoning](/v2/documentation/core-concepts/reasoning) page. - ## Observation & Perspective-Taking Honcho can build different representations based on what each peer observes. This enables sophisticated multi-peer scenarios where understanding is relative to what was actually witnessed. -There are two observation modes controlled by configuration: +There are two observation modes controlled by [configuration](/v2/documentation/features/advanced/configuration): **Honcho observing peers** (`observe_me`): When enabled (default), Honcho forms a representation of the peer based on all messages they've sent across all sessions. This is Honcho's understanding of that peer, built from everything they've said and done in your system. Set `observe_me: false` if you don't want Honcho to reason about that peer at all. -**Peers observing others** (`observe_others`): When enabled at the session level, a peer will form representations of other peers in that session based only on messages they've observed. If Alice and Opus are in a session together and Opus has `observe_others: true`, Opus will form a representation of Alice based solely on what Alice said in sessions Opus participated in. Opus's representation of Alice will be completely different from Carol's representation of Alice if they've observed different interactions. +**Peers observing others** (`observe_others`): When enabled at the session level, a peer will form representations of other peers in that session based only on messages they've observed. If Alice and Bob are in a session together and Bob has `observe_others: true`, Bob will form a representation of Alice based solely on what Alice said in sessions Bob participated in. Bob's representation of Alice will be completely different from Carol's representation of Alice if they've observed different interactions. -![](/images/alice-bob.png) +In the diagram below, assume `observe_me` isn't turned off (again, default behavior) and `observe_others` is turned on for both peers in a session that contains the peers Alice and Bob. -The diagram above shows observation in practice. Honcho can observe each peer (forming representations based on everything they say), and individual peers can observe others (forming representations based only on what they witness in shared sessions). +![](/images/observe_config.png) -Why would you want peers observing others? In multi-agent systems, different agents have access to different information. If Opus participates in sessions 1 and 2 with Alice, while Sonnet only participates in session 3, Opus's representation of Alice will be built from sessions 1 and 2, while Sonnet's representation will only include what happened in session 3. This information segmentation based on what each agent observed is critical for accurately modeling multi-agent scenarios. +The shared session that Alice and Bob have informs their respective representations of each other. Alice has a small set of conclusions that pertain to Bob, and Bob has a small set of conclusions that pertain to Alice. Honcho can observe the totality of each peer's interactions, forming representations of the peers themselves, and enable peers to store conclusions about peers they interact with based only on what they witness in shared sessions. - -By default, `observe_me` is `true` (Honcho observes all peers) and `observe_others` is `false` (peers don't observe each other). You can configure both at the peer and session level depending on your needs. - +Why would you want peers observing others? So you can simulate stateful *perspectives*. If Bob participates in sessions 1 and 2 with Alice, while Carol only participates in session 3, Bob's representation of Alice will be built from sessions 1 and 2, while Carol's representation will only include what happened in session 3. This information segmentation based on what each agent observed is critical for accurately segmenting statefulness in multi-agent scenarios. -## Querying Representations - -There are two main ways to access what Honcho knows about a peer: - -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. The goal of get_context is to solve statefulness with one method--it gives you everything you need in one call to make your agent feel like it remembers. - -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. Use this when you need super specific context that requires bespoke querying and synthesis--insights that might lie outside the distribution of what get_context provides. This is useful for steering agent behavior based on deep understanding of a peer. - -Use get_context for standard contextualized responses. Use chat when you need to dig deeper or query for something specific. ## Why Representations Work -Statefulness is simulated through reconstruction of the past. Traditional systems reconstruct by retrieving stored facts when queries are semantically similar. Honcho reconstructs through reasoning, which changes everything. +Statefulness is simulated through reconstruction of the past. Traditional systems reconstruct by retrieving stored facts, querying semantically similar items, and hoping the LLM does the rest. Honcho reconstructs through reasoning about the past exhaustively, leaving much less to chance. Reasoning can surface insights 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 it. Reasoning handles contradictions gracefully--when new information conflicts with old conclusions, it reconciles them instead of just accumulating more data. And reasoning enables prediction under uncertainty, inferring what's likely true based on patterns even when data is incomplete. -Humans reconstruct the past from imperfect recollections, then act on those reconstructions as if they were complete. Reasoning enables agents to do this perfectly. Representations produce an exhaustive, explicit record of what can be concluded about a peer--giving agents a complete foundation that humans can only pretend to have. That's what makes truly stateful agents possible. +Humans reconstruct the past from imperfect recollections, then act on those reconstructions as if they were complete. Representations enable agents to do the same with far greater fidelity. Reasoning produces an exhaustive, explicit record of what can be concluded about a peer--giving agents complete recollection that humans can only pretend to have. That's what makes truly stateful agents possible. ## Next Steps diff --git a/docs/v2/documentation/introduction/overview.mdx b/docs/v2/documentation/introduction/overview.mdx index 53a89f4d..797cba90 100644 --- a/docs/v2/documentation/introduction/overview.mdx +++ b/docs/v2/documentation/introduction/overview.mdx @@ -36,14 +36,14 @@ All the while usage dwindles, customers churn, and motivation to solve the probl ## How Honcho Works -Honcho has four core primitives that work together: +Honcho has four storage primitives that work together: - **Workspaces** - Top-level containers that isolate different applications or environments - **Peers** - Any entity that persists over time (users, agents, objects, and more) - **Sessions** - Interaction threads between peers with temporal boundaries - **Messages** - Units of interaction that trigger reasoning -When you write messages to Honcho, they're stored and processed in the background. Custom reasoning models perform formal logical [*reasoning*](/v2/documentation/core-concepts/reasoning) (deduction, induction, abduction) to generate insights about each peer. These conclusions are stored as [*representations*](/v2/documentation/core-concepts/representation) that you can query to provide rich context for your agents. +When you write messages to Honcho, they're stored and processed in the background. Custom reasoning models perform formal logical [*reasoning*](/v2/documentation/core-concepts/reasoning) to generate insights about each peer. These conclusions are stored as [*representations*](/v2/documentation/core-concepts/representation) that you can query to provide rich context for your agents. ![Honcho Architecture](/images/architecture.png) @@ -51,7 +51,9 @@ The diagram above shows the flow: agents write messages to Honcho, which trigger ## Why Reasoning? -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. +TODO: Workshop this + +Traditional RAG systems retrieve what was explicitly said, but they miss things 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. 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. diff --git a/docs/v2/documentation/introduction/quickstart.mdx b/docs/v2/documentation/introduction/quickstart.mdx index 3e384d34..289b98e4 100644 --- a/docs/v2/documentation/introduction/quickstart.mdx +++ b/docs/v2/documentation/introduction/quickstart.mdx @@ -6,6 +6,8 @@ sidebarTitle: "Quickstart" Let's start with a simple implementation. +TODO: move "next Steps" up here to "tell em what you're gonna tell em" + 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". @@ -47,7 +49,7 @@ TODO: change default environment to production, require an API key. from honcho import Honcho # Initialize client -honcho = Honcho(workspace="first-honcho-test") +honcho = Honcho(workspace="first-honcho-test", api_key=HONCHO_API_KEY) ``` @@ -55,7 +57,7 @@ honcho = Honcho(workspace="first-honcho-test") import { Honcho } from '@honcho-ai/sdk'; // Initialize client -const honcho = new Honcho({ workspace = "first-honcho-test" }); +const honcho = new Honcho({ workspace = "first-honcho-test", apiKey = HONCHO_API_KEY }); ``` @@ -213,7 +215,7 @@ for (const sessionData of data.sessions) { #### 5. Query for Insights -Now ask Honcho what it's learned - this is where the magic happens: +Now ask Honcho what it's learned--this is where the magic happens: ```python Python