137 lines
7.0 KiB
Plaintext
137 lines
7.0 KiB
Plaintext
---
|
|
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 Mapping
|
|
|
|
The integration breaks down into four parts:
|
|
|
|
- **Identity and mapping** - 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="Directional Representations" icon="messages" href="../../documentation/features/advanced/directional-representations">
|
|
Review how `observe_me` and `observe_others` change what peers can model.
|
|
</Card>
|
|
</CardGroup>
|