diff --git a/docs/docs.json b/docs/docs.json
index a81217cc..0b357367 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -108,7 +108,8 @@
"v3/guides/integrations/n8n",
"v3/guides/integrations/openclaw",
"v3/guides/integrations/hermes",
- "v3/guides/integrations/zo-computer"
+ "v3/guides/integrations/zo-computer",
+ "v3/guides/integrations/paperclip"
]
},
{
diff --git a/docs/v3/guides/integrations/paperclip.mdx b/docs/v3/guides/integrations/paperclip.mdx
new file mode 100644
index 00000000..072383a0
--- /dev/null
+++ b/docs/v3/guides/integrations/paperclip.mdx
@@ -0,0 +1,135 @@
+---
+title: "Paperclip"
+icon: "paperclip"
+description: "Add Honcho memory to Paperclip"
+sidebarTitle: "Paperclip"
+---
+
+Honcho for [Paperclip](https://paperclip.ing) adds persistent Honcho memory to Paperclip while keeping Paperclip as the system of record.
+
+
+This page covers the current public-host-compatible Paperclip plugin. It supports tools, sync, migration import, and manual prompt previews. It does not depend on automatic prompt-context injection hooks, run transcript import, or legacy workspace file import.
+
+
+## Install the Plugin
+
+1. In Paperclip, open `Instance Settings` -> `Plugins`.
+2. Click `Install Plugin`.
+3. Enter `@honcho-ai/paperclip-honcho`.
+4. Complete the install from the Paperclip UI.
+
+## Quick Setup
+
+### Minimal Path
+
+1. Create a Paperclip secret containing the Honcho API key.
+ - For a local Honcho, use whatever credential your local startup expects & `honchoApiKey` is not needed.
+2. Open the Honcho plugin settings page in Paperclip.
+3. If you are using Honcho Cloud, leave the deployment on the default cloud setting.
+4. If you are using a local Honcho instance, switch the deployment to `Self-hosted / local` and set `honchoApiBaseUrl`.
+5. Set `honchoApiKey`.
+6. Save the settings.
+7. Run `Initialize Honcho memory`.
+
+`honchoApiKey` is the only field required for the standard setup path. The other settings already have defaults.
+
+
+If you use a local Honcho deployment, `honchoApiBaseUrl` must be reachable from the Paperclip host runtime. If Paperclip is running in Docker, `localhost` may not point at your machine.
+
+
+## Multi-Agent Hierarchy
+
+### What Maps Where
+
+Paperclip memory is organized around company, issue, and agent boundaries:
+
+- **Company -> workspace**: each Paperclip company maps to one Honcho workspace.
+- **Issue -> session**: each Paperclip issue maps to one Honcho session inside that workspace.
+- **Humans and agents -> peers**: human actors and Paperclip agents map to Honcho peers.
+
+This gives the plugin a natural hierarchy: company-level memory lives at the workspace level, issue-level memory lives at the session level, and people or agents are modeled as peers that participate across those scopes.
+
+### How Agent Observation Works
+
+The current plugin gives agent peers explicit observation settings:
+
+- `observe_me` defaults to `true`
+- `observe_others` defaults to `true`
+
+In practice, that means agent peers can both be observed by Honcho and form representations of other peers they interact with.
+
+## How It Works
+
+### Identity And Scope
+
+The integration breaks down into four parts:
+
+- **Identity and scope** - each Paperclip company maps to a Honcho workspace, agents and human actors map to peers, and issues map to sessions.
+- **What gets copied into Honcho** - issue comments and document revisions sync into Honcho, with document content sectioned and normalized message content capped before ingestion.
+- **What operators get** - operators get a plugin settings page, migration preview/status data, repair tools, and an issue-level `Memory` tab.
+- **What agents get** - agents get Honcho retrieval and peer-chat tools inside Paperclip.
+
+## Operator Actions
+
+The settings page exposes the main operator workflow directly:
+
+| Action | What it does |
+| --- | --- |
+| `Validate config` | Validates the current plugin configuration before any sync or import work runs. |
+| `Test connection` | Resolves the API key secret, checks the Honcho connection, and returns the mapped workspace ID. |
+| `Initialize memory for this company` | Connects Honcho, creates core mappings, imports baseline issue memory, and verifies manual prompt previews. |
+| `Rescan migration sources` | Scans issue comments and issue documents and writes a fresh import preview. |
+| `Import history` | Imports the approved historical preview into Honcho with idempotent ledger checks. |
+| `Preview prompt context` | Builds a manual prompt-context preview for a company or issue without relying on automatic host hooks. |
+| `Repair mappings` | Recreates missing workspace, peer, and session mappings for the current company. |
+| `Resync this issue` | Replays sync for the current issue from the issue Memory tab. |
+
+## Configuration Defaults And Overrides
+
+### Default Behavior
+
+| Setting | Default | Use when |
+| --- | --- | --- |
+| `honchoApiKey` | — | Required. Points the plugin at the Paperclip secret containing your Honcho API key. |
+| `honchoApiBaseUrl` | `https://api.honcho.dev` | Override this for self-hosted or non-default Honcho deployments. |
+| `workspacePrefix` | `paperclip` | Change this if you want a different workspace namespace. |
+| `syncIssueComments` | `true` | Turn this off if you do not want comment history imported into Honcho. |
+| `syncIssueDocuments` | `true` | Turn this off if you do not want issue document revisions imported. |
+| `enablePeerChat` | `true` | Required for the peer chat tool surface. |
+| `enablePromptContext` | `false` | Keep this off on the public-host-compatible path and use manual prompt previews instead. |
+| `observe_me` | `true` | Controls whether agent peers are observed by Honcho. |
+| `observe_others` | `true` | Controls whether agent peers form representations of other peers they interact with. |
+
+The plugin also accepts additional advanced fields in the settings page, including noise-pattern and metadata-strip controls. Most setups can ignore those and start with the defaults above.
+
+## Agent Tools
+
+The plugin registers the following Honcho tools for Paperclip agents:
+
+| Tool | Description |
+| --- | --- |
+| `honcho_get_issue_context` | Retrieve compact Honcho context for the current issue session. |
+| `honcho_search_memory` | Search Honcho memory within the current workspace, narrowing to the current issue by default. |
+| `honcho_search_messages` | Search raw Honcho messages. |
+| `honcho_search_conclusions` | Search high-signal summarized Honcho memory. |
+| `honcho_get_workspace_context` | Retrieve broad workspace recall from Honcho. |
+| `honcho_get_session` | Retrieve issue session context from Honcho. |
+| `honcho_get_agent_context` | Retrieve peer context for a specific agent. |
+| `honcho_get_hierarchy_context` | Retrieve delegated-work context when the host provides lineage metadata. |
+| `honcho_ask_peer` | Query Honcho peer chat for a target peer. Requires peer chat to be enabled in plugin config. |
+
+## Next Steps
+
+
+
+ Open the repository for source and setup details.
+
+
+
+ Review how workspaces, peers, and sessions fit together.
+
+
+
+ Review how `observe_me` and `observe_others` change what peers can model.
+
+
diff --git a/docs/v3/guides/overview.mdx b/docs/v3/guides/overview.mdx
index 71f31aef..d3ca8c32 100644
--- a/docs/v3/guides/overview.mdx
+++ b/docs/v3/guides/overview.mdx
@@ -44,6 +44,9 @@ Connect external platforms to Honcho:
Ingest meeting transcripts with speaker turns and participant data
+
+ Add Honcho memory to Paperclip companies, agents, issues, and documents
+
Build an embodied voice robot with long-term memory