diff --git a/docs/docs.json b/docs/docs.json
index 3b3e5f91..4df76911 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -34,7 +34,16 @@
"group": "Core Concepts",
"pages": [
"v2/documentation/core-concepts/architecture",
- "v2/documentation/core-concepts/features",
+ "v2/documentation/core-concepts/features/messages-and-memories",
+ "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-representations",
"v2/documentation/core-concepts/configuration",
"v2/documentation/core-concepts/summarizer",
"v2/documentation/core-concepts/glossary"
@@ -59,18 +68,6 @@
{
"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"
- ]
}
]
},
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 @@
+
+
+
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 @@
+
+
+
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 @@
+
+
+
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/configuration.mdx b/docs/v2/documentation/core-concepts/configuration.mdx
index ff57dc8e..ced19fe7 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 Peers'
description: 'Customizing how Honcho handles peers and sessions'
icon: 'wrench'
---
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/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/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 bb6f7fdf..ed2eddad 100644
--- a/docs/v2/documentation/introduction/overview.mdx
+++ b/docs/v2/documentation/introduction/overview.mdx
@@ -5,9 +5,14 @@ icon: "brain"
sidebarTitle: "Overview"
---
-Honcho is an AI-native memory library for building agents with [state-of-the-art](https://blog.plasticlabs.ai/research/Introducing-Neuromancer-XR) memory.
+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.
-It then goes beyond basic memory by reasoning about the stored data
+Agents using Honcho have perfect recall with a wide variety of tools to traverse
+the history of an agent and get the exact context they need when they need it.
+
+It then goes beyond basic memory by reasoning about the stored messages
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.
@@ -24,13 +29,14 @@ Use it to build
# Start simple - just add 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
@@ -40,27 +46,56 @@ Designed for developers and agents alike:
## How It Works
-### Storage
+
+
+
+
-Developers use Honcho to store information about their users and application via
-two integrated layers:
+
-**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.
-**Reasoning Layer**: Continuously analyzes stored interactions to improve the
-memories and representation of each `Peer` in the system.
+At a high level Honcho works very simply:
-### Retrieval
+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
-Once data is stored and generated within Honcho, the API exposes several
-different ways to retrieve and use those insights.
+There are several API endpoints to leverage the memory & insights in Honcho.
-**[Dialectic API](/v2/guides/dialectic-endpoint)**: This is the flagship
-endpoint that allows developers chat with Honcho about any aspect of each user
-in your system to get dynamic, in-context actionable insights.
+### Get Context
+
+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
+
+- 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)
+
+### Search
+
+This endpoint lets you search across Honcho for relevant messages either using a
+hybrid search strategy that combines text search and cosine similarity.
+
+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 comes in handy when you want your agent to back-channel with Honcho to
+change it's behavior at runtime.
Example Queries
- "What's the best way to explain technical concepts to this user?"
@@ -69,32 +104,6 @@ Example Queries
- "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
diff --git a/docs/v2/guides/overview.mdx b/docs/v2/guides/overview.mdx
index f3093fea..dcaf5b48 100644
--- a/docs/v2/guides/overview.mdx
+++ b/docs/v2/guides/overview.mdx
@@ -28,31 +28,3 @@ Ready-to-use integration patterns for popular platforms:
Get Honcho running with a single prompt in Cursor or Claude Code
-
-## Design Patterns
-Implementation patterns for Honcho's core capabilities:
-
-
-
-
- Query user psychology in natural language
-
-
-Manage conversation flow and context windows
-
-
- Search your data using natural language
-
-
- Understanding and customizing user models
-
-
-Handle real-time interactions efficiently
-
-
-Control what data gets processed and how
-
-
-Upload PDF, text, or JSON files to create messages
-
-
+
-Developers use Honcho to store information about their users and application via
-two integrated layers:
+