Skip to main content
Honcho for Paperclip 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:
ActionWhat it does
Validate configValidates the current plugin configuration before any sync or import work runs.
Test connectionResolves the API key secret, checks the Honcho connection, and returns the mapped workspace ID.
Initialize memory for this companyConnects Honcho, creates core mappings, imports baseline issue memory, and verifies manual prompt previews.
Rescan migration sourcesScans issue comments and issue documents and writes a fresh import preview.
Import historyImports the approved historical preview into Honcho with idempotent ledger checks.
Preview prompt contextBuilds a manual prompt-context preview for a company or issue without relying on automatic host hooks.
Repair mappingsRecreates missing workspace, peer, and session mappings for the current company.
Resync this issueReplays sync for the current issue from the issue Memory tab.

​
Configuration Defaults And Overrides

​
Default Behavior

SettingDefaultUse when
honchoApiKey—Required. Points the plugin at the Paperclip secret containing your Honcho API key.
honchoApiBaseUrlhttps://api.honcho.devOverride this for self-hosted or non-default Honcho deployments.
workspacePrefixpaperclipChange this if you want a different workspace namespace.
syncIssueCommentstrueTurn this off if you do not want comment history imported into Honcho.
syncIssueDocumentstrueTurn this off if you do not want issue document revisions imported.
enablePeerChattrueRequired for the peer chat tool surface.
enablePromptContextfalseKeep this off on the public-host-compatible path and use manual prompt previews instead.
observe_metrueControls whether agent peers are observed by Honcho.
observe_otherstrueControls 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:
ToolDescription
honcho_get_issue_contextRetrieve compact Honcho context for the current issue session.
honcho_search_memorySearch Honcho memory within the current workspace, narrowing to the current issue by default.
honcho_search_messagesSearch raw Honcho messages.
honcho_search_conclusionsSearch high-signal summarized Honcho memory.
honcho_get_workspace_contextRetrieve broad workspace recall from Honcho.
honcho_get_sessionRetrieve issue session context from Honcho.
honcho_get_agent_contextRetrieve peer context for a specific agent.
honcho_get_hierarchy_contextRetrieve delegated-work context when the host provides lineage metadata.
honcho_ask_peerQuery Honcho peer chat for a target peer. Requires peer chat to be enabled in plugin config.

​
Next Steps

Paperclip-Honcho Repository

Open the repository for source and setup details.

Honcho Architecture

Review how workspaces, peers, and sessions fit together.

Representation Scopes

Review how observe_me and observe_others change what peers can model.