Skip to content

feat(paperclip): replace library with Paperclip plugin (v0.2.0) #934

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nicoloboschi merged 3 commits into from
Apr 15, 2026
Merged

feat(paperclip): replace library with Paperclip plugin (v0.2.0) #934

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3960764
feat(paperclip): replace library with Paperclip plugin (v0.2.0)
benfrank241 Apr 8, 2026
4d5a559
Merge branch 'main' into feat/paperclip-plugin-replace
benfrank241 Apr 15, 2026
3b4c73c
chore(paperclip): apply prettier formatting and update skills changelog
benfrank241 Apr 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
176 changes: 50 additions & 126 deletions hindsight-docs/docs-integrations/paperclip.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,163 +1,87 @@
---
sidebar_position: 11
title: "Paperclip Persistent Memory with Hindsight | Integration Guide"
description: "Add long-term memory to Paperclip agents with Hindsight. Retain, recall, and reflect memories across sessions using the Paperclip integration."
description: "Add long-term memory to all Paperclip agents with Hindsight. Install once as a plugin — every agent gets automatic recall before runs and retain after runs."
---

# Paperclip

Persistent memory for [Paperclip AI](https://github.com/paperclipai/paperclip) agents using [Hindsight](https://hindsight.vectorize.io).

Paperclip agents start every heartbeat cold — no memory of prior sessions, decisions, or patterns. The `@vectorize-io/hindsight-paperclip` package gives them long-term memory that persists across heartbeats and sessions.
Install the `@vectorize-io/hindsight-paperclip` plugin once. Every agent in your Paperclip instance automatically gets long-term memory that persists across runs, companies, and restarts — no code changes required.

## Quick Start
## Installation

```bash
npm install @vectorize-io/hindsight-paperclip
pnpm paperclipai plugin install @vectorize-io/hindsight-paperclip
```

```typescript
import { recall, retain, loadConfig } from '@vectorize-io/hindsight-paperclip'

const config = loadConfig() // reads HINDSIGHT_API_URL, HINDSIGHT_API_TOKEN

// Before the heartbeat — inject context from prior sessions
const memories = await recall({
companyId,
agentId,
query: `${task.title}\n${task.description}`,
}, config)

if (memories) {
systemPrompt = `Past context:\n${memories}\n\n${systemPrompt}`
}

// After the heartbeat — store what the agent did
await retain({
companyId,
agentId,
content: agentOutput,
documentId: runId,
}, config)
```
Then configure in **Settings → Plugins → Hindsight Memory**.

Get an API key at [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup).
## Prerequisites

## How It Works
Either:

```bash
# Self-hosted
pip install hindsight-all
export HINDSIGHT_API_LLM_API_KEY=your-openai-key
hindsight-api
```
Paperclip Heartbeat
│
▼
recall() ← Query Hindsight for prior context
│
▼
Agent executes ← Prompt enriched with memories
│
▼
retain() ← Store output for future heartbeats
```

Memory is isolated per company and agent by default (`paperclip::{companyId}::{agentId}`), matching Paperclip's multi-tenant model.

## HTTP Adapter Integration

For agents running as HTTP webhook servers, use the Express middleware:
Or [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) — no self-hosting required.

```typescript
import express from 'express'
import { createMemoryMiddleware, loadConfig } from '@vectorize-io/hindsight-paperclip'
import type { HindsightRequest } from '@vectorize-io/hindsight-paperclip'

const app = express()
app.use(express.json())
app.use(createMemoryMiddleware(loadConfig()))

app.post('/heartbeat', async (req, res) => {
const { memories } = (req as HindsightRequest).hindsight
const { context } = req.body

const prompt = memories
? `Past context:\n${memories}\n\nCurrent task: ${context.taskDescription}`
: `Task: ${context.taskDescription}`
## How It Works

const output = await runYourAgent(prompt)
res.json({ output }) // output is auto-retained by middleware
})
```
agent.run.started
└─ recall(issueTitle + description)
└─ cached in plugin state for this run

The middleware reads `agentId`, `companyId`, `runId`, and `context.taskDescription` from Paperclip's HTTP adapter request body, then auto-retains the agent's `output` field after each response.

## Process Adapter Integration
agent running…
├─ hindsight_recall(query) → returns cached context or live recall
└─ hindsight_retain(content) → stores immediately

For agents running as scripts via Paperclip's Process adapter:

```typescript
import { recall, retain, loadConfig } from '@vectorize-io/hindsight-paperclip'

const config = loadConfig()
const { PAPERCLIP_AGENT_ID, PAPERCLIP_COMPANY_ID, PAPERCLIP_RUN_ID } = process.env

const memories = await recall({
agentId: PAPERCLIP_AGENT_ID!,
companyId: PAPERCLIP_COMPANY_ID!,
query: process.env.TASK_DESCRIPTION ?? '',
}, config)

if (memories) {
console.log(`[Memory Context]\n${memories}`)
}

// ... agent executes ...

await retain({
agentId: PAPERCLIP_AGENT_ID!,
companyId: PAPERCLIP_COMPANY_ID!,
content: agentOutput,
documentId: PAPERCLIP_RUN_ID!,
}, config)
agent.run.finished
└─ retain(output) → stored with runId as document_id
```

## Bank ID Isolation
Memory is keyed to `companyId` + `agentId` — never to the run ID — so it accumulates across every run.

By default, each company+agent pair gets its own memory bank:

| Setting | Bank ID format |
|---|---|
| Default | `paperclip::{companyId}::{agentId}` |
| Company-only | `paperclip::{companyId}` |
| Agent-only | `paperclip::{agentId}` |
| Custom prefix | `{prefix}::{companyId}::{agentId}` |
## Configuration

```typescript
// Shared memory across all agents in a company
loadConfig({ bankGranularity: ['company'] })
| Field | Default | Description |
|-------|---------|-------------|
| `hindsightApiUrl` | `http://localhost:8888` | Hindsight server URL |
| `hindsightApiKeyRef` | — | Paperclip secret name holding Hindsight Cloud API key |
| `bankGranularity` | `["company", "agent"]` | Memory isolation: per company+agent, per company, or per agent |
| `recallBudget` | `mid` | `low` = fastest, `mid` = balanced, `high` = most thorough |
| `autoRetain` | `true` | Automatically retain run output after every run |

// Agent's global memory across all companies
loadConfig({ bankGranularity: ['agent'] })
## Bank ID Format

// Custom prefix
loadConfig({ bankIdPrefix: 'myapp' })
```
paperclip::{companyId}::{agentId} ← default (company + agent granularity)
paperclip::{companyId} ← company granularity (shared across agents)
paperclip::{agentId} ← agent granularity (agent memory across companies)
```

## Configuration
## Agent Tools

Agents can call these tools directly during a run:

| Option | Env Variable | Default | Description |
|---|---|---|---|
| `hindsightApiUrl` | `HINDSIGHT_API_URL` | Required | Hindsight server URL |
| `hindsightApiToken` | `HINDSIGHT_API_TOKEN` | — | API token for Hindsight Cloud |
| `bankGranularity` | — | `['company', 'agent']` | Which IDs to include in the bank ID |
| `bankIdPrefix` | — | `'paperclip'` | Prefix for bank IDs |
| `recallBudget` | — | `'mid'` | Search depth: `low`, `mid`, or `high` |
| `recallMaxTokens` | — | `1024` | Max tokens in recalled memory block |
| `retainContext` | — | `'paperclip'` | Provenance label stored with memories |
| `timeoutMs` | — | `15000` | Request timeout in milliseconds |
**`hindsight_recall(query)`** — search memory for relevant context. Called automatically at run start; agents can also call it mid-run for targeted queries.

## Skill File
**`hindsight_retain(content)`** — store a fact or decision immediately, without waiting for run end.

A markdown skill file is included at `src/skills/hindsight.md`. Inject it into your agent's system prompt to give the agent direct access to Hindsight's REST API via `curl` for mid-task recall and retention.
## Adapter Compatibility

## Requirements
Works with all Paperclip adapter types via the event system:

- Node.js 20+ (uses native `fetch`, no external HTTP dependencies)
- Hindsight server (self-hosted or [Hindsight Cloud](https://hindsight.vectorize.io))
| Adapter | Supported |
|---------|-----------|
| Claude | ✓ |
| Codex | ✓ |
| Cursor | ✓ |
| HTTP | ✓ |
| Process | ✓ |
15 changes: 15 additions & 0 deletions hindsight-docs/src/pages/changelog/integrations/paperclip.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,21 @@ For the source code, see [`hindsight-integrations/paperclip`](https://github.com

← [Back to main changelog](/changelog)

## [0.2.0](https://github.com/vectorize-io/hindsight/tree/integrations/paperclip/v0.2.0)

**Breaking Changes**

- Rewritten as a proper Paperclip plugin (installed via `pnpm paperclipai plugin install`). No code changes required — memory hooks run automatically via the event system.
- Works with all adapter types (Claude, Codex, Cursor, HTTP, Process). Previously required manual `recall()`/`retain()` calls and only supported HTTP adapter agents.

**Features**

- `agent.run.started` hook: auto-recalls context keyed to issue title + description
- `agent.run.finished` hook: auto-retains agent output with `runId` as document ID
- `hindsight_recall` and `hindsight_retain` agent tools for mid-run memory access
- `onValidateConfig`: live connectivity check when operator saves settings
- Configurable bank granularity (company+agent, company-only, agent-only)

## [0.1.2](https://github.com/vectorize-io/hindsight/tree/integrations/paperclip/v0.1.2)

**Improvements**
Expand Down
Loading