Paperclip
Persistent memory for Paperclip AI agents using Hindsight.
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.
Installation
pnpm paperclipai plugin install @vectorize-io/hindsight-paperclipThen configure in Settings → Plugins → Hindsight Memory.
Prerequisites
Requires Paperclip 2026.720.0 or newer. Upgrading from an older plugin version? Open the plugin settings and pick the API key secret again: older versions saved the secret's name, and Paperclip now accepts only a reference chosen with the secret picker.
💡 Hindsight Cloud (recommended)
Sign up free — no infrastructure to run. Skip straight to Configuration below. Self-hosting alternative — run Hindsight locally:
pip install hindsight-all
export HINDSIGHT_API_LLM_API_KEY=your-openai-key
hindsight-apiHow It Works
agent.run.started
└─ fetch issue via ctx.issues.get
└─ recall(issueTitle + description) → cached in plugin state for this run
agent running…
├─ hindsight_recall(query) → cached context if query matches run start, otherwise live recall
└─ hindsight_retain(content) → stores immediately
issue.comment.created
└─ retain(full comment body via ctx.issues.listComments)
└─ bank attribution: agent comment author when present; otherwise issue assignee
agent.run.finished
└─ no-op (subscription kept for future use when payload carries output)The bundled plugin manifest declares the issues.read and issue.comments.read capabilities needed by the new SDK calls, so Paperclip may prompt for these on first install or upgrade.
Memory is keyed to companyId + agentId — never to the run ID — so it accumulates across every run.
Configuration
| Field | Default | Description |
|---|---|---|
hindsightApiUrl |
https://api.hindsight.vectorize.io |
Hindsight server URL (Cloud default; use http://localhost:8888 for self-hosted) |
hindsightApiKeyRef |
— | Paperclip secret holding your Hindsight Cloud API key, chosen with the secret picker. Leave empty for self-hosted |
dynamicBankId |
true |
When true, bank ID is derived from bankGranularity. Set false and provide bankId to share one static memory bank across agents |
bankId |
— | Static bank ID used when dynamicBankId is false. All agents sharing this value read/write the same memory bank |
bankGranularity |
["company", "agent"] |
Memory isolation when dynamicBankId is true: per company+agent, per company, or per agent. Add "user" for per-user memory isolation (useful for GDPR compliance) |
recallBudget |
mid |
low = fastest, mid = balanced, high = most thorough |
requestTimeoutMs |
15000 |
Timeout for each request to Hindsight. Raise it for self-hosted instances where recall on long issue descriptions is slower |
autoRetain |
true |
Automatically retain run output after every run |
Bank ID Format
paperclip::{companyId}::{agentId} ← default (company + agent granularity)
paperclip::{companyId} ← company granularity (shared across agents)
paperclip::{agentId} ← agent granularity (agent memory across companies)
paperclip::{companyId}::{agentId}::user::{userId} ← user granularity (per-user isolation, GDPR-friendly)
{bankId} ← static shared bank (dynamicBankId = false)Agent Tools
Agents can call these tools directly during a run:
hindsight_recall(query) — search memory for relevant context. Called automatically at run start; agents can also call it mid-run for targeted queries. The run-start result is reused only when the agent asks the same query; any other query triggers a live recall.
hindsight_retain(content) — store a fact or decision immediately, without waiting for run end.
Adapter Compatibility
Works with all Paperclip adapter types via the event system:
| Adapter | Supported |
|---|---|
| Claude | ✓ |
| Codex | ✓ |
| Cursor | ✓ |
| HTTP | ✓ |
| Process | ✓ |