From 58f9abba98c080a540ee168fe7a85b7d35652c0c Mon Sep 17 00:00:00 2001 From: adavyas <121313528+adavyas@users.noreply.github.com> Date: Fri, 10 Apr 2026 11:35:14 -0700 Subject: [PATCH] docs: add paperclip integration docs (#549) * Simplify Paperclip integration instructions Clarified instructions for local Honcho setup and removed unnecessary details. * Update docs.json * Update links in Paperclip integration guide * Revise memory initialization instructions in Paperclip guide Updated instructions for initializing memory and removed optional checks section. --- docs/docs.json | 3 +- docs/v3/guides/integrations/paperclip.mdx | 135 ++++++++++++++++++++++ docs/v3/guides/overview.mdx | 3 + 3 files changed, 140 insertions(+), 1 deletion(-) create mode 100644 docs/v3/guides/integrations/paperclip.mdx 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