157 lines
8.3 KiB
Plaintext
157 lines
8.3 KiB
Plaintext
---
|
|
title: "Paperclip"
|
|
icon: "paperclip"
|
|
description: "Add Honcho memory to Paperclip"
|
|
sidebarTitle: "Paperclip"
|
|
---
|
|
|
|
[Honcho for Paperclip](https://github.com/plastic-labs/paperclip-honcho) 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.
|
|
|
|
## Quick Setup
|
|
|
|
### Minimal Path
|
|
|
|
1. Create a Paperclip secret containing the Honcho API key.
|
|
- For self-hosted or local Honcho, use whatever credential your local startup expects.
|
|
- If your local dev setup does not require an API key, you can leave `honchoApiKeySecretRef` unset.
|
|
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 self-hosted or local Honcho instance, switch the deployment to `Self-hosted / local` and set `honchoApiBaseUrl`.
|
|
5. Set `honchoApiKeySecretRef`.
|
|
6. Save the settings.
|
|
7. Run `Initialize memory for this company`.
|
|
|
|
### Optional Checks And Follow-Up Actions
|
|
|
|
8. Optionally run:
|
|
- `Validate config`
|
|
- `Test connection`
|
|
- `Preview prompt context`
|
|
- `Rescan migration sources`
|
|
- `Import history`
|
|
- `Repair mappings`
|
|
|
|
`honchoApiKeySecretRef` is the only field required for the standard setup path if you are using cloud-based Honcho. `honchoApiBaseUrl` is the only field required if you are running Honcho locally. The other settings already have defaults.
|
|
|
|
<Note>
|
|
If you use a self-hosted or 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:
|
|
|
|
- `observeMe` defaults to `true`
|
|
- `observeOthers` defaults to `true`
|
|
|
|
In practice, that means agent peers can both be observed by Honcho and form representations of other peers they interact with. That is the main multi-agent improvement in the current Paperclip plugin compared with the older single-toggle model.
|
|
|
|
### When Hierarchy Context Is Available
|
|
|
|
Hierarchy is still partly host-dependent. `honcho_get_hierarchy_context` is available, but it only returns delegated-work context when the Paperclip host provides lineage metadata. The tool degrades gracefully when that metadata is unavailable.
|
|
|
|
Prompt context is still more conservative than in integrations like OpenClaw. The recommended starting configuration keeps `enablePromptContext: false`, and operators use `Preview prompt context` for manual prompt probes instead of relying on automatic injection hooks.
|
|
|
|
## 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
|
|
|
|
### Required Setting
|
|
|
|
If you are not using Honcho Cloud, set `honchoApiBaseUrl`. Set `honchoApiKeySecretRef` if you are using Honcho Cloud. Default `honchoApiBaseUrl` is already set to api.honcho.dev. Everything else can be left at the defaults until you have a reason to change it.
|
|
|
|
### Default Behavior
|
|
|
|
| Setting | Default | Use when |
|
|
| --- | --- | --- |
|
|
| `honchoApiKeySecretRef` | — | Required for cloud-based setups. 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. |
|
|
| `observeMe` | `true` | Controls whether agent peers are observed by Honcho. |
|
|
| `observeOthers` | `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 `observeMe` and `observeOthers` change what peers can model.
|
|
</Card>
|
|
</CardGroup>
|