# 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. **Chiedi al grafo** runs semantic retrieval and highlights the source documents returned by Supermemory; **Filtra** is a separate local text filter that highlights matching nodes and dims the rest without making a server request. The left rail can hide/show namespaces, documents, excerpts or memories and lists matched source documents. A selected document can be searched with an entered topic; a selected memory can expand its branch with semantic results. **Aggiorna inventario** rereads Paperclip documents and the Supermemory documents/chunks/memories lists after uploads, deletes or reindexing. The graph supports rotate, zoom, pan, fit-to-view, full screen, focus and a Paperclip-themed details panel, all contained in the page layout.
- **Graph labels:** the overview shows namespace and document names plus a balanced sample of memory excerpts. The namespace and a single document are laid out separately so both labels can be seen. Nearby labels move into free space to reduce collisions. Zooming in progressively reveals more labels, subject to the viewport capacity. Hovering a node shows its full name. Every local-filter match in front of the camera shows its full name, including when its label anchor falls beyond the canvas edge; labels are spaced where possible and remain visible in a crowded view. The `+` control zooms into the selected node, and the mouse wheel zooms toward the cursor. Nodes and edges remain visible when their labels are hidden.
- **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, scoped agent API routes, plugin entities and company secrets. It does not modify Paperclip core. For harness hooks, the plugin calculates authorized namespaces from the selected agent grant and active Memory assignments at run time. The hook sends retrieval and candidate-save requests to authenticated plugin routes; the plugin worker resolves the master key and checks the caller's agent and current assignments server-side. No Supermemory key is returned to the harness.

## Install from Paperclip

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

Version 0.2.46 connects every node returned by the selected namespace inventory or search to that namespace, including orphaned chunks and memories whose upstream records omit document provenance. It also reports the correct installed version to Paperclip.

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 for the native MCP tools. The hook itself does not read that secret and needs no manually maintained memory variables in the agent's environment.
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). Both the page and the worker validate extension and MIME; the worker also rejects binary content mislabeled as text and invalid UTF-8.
- 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 text-extracted locally in the Paperclip worker and sent to Supermemory as linked text documents, split into smaller sections for retrieval and graph display. A second `taskType: "memory"` pass divides the text into blocks up to 40 KB and asks Supermemory to extract durable facts, entities and explicit relationships, with `dreaming: "instant"` and source/passage context. The instant pass costs one additional Supermemory operation per block; it improves the chance that a long document produces useful graph nodes without waiting for dynamic batching, but Supermemory still decides which memories and links are meaningful. `taskType: "superrag"` continues to provide source-grounded chunk retrieval. The library shows each pass's status and removes the source, retrieval chunks, and derived-memory documents together when the owner deletes the source. 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 both previous derived passes without uploading a duplicate binary.

Each text, URL, and PDF source has a retrieval/reference pass (`taskType: "superrag"`) and a separate memory-building pass (`taskType: "memory"`). The memory pass is deliberately more granular and requests immediate extraction of entity and relationship context. It does not promise one graph node per entity or guarantee that every relationship is present if Supermemory does not infer it. 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.

### Harness memory hooks

The hook uses Paperclip's automatically injected `PAPERCLIP_API_URL`, `PAPERCLIP_API_KEY`, `PAPERCLIP_AGENT_ID`, and `PAPERCLIP_RUN_ID`. It calls authenticated `/api/plugins/paperclipai.supermemory/api/runtime`, `/memory/search`, and `/memory/capture` routes. The runtime route returns only `memoryEnabled` and `candidateCaptureEnabled`; the plugin checks the active agent, explicit Owner grant, current namespace assignments, and configured Supermemory master-key secret on every request. Namespace IDs, ACL credentials, and the master key remain inside Paperclip/the plugin. Search uses company-wide and personal-agent assignments explicitly allowlisted to that agent; project-scoped search remains in the native tool path, where Paperclip supplies trusted project context.

Do not add `PAPERCLIP_MEMORY_ENABLED`, `PAPERCLIP_MEMORY_KEY_SCOPE_VERIFIED`, `PAPERCLIP_COMPANY_KEY`, `PAPERCLIP_ROLE_KEY`, `PAPERCLIP_MEMORY_READ_NAMESPACES`, `PAPERCLIP_MEMORY_WRITE_NAMESPACE`, `PAPERCLIP_MEMORY_KEY_NAME`, or `PAPERCLIP_MEMORY_SECRET_KEY` to an agent's environment. These are obsolete manual scope settings; Paperclip reserves the `PAPERCLIP_*` prefix and may reject them under strict secret validation. Remove legacy copies, especially `PAPERCLIP_MEMORY_SECRET_KEY`. The plugin computes authorization and scope server-side on each request. A new agent needs an explicit entry under **Authorized agents** and in each namespace allowlist; no per-agent environment variables are needed. Project-scoped access stays in the native tool path because the hook route does not receive a trusted project ID.

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. The ACL gateway must be **0.2.1 or newer** to proxy these Owner-only list routes. The plugin sends an empty JSON body for inventory requests because the installed Supermemory Local 0.0.9 rejects the hosted-only `include.memoryCount` option. A document can therefore produce multiple chunk nodes; a zero memory count does not mean the document was not indexed. If a gateway or Local route returns 404, Graph keeps Paperclip source documents visible and shows a diagnostic warning; verify the namespace exists and the ACL gateway exposes the Owner list routes. **Chiedi al grafo** uses namespace-scoped `searchMode: "memories"` and `searchMode: "chunks"` requests; the source list represents the relevant documents Supermemory returned, subject to its retrieval limit. **Filtra** searches the labels and excerpts already loaded in the browser and only changes visual emphasis. **Cerca nel documento** uses the selected document title as extra search context, then limits the displayed graph to that document and its linked results; Supermemory Local's current search route does not accept a document-only filter, so retrieval is still namespace-scoped. **Espandi ramo** keeps the current graph and adds semantic results connected to the selected node. Large inventories 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-static/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`.
