# Supermemory for Paperclip (self-hosted)

Paperclip plugin for Supermemory Local. It adds a native **Memory** sidebar page, an Owner-only content library and searchable memory-graph explorer, Paperclip agent/project selectors, and the existing Supermemory agent tools. It does not install or modify Paperclip core.

## What the plugin does

- **Plugin settings:** chooses Paperclip agents from the active organization list and binds one individual ACL secret to each selected agent. The user no longer copies agent UUIDs.
- **Memory page:** adds a native sidebar entry, lets an Owner assign one isolated Supermemory namespace to the whole organization, an agent, or a project, and manages text, URLs, and supported files. Organization-wide knowledge is shared only with the explicitly selected agents and can be disabled by deactivating its assignment.
- **Memory graph:** adds a full-page **Graph** submenu. The initial view loads the paginated namespace inventory from Supermemory: source documents, indexed chunks and extracted memories, linked to the Paperclip document where the IDs establish provenance. The sidebar reports Paperclip/Supermemory document, chunk, memory and loaded-node counts, and marks the view partial if a source/API limit is reached. Search adds Supermemory's relevant results and relationships. The graph supports rotate, zoom, pan, fit-to-view, keyboard-accessible pan/zoom buttons, full screen, focus and a Paperclip-themed details panel.
- **Agent search:** checks the trusted Paperclip agent, company, run and project context. It searches the agent's company/role ACL compartments and only the agent/project namespaces explicitly assigned to that identity.
- **Candidate saves:** sends candidate facts to the existing role staging compartment for human review. It does not publish them as shared memory.

The plugin uses Paperclip's standard plugin slots (`settingsPage`, `page`, `sidebar`), worker actions, plugin entities and company secrets. No Paperclip core patch is required.

## Install from Paperclip

