paperclip-honcho

KO | EN

gitlite — search

#react #ai #llm #golang #machine-learning #docker #nodejs #windows #awesome #kubernetes #security #pytorch #mcp #open-source

paperclip-honcho

(★ 17)

No description available.

paperclip-honcho Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# @honcho-ai/paperclip-honcho

Add Honcho memory to Paperclip while keeping Paperclip as the system of record.

This package targets the current public/latest Paperclip host surface. It supports tools, sync, migration import, and manual prompt previews without depending 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. Open the Honcho plugin settings page in Paperclip.
2. If you are using a self-hosted or local Honcho instance, switch the deployment to `Self-hosted / local` and set the base URL.
   - Local development does not require a Honcho API key, however, is currently discouraged because of the host repository not being able to reach `localhost` reliably. This can be fixed via a tunnel to the port Honcho runs on.
3. Paste your Honcho API key into the `Honcho API Key` field.
   - Note: Paperclip's plugin secret-reference system (`ctx.secrets.resolve`) is currently disabled platform-wide pending company-scoped plugin config upstream, so this field is used as a literal value rather than a secret reference. Do not treat it as more protected than plaintext plugin config.
   - If you'd rather not put the key in Paperclip's UI, set a `HONCHO_API_KEY` environment variable (and optionally `HONCHO_API_BASE_URL`) on the plugin worker process instead.
   - On a self-hosted, single-tenant Paperclip instance running on the same machine as Hermes/Claude Code/opencode, leaving the key blank falls back to the shared `~/.honcho/config.json` those tools already use.
4. Click `Save settings`.
5. Click `Initialize Honcho memory`.

## Multi-Agent Hierarchy

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.

### Agent Observation

The current plugin exposes explicit observation settings:

- `observe_me` defaults to `true`
- `observe_others` defaults to `true`

That means agent peers can both be observed by Honcho and form representations of other peers they interact with.

### Hierarchy Context Availability

`honcho_get_hierarchy_context` is available, but delegated-work context depends on the Paperclip host providing lineage metadata. The tool degrades gracefully when that metadata is unavailable.

Prompt context is still conservative on the public-host-compatible path. The recommended starting configuration keeps `enablePromptContext: false`, and operators use manual prompt previews instead of relying on automatic injection hooks.

## How It Works

The integration breaks down into four parts:

- Identity and scope: Paperclip companies map to Honcho workspaces, issues map to sessions, and humans plus agents map to peers.
- Sync behavior: issue comments and document revisions sync into Honcho, with document content sectioned and normalized message content capped before ingestion.
- Operator controls: the plugin settings page provides setup, status, and initialization flows, plus an issue-level `Memory` tab.
- Agent tools: Paperclip agents get Honcho retrieval and peer-chat tools.

## Operator Actions

The current operator flow is intentionally narrow:

| Action | What it does |
| --- | --- |
| `Save settings` | Persists the current plugin configuration after validation. |
| `Initialize Honcho memory` | Validates config, tests the Honcho connection, creates core mappings, imports baseline issue memory, and verifies the initialization path. |
| `Resync this issue` | Replays sync for the current issue from the issue `Memory` tab. |

## Configuration Defaults

| Setting | Default | Use when |
| --- | --- | --- |
| `honchoApiKey` | — | Required for cloud-based setups. Leave it unset for local development. |
| `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:

- `honcho_get_issue_context`
- `honcho_search_memory`
- `honcho_search_messages`
- `honcho_search_conclusions`
- `honcho_get_workspace_context`
- `honcho_get_session`
- `honcho_get_agent_context`
- `honcho_get_hierarchy_context`
- `honcho_ask_peer`

## Development

```bash
pnpm install
pnpm build
pnpm test
pnpm typecheck
```

This repo keeps `dist/` checked in so local path installs and tarball validation work without extra publish-time build assumptions.

paperclip-honcho

paperclip-honcho Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

paperclip-honcho

paperclip-honcho Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README