# 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 an agent or project, and manages text, URLs, and supported files.
- **Memory graph:** adds a full-page **Graph** submenu. On opening or changing namespace, it searches from the titles and indexed text of the documents assigned to that namespace. Uploaded Paperclip documents appear as their own nodes; they connect to Supermemory memories only when the stored document IDs establish that link. The Paperclip-themed controls frame a colorful 3D scene with labels, hover highlighting, a details panel, orbital rotation, zoom, pan, and animated focus. Owners can search a topic or expand a memory to explore another neighborhood. This is a navigable search neighborhood, not a claim that every memory in the namespace has been enumerated.
- **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.18**.

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

- 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. This provides searchable content even when the Local binary PDF OCR provider cannot process a file. Existing PDFs uploaded before this feature can be reindexed from their document card by selecting the same PDF file; this adds the 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 graph view uses the namespace-scoped Supermemory search endpoint with `searchMode: "memories"` and `include.related: true`. On its first load, the Owner UI passes only the active assignment ID and an empty query. The worker resolves that assignment and its registered documents, then searches using their titles and saved text hints. Paperclip document nodes are linked to returned memory nodes only through the indexed Supermemory document IDs recorded at upload time. Unmatched files remain visible with their indexing status so the Owner can tell whether there is no result or no document. Manual searches use the same assignment-scoped endpoint. The worker resolves the namespace server-side with the master secret; the secret and unrestricted namespace selector never reach the browser. Related memories are returned only within the selected namespace; 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).

## 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`.