Package: [`paperclip-plugin-supermemory-otomatik`](https://www.npmjs.com/package/paperclip-plugin-supermemory-otomatik) **0.2.22**.

1. In Paperclip, open **Settings → Plugins → Install Plugin**.
2. Enter `paperclip-plugin-supermemory-otomatik` and install it for the instance.
3. Open the plugin configuration for the target organization.
4. Select each authorized agent from **Agente Paperclip** and choose that agent's individual ACL secret.
5. Select the Paperclip secret containing the Supermemory Local master API key. This is required for the Memory page, URL/file ingestion, and explicitly assigned namespaces.
6. Save. **Memory** appears in the organization sidebar with the **Graph** submenu. The Paperclip in Italiano Chrome extension translates that label to **Grafo**.

The settings form uses the active Paperclip organization to load agents and company secrets. It persists secret references only; it never reads or renders the secret values. The configuration save endpoint requires a Paperclip instance administrator. The settings page also has **Aggiorna all’ultima versione**: only an instance admin can request an upgrade, and Paperclip pauses an update for approval if the new release adds capabilities.

## Configure secrets and URLs

Default OTOMATIK gateway endpoint:

- `https://otomatik.tail77a9ab.ts.net:18443/mcp`

Paperclip reaches the gateway over Tailscale HTTPS. Tailscale Serve forwards tailnet requests to `127.0.0.1:6768`; Supermemory Local remains private at `127.0.0.1:6767` and the plugin never contacts it directly. The plugin accepts HTTPS `*.ts.net` URLs on port 443 or 18443. It upgrades the old default `http://127.0.0.1:6768/mcp` to the OTOMATIK Tailscale URL automatically.

Create/import the gateway tokens in **Paperclip → Organization Settings → Secrets** first. There must be a distinct ACL token for each agent; the gateway must bind each token to the same Paperclip organization, agent and role. Use the individual token as that agent's secret reference.

Store the Supermemory Local **master key** in a Paperclip company secret and select it in `Secret con la chiave master Supermemory Local`. The plugin sends it only to the gateway after an Owner check, or after checking an agent's explicit assignment allowlist. The gateway uses the key server-side to call Supermemory Local; agents never receive it. Never paste it into an agent prompt, instructions file, or memory document. The worker chooses namespaces from trusted Paperclip context and the Owner's assignments; agents never supply a namespace.

## Namespaces and access rules

- Organization-wide knowledge: only the agents selected in the explicit allowlist can search the namespace. Disable the assignment to revoke plugin access while retaining its documents; create it again later to restore access to the same stored namespace.
- Agent assignment: only that Paperclip agent can search the generated namespace.
- Project assignment: searches require both the matching `projectId` from the Paperclip run context and the selected agent's explicit allowlist entry.
- Namespaces include the full Paperclip company UUID and target UUID, so two Paperclip organizations cannot accidentally map to the same generated namespace.
- Supermemory creates the namespace when the first document is added. Creating an assignment alone does not create a remote namespace.
- Disabling an assignment revokes plugin access but leaves its Supermemory documents intact.
- Memory library actions and document contents are available only to an active Paperclip organization Owner. Other users may see the sidebar route but receive no catalog or document content.
- Paperclip's current tool run context contains a project ID but no issue-level privacy grants. This plugin does not provide task-private memory. Do not treat project scopes as private-task isolation.

For project namespaces, select only agents who already have project access in Paperclip. The plugin stores that explicit agent allowlist as an additional check; review it when project membership changes.

## Memory content types

The page mirrors the Instructions layout: left content list, **Leggi / Modifica / Raw**, text editing, drag-and-drop and file upload. The workspace fits the available Paperclip window; long documents scroll inside their content panel. It supports:

- Text files: TXT, Markdown, HTML, JSON and CSV (up to 1 MB).
- Public web URLs. Supermemory Local needs its Firecrawl integration configured; URL extraction sends the URL/page to Firecrawl.
- Binary formats documented for the self-hosted Local API: PDF, PNG, JPG/JPEG, GIF and WebP. This UI caps binary uploads at 6 MiB because Paperclip's plugin action bridge accepts JSON payloads with a 10 MB limit. Supermemory's API documents a larger general file limit, but that limit cannot be reached through this Paperclip bridge implementation.

Text and URL content can be edited and reindexed. Binary file contents cannot be retrieved into the editor; delete the catalog item and upload a replacement to update one. Office, audio and video formats appear in some hosted Supermemory documentation but are not documented for the installed Supermemory Local server, so this plugin does not offer them as verified Local formats.

PDFs are also text-extracted locally in the Paperclip worker and sent to Supermemory as linked text documents, split into smaller sections for retrieval and graph display. This provides searchable content even when the Local binary PDF OCR provider cannot process a file. Existing PDFs uploaded with an earlier release can be reindexed from their document card by selecting the same PDF file; this replaces the previous extracted text without uploading a duplicate binary. Deleting a PDF removes both its binary source and all linked extracted-text documents from Supermemory.

The content is indexed as retrieval/reference material (`taskType: "superrag"`) rather than used to update a personal profile. Text, URL, file, search, update, and delete requests all pass through the ACL gateway. The plugin sends file bytes as JSON/base64 through Paperclip; the gateway converts them to multipart before forwarding them to Local. Supermemory returns an asynchronous status; `queued` means indexing has started, not finished.

The initial graph inventory reads the namespace's paginated `documents`, `chunks` and `memories` lists, then links records to the Paperclip source document using the IDs stored during ingestion. A document can therefore produce multiple chunk nodes; a zero memory count does not mean the document was not indexed. The search box uses namespace-scoped `searchMode: "memories"` and `searchMode: "chunks"` requests and overlays the results/relationships Supermemory returns. Large namespaces are capped at 1,500 loaded items for browser performance; the UI reports a partial view and preserves API totals. The worker resolves the namespace server-side with the master secret; the secret and unrestricted namespace selector never reach the browser. Graphs are never merged across assignments or organizations. See the [official search API reference](https://api.supermemory.ai/reference) and the [Supermemory SDK search guide](https://github.com/supermemoryai/skills/blob/main/supermemory/references/sdk-guide.md).

### RAG and embedding models

Supermemory Local already provides retrieval-augmented search: documents are chunked/indexed, and the search endpoint supports hybrid semantic and keyword retrieval. The installed OTOMATIK server is `0.0.9` and currently uses local `Xenova/bge-base-en-v1.5` embeddings (768 dimensions), so embedding does not require a Gemini/OpenAI key. That default is English-only; Italian keyword matching can still find exact terms, while semantic recall for Italian may be weaker.

For Italian and multilingual content, Supermemory documents local `Xenova/bge-m3` (1,024 dimensions) as a multilingual option. Do not change the model in-place on an existing data directory: vectors made by different models are not comparable. A model change requires a fresh data directory or a complete backup-and-re-ingestion migration. Keep the current model until that migration is planned and verified against the existing documents. See [Supermemory's self-hosted embedding guide](https://supermemory.ai/docs/self-hosting/embeddings).

For the Piemonte PDF currently in the project namespace, the library's “SCHEDA/Scheda informativa” search result comes from the extracted text companion of `quadro-normativo-obblighi-formativi-piemonte.pdf`, not from a deleted source document. The live inventory showed 3 Supermemory documents, 79 chunks and 0 extracted memory records; the PDF binary record was in `failed` state, while its linked text extraction was indexed and searchable. The graph now displays the binary-processing status separately from the text-extraction status.

## Tools

- `search-approved-memory`: searches company and role compartments permitted by the agent's gateway token, then any explicitly assigned agent/project namespaces.
- `submit-memory-candidate`: sends a bounded, non-sensitive candidate to the agent's staging compartment for human review.

The plugin does not read entire chat transcripts or save automatically. Agent permissions in this plugin are separate from harness hooks. Removing an agent grant here does not revoke a separate harness token or hook; revoke those credentials separately when disabling that agent completely.

## Sources and current limits

Content support was checked against [Supermemory supported content types](https://supermemory.ai/docs/concepts/content-types), [Supermemory ingestion API](https://supermemory.ai/docs/ingestion/add-memories), and the [Supermemory Local self-hosting documentation](https://github.com/supermemoryai/supermemory/blob/main/apps/docs/self-hosting/overview.mdx). The hosted API's additional Office/audio/video support is not assumed for Local.

Implementation research and evidence boundaries: [`SUPERMEMORY-CONTENT-API-RESEARCH.md`](../agent-library/memory-hooks/SUPERMEMORY-CONTENT-API-RESEARCH.md).

## Development

```sh
npm install
npm run typecheck
npm run build
```

Paperclip host compatibility: `2026.1023.0` or later. SDK: `@paperclipai/plugin-sdk@2026.1023.0`.
