---
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.

<Note>
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.
</Note>

## 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.
   - Plugin download does not currently work on Windows because of a Paperclip host-side issue.

## 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.

<Note>
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.
</Note>

## 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, including a per-issue migration mapping preview, 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

<CardGroup cols={2}>
  <Card title="Paperclip-Honcho Repository" icon="github" href="https://github.com/plastic-labs/paperclip-honcho">
    Open the repository for source and setup details.
  </Card>

  <Card title="Honcho Architecture" icon="sitemap" href="../../documentation/core-concepts/architecture">
    Review how workspaces, peers, and sessions fit together.
  </Card>

  <Card title="Representation Scopes" icon="messages" href="../../documentation/features/advanced/representation-scopes">
    Review how `observe_me` and `observe_others` change what peers can model.
  </Card>
</CardGroup>
