diff --git a/docs/docs.json b/docs/docs.json
index b5898c6f..232e22e9 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -97,7 +97,8 @@
"v3/guides/integrations/langgraph",
"v3/guides/integrations/mcp",
"v3/guides/integrations/n8n",
- "v3/guides/integrations/openclaw"
+ "v3/guides/integrations/openclaw",
+ "v3/guides/integrations/hermes"
]
},
{
@@ -113,8 +114,7 @@
{
"group": "Community Integrations",
"pages": [
- "v3/guides/community/agent0",
- "v3/guides/community/hermes"
+ "v3/guides/community/agent0"
]
},
{
diff --git a/docs/v3/guides/community/hermes.mdx b/docs/v3/guides/community/hermes.mdx
deleted file mode 100644
index d22cb2e4..00000000
--- a/docs/v3/guides/community/hermes.mdx
+++ /dev/null
@@ -1,33 +0,0 @@
----
-title: "Hermes Agent"
-icon: 'bolt'
-description: "Add AI-native memory to Hermes Agent"
-sidebarTitle: 'Hermes Agent'
----
-
-[Hermes Agent](https://github.com/NousResearch/hermes-agent) is an open-source AI agent from Nous Research with advanced tool-calling capabilities, terminal access, a skills system, and multi-platform deployment (Telegram, Discord, Slack, WhatsApp). The Honcho integration gives Hermes persistent cross-session memory and user modeling.
-
-## Getting Started
-
-Honcho support is built into Hermes Agent. See the [Hermes Agent README](https://github.com/NousResearch/hermes-agent) for full installation and configuration instructions.
-
-The integration is opt-in and requires:
-1. A Honcho API key from [app.honcho.dev](https://app.honcho.dev)
-2. The `honcho-ai` package (`pip install hermes-agent[honcho]`)
-3. Enabling Honcho in your Hermes config
-
-## How It Works
-
-The integration runs alongside Hermes's existing `USER.md` memory system. Honcho adds cross-session reasoning — prefetching user context into each turn, syncing exchanges for ongoing modeling, and exposing a dialectic tool (`query_user_context`) for the agent to query its understanding mid-conversation.
-
-## Next Steps
-
-
-
- Source code, installation, and full documentation.
-
-
-
- Learn about peers, sessions, and dialectic reasoning.
-
-
diff --git a/docs/v3/guides/integrations/hermes.mdx b/docs/v3/guides/integrations/hermes.mdx
new file mode 100644
index 00000000..e19d2d64
--- /dev/null
+++ b/docs/v3/guides/integrations/hermes.mdx
@@ -0,0 +1,187 @@
+---
+title: "Hermes Agent + Honcho"
+sidebarTitle: "Hermes Agent"
+description: "How Hermes Agent uses Honcho for persistent cross-session memory and user modeling"
+icon: "message-bot"
+---
+
+[Hermes Agent](https://github.com/NousResearch/hermes-agent) is an open-source AI agent from [Nous Research](https://nousresearch.com) with tool-calling, terminal access, a skills system, and multi-platform deployment (Telegram, Discord, Slack, WhatsApp). Honcho gives Hermes persistent cross-session memory and user modeling.
+
+For setup, configuration, and CLI commands, see the [Hermes Agent Honcho docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/honcho).
+
+## What Honcho provides
+
+Honcho acts as a long-term memory and user-model layer alongside Hermes' built-in memory files (`MEMORY.md` and `USER.md`).
+
+It gives Hermes three capabilities:
+
+1. **Prompt-time context injection** -- durable context about a user loaded into the prompt before generating a response.
+2. **Cross-session continuity** -- recall of stable preferences, project history, and working context across conversations.
+3. **Durable writeback** -- stable facts learned during a conversation stored back for future turns.
+
+These sit alongside Hermes' local session history. Session history remembers the current conversation. Honcho remembers what should still matter later.
+
+## Dual-peer architecture
+
+Both the user and the AI agent have peer representations in Honcho:
+
+- **User peer**: observed from user messages. Learns preferences, goals, communication style.
+- **AI peer**: observed from assistant messages. Builds the agent's knowledge representation.
+
+Both representations are injected into the system prompt, giving Hermes awareness of both who it's talking to and what it knows.
+
+## Available tools
+
+Hermes exposes four Honcho tools to the agent:
+
+| Tool | What it does |
+|---|---|
+| `honcho_profile` | Fast peer card retrieval (no LLM). Returns curated key facts about the user. |
+| `honcho_search` | Semantic search over memory. Returns raw excerpts ranked by relevance. |
+| `honcho_context` | Dialectic Q&A powered by Honcho's LLM. Synthesizes answers from conversation history. |
+| `honcho_conclude` | Writes durable facts to Honcho when the user states preferences, corrections, or important context. |
+
+## Two memory layers
+
+When Honcho is enabled, Hermes operates with two layer memory by default (`hybrid`):
+
+**Local session history** -- the immediate transcript for the current chat, thread, or CLI session. Use it for recent turns, short-lived task context, and follow-up questions.
+
+**Honcho memory** -- the semantic, cross-session layer. Use it for user preferences, durable project facts, cross-session continuity, and synthesized peer context.
+
+## Running Honcho locally with Hermes
+
+If you want to point Hermes at a local Honcho instance instead of the hosted API:
+
+### Docker (quickest)
+
+```bash
+git clone https://github.com/plastic-labs/honcho.git
+cd honcho
+cp .env.template .env
+cp docker-compose.yml.example docker-compose.yml
+```
+
+Edit `.env`:
+
+```bash
+OPENAI_API_KEY=your-openai-api-key
+ANTHROPIC_API_KEY=your-anthropic-api-key
+DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@database:5432/honcho
+AUTH_USE_AUTH=false
+```
+
+```bash
+docker compose up -d
+curl http://localhost:8000/health
+```
+
+### Manual
+
+```bash
+git clone https://github.com/plastic-labs/honcho.git
+cd honcho
+uv sync
+cp .env.template .env
+```
+
+Edit `.env` with a local or cloud Postgres connection string and API keys, then:
+
+```bash
+uv run alembic upgrade head
+uv run fastapi dev src/main.py
+```
+
+Then update `~/.honcho/config.json` to point at your local instance:
+
+```json
+{
+ "apiKey": "not-needed-with-auth-disabled",
+ "baseUrl": "http://localhost:8000",
+ "hosts": {
+ "hermes": {
+ "workspace": "hermes",
+ "peerName": "your-name",
+ "aiPeer": "hermes",
+ "memoryMode": "hybrid",
+ "enabled": true
+ }
+ }
+}
+```
+
+The `baseUrl` field overrides the default hosted API. With `AUTH_USE_AUTH=false` on the server, the `apiKey` value is ignored but the field must still be present.
+
+See the full [self-hosting guide](/v3/contributing/self-hosting) for database options, cloud setup, and troubleshooting.
+
+## Verifying the integration
+
+Steps to test the integration via CLI and agentically by speaking to Hermes agent in natural language.
+
+### 1. Check configuration
+
+```bash
+hermes honcho status
+```
+
+### 2. Test cross-session recall
+
+In one conversation:
+
+```text
+Remember that my test phrase is velvet circuit.
+```
+
+In a fresh conversation (different thread, new CLI session):
+
+```text
+What is my test phrase?
+```
+
+If Hermes recalls "velvet circuit" after short-term context is gone, Honcho is working.
+
+### 3. Test writeback
+
+Tell Hermes a preference:
+
+```text
+Remember that I prefer terse answers.
+```
+
+Wait briefly if writes are asynchronous. Open a fresh conversation:
+
+```text
+How should you respond to me?
+```
+
+If Hermes answers with the stored preference, writeback is functioning.
+
+
+## Session strategy
+
+| Scope | When to use |
+|----------------------|---------------------------------------------------------|
+| Per-Session | A honcho session starts fresh each time a new Hermes session is created. Hermes remembers the user across sessions. |
+| Per Directory | One honcho session per project directory. Context is scoped to each directory. Coding/project memory scoped to each repository/workspace. |
+| Global (per user) | Continuity across all chats, threads, and projects. One honcho session globally for the user and Hermes agent. |
+
+
+## Next steps
+
+
+
+ Setup, configuration, CLI commands, and all config options.
+
+
+
+ Source code, installation, and full documentation.
+
+
+
+ Peers, sessions, and how reasoning works.
+
+
+
+ Full local environment setup, database options, and troubleshooting.
+
+