paperclip-plugin-supermemory-otomatik 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Otomatik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# Supermemory for Paperclip (self-hosted)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Paperclip plugin for Supermemory Local. It adds a native **Memory** sidebar page, an Owner-only content library, 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.
+- **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.0**.
+
+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. The new **Memory** entry appears in the organization sidebar.
+
+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.
+
+## Configure secrets and URLs
+
+Default OTOMATIK endpoints:
+
+- ACL gateway: `http://127.0.0.1:6768/mcp`
+- Supermemory Local API: `http://127.0.0.1:6767`
+
+Keep both services on a private network. The plugin rejects public hosts and nonstandard ports. If the Paperclip plugin worker runs in a separate container, set the private service address reachable from that container.
+
+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 that secret in `Owner-only Supermemory Local API key`. The plugin resolves this value only inside Owner-checked management actions and after checking an agent's allowlist before a memory search. Never paste it into an agent prompt, instructions file, or memory document. The worker is a trusted enforcement boundary: it holds the broader key but chooses the namespace 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. 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.
+
+The content is indexed as retrieval/reference material (`taskType: "superrag"`) rather than used to update a personal profile. Supermemory returns an asynchronous status; `queued` means indexing has started, not finished.
+
+## 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`.

package/dist/manifest.js

@@ -0,0 +1,145 @@
+// src/manifest.ts
+var PLUGIN_ID = "paperclipai.supermemory";
+var SEARCH_TOOL = "search-approved-memory";
+var SAVE_TOOL = "submit-memory-candidate";
+var MEMORY_SETTINGS_PAGE = "supermemory-settings";
+var MEMORY_PAGE = "supermemory-memory";
+var MEMORY_SIDEBAR = "supermemory-sidebar";
+var MEMORY_ROUTE = "memory";
+var manifest = {
+  id: PLUGIN_ID,
+  apiVersion: 1,
+  version: "0.2.0",
+  minimumHostVersion: "2026.1023.0",
+  displayName: "Supermemory (self-hosted)",
+  description: "Memory tools and an Owner-managed memory library for self-hosted Supermemory, with company-, agent-, and project-scoped access.",
+  author: "Otomatik",
+  categories: ["connector", "automation", "ui"],
+  capabilities: [
+    "agent.tools.register",
+    "agents.read",
+    "projects.read",
+    "access.members.read",
+    "http.outbound",
+    "instance.settings.register",
+    "secrets.read-ref",
+    "ui.page.register",
+    "ui.sidebar.register"
+  ],
+  entrypoints: {
+    worker: "./dist/worker.js",
+    ui: "./dist/ui"
+  },
+  instanceConfigSchema: {
+    type: "object",
+    properties: {
+      gatewayUrl: {
+        type: "string",
+        title: "Self-hosted ACL gateway URL",
+        description: "Private Paperclip ACL gateway used by legacy company/team memory and reviewed memory candidates. Defaults to the OTOMATIK loopback endpoint.",
+        default: "http://127.0.0.1:6768/mcp"
+      },
+      localApiUrl: {
+        type: "string",
+        title: "Supermemory Local API URL",
+        description: "Private Supermemory Local API used by Owner-managed namespace content and explicit agent/project memory. Defaults to the OTOMATIK loopback endpoint.",
+        default: "http://127.0.0.1:6767"
+      },
+      adminApiKeyRef: {
+        type: "string",
+        format: "secret-ref",
+        title: "Owner-only Supermemory Local API key",
+        description: "Paperclip secret containing the Supermemory Local master API key. The plugin resolves it only for Owner-checked management actions and authorized agent searches; never paste it into instructions or agent prompts."
+      },
+      agentGrants: {
+        type: "array",
+        title: "Authorized agents",
+        description: "Only listed Paperclip agents can use the memory tools. Each one uses its own ACL gateway token secret, already bound to the same agent, company, and role.",
+        items: {
+          type: "object",
+          title: "Agent grant",
+          required: ["agentId", "tokenRef"],
+          properties: {
+            agentId: {
+              type: "string",
+              title: "Paperclip agent",
+              minLength: 1
+            },
+            tokenRef: {
+              type: "string",
+              format: "secret-ref",
+              title: "This agent's ACL token secret",
+              description: "Select the Paperclip company secret containing only this agent's Supermemory ACL token."
+            }
+          }
+        },
+        default: []
+      }
+    }
+  },
+  tools: [
+    {
+      name: SEARCH_TOOL,
+      displayName: "Search approved Supermemory",
+      description: "Search this agent's explicitly authorized company/team compartments and any assigned agent/project namespaces. Project memory is available only when the Paperclip run is in that project and the agent is on its explicit allowlist. Do not search for credentials or personal records.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", minLength: 1, maxLength: 300 },
+          searchMode: { type: "string", enum: ["hybrid", "memories", "chunks"], default: "hybrid" },
+          limit: { type: "integer", minimum: 1, maximum: 5, default: 3 }
+        },
+        required: ["query"],
+        additionalProperties: false
+      }
+    },
+    {
+      name: SAVE_TOOL,
+      displayName: "Submit a Supermemory candidate",
+      description: "Submit one durable, non-sensitive fact or decision to this agent's role staging compartment for human review. This does not publish it to shared approved memory. Never submit credentials, personal data, customer cases, legal/health/workplace records, or full chat transcripts.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          content: { type: "string", minLength: 20, maxLength: 1200 }
+        },
+        required: ["content"],
+        additionalProperties: false
+      }
+    }
+  ],
+  ui: {
+    slots: [
+      {
+        type: "settingsPage",
+        id: MEMORY_SETTINGS_PAGE,
+        displayName: "Supermemory settings",
+        exportName: "SupermemorySettingsPage"
+      },
+      {
+        type: "page",
+        id: MEMORY_PAGE,
+        displayName: "Memory",
+        exportName: "MemoryPage",
+        routePath: MEMORY_ROUTE
+      },
+      {
+        type: "sidebar",
+        id: MEMORY_SIDEBAR,
+        displayName: "Memory",
+        exportName: "MemorySidebarLink"
+      }
+    ]
+  }
+};
+var manifest_default = manifest;
+export {
+  MEMORY_PAGE,
+  MEMORY_ROUTE,
+  MEMORY_SETTINGS_PAGE,
+  MEMORY_SIDEBAR,
+  PLUGIN_ID,
+  SAVE_TOOL,
+  SEARCH_TOOL,
+  manifest_default as default
+};
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/manifest.ts"],
+  "sourcesContent": ["import type { PaperclipPluginManifestV1 } from \"@paperclipai/plugin-sdk\";\n\nexport const PLUGIN_ID = \"paperclipai.supermemory\";\nexport const SEARCH_TOOL = \"search-approved-memory\";\nexport const SAVE_TOOL = \"submit-memory-candidate\";\nexport const MEMORY_SETTINGS_PAGE = \"supermemory-settings\";\nexport const MEMORY_PAGE = \"supermemory-memory\";\nexport const MEMORY_SIDEBAR = \"supermemory-sidebar\";\nexport const MEMORY_ROUTE = \"memory\";\n\nconst manifest: PaperclipPluginManifestV1 = {\n  id: PLUGIN_ID,\n  apiVersion: 1,\n  version: \"0.2.0\",\n  minimumHostVersion: \"2026.1023.0\",\n  displayName: \"Supermemory (self-hosted)\",\n  description: \"Memory tools and an Owner-managed memory library for self-hosted Supermemory, with company-, agent-, and project-scoped access.\",\n  author: \"Otomatik\",\n  categories: [\"connector\", \"automation\", \"ui\"],\n  capabilities: [\n    \"agent.tools.register\",\n    \"agents.read\",\n    \"projects.read\",\n    \"access.members.read\",\n    \"http.outbound\",\n    \"instance.settings.register\",\n    \"secrets.read-ref\",\n    \"ui.page.register\",\n    \"ui.sidebar.register\",\n  ],\n  entrypoints: {\n    worker: \"./dist/worker.js\",\n    ui: \"./dist/ui\",\n  },\n  instanceConfigSchema: {\n    type: \"object\",\n    properties: {\n      gatewayUrl: {\n        type: \"string\",\n        title: \"Self-hosted ACL gateway URL\",\n        description: \"Private Paperclip ACL gateway used by legacy company/team memory and reviewed memory candidates. Defaults to the OTOMATIK loopback endpoint.\",\n        default: \"http://127.0.0.1:6768/mcp\",\n      },\n      localApiUrl: {\n        type: \"string\",\n        title: \"Supermemory Local API URL\",\n        description: \"Private Supermemory Local API used by Owner-managed namespace content and explicit agent/project memory. Defaults to the OTOMATIK loopback endpoint.\",\n        default: \"http://127.0.0.1:6767\",\n      },\n      adminApiKeyRef: {\n        type: \"string\",\n        format: \"secret-ref\",\n        title: \"Owner-only Supermemory Local API key\",\n        description: \"Paperclip secret containing the Supermemory Local master API key. The plugin resolves it only for Owner-checked management actions and authorized agent searches; never paste it into instructions or agent prompts.\",\n      },\n      agentGrants: {\n        type: \"array\",\n        title: \"Authorized agents\",\n        description: \"Only listed Paperclip agents can use the memory tools. Each one uses its own ACL gateway token secret, already bound to the same agent, company, and role.\",\n        items: {\n          type: \"object\",\n          title: \"Agent grant\",\n          required: [\"agentId\", \"tokenRef\"],\n          properties: {\n            agentId: {\n              type: \"string\",\n              title: \"Paperclip agent\",\n              minLength: 1,\n            },\n            tokenRef: {\n              type: \"string\",\n              format: \"secret-ref\",\n              title: \"This agent's ACL token secret\",\n              description: \"Select the Paperclip company secret containing only this agent's Supermemory ACL token.\",\n            },\n          },\n        },\n        default: [],\n      },\n    },\n  },\n  tools: [\n    {\n      name: SEARCH_TOOL,\n      displayName: \"Search approved Supermemory\",\n      description: \"Search this agent's explicitly authorized company/team compartments and any assigned agent/project namespaces. Project memory is available only when the Paperclip run is in that project and the agent is on its explicit allowlist. Do not search for credentials or personal records.\",\n      parametersSchema: {\n        type: \"object\",\n        properties: {\n          query: { type: \"string\", minLength: 1, maxLength: 300 },\n          searchMode: { type: \"string\", enum: [\"hybrid\", \"memories\", \"chunks\"], default: \"hybrid\" },\n          limit: { type: \"integer\", minimum: 1, maximum: 5, default: 3 },\n        },\n        required: [\"query\"],\n        additionalProperties: false,\n      },\n    },\n    {\n      name: SAVE_TOOL,\n      displayName: \"Submit a Supermemory candidate\",\n      description: \"Submit one durable, non-sensitive fact or decision to this agent's role staging compartment for human review. This does not publish it to shared approved memory. Never submit credentials, personal data, customer cases, legal/health/workplace records, or full chat transcripts.\",\n      parametersSchema: {\n        type: \"object\",\n        properties: {\n          content: { type: \"string\", minLength: 20, maxLength: 1200 },\n        },\n        required: [\"content\"],\n        additionalProperties: false,\n      },\n    },\n  ],\n  ui: {\n    slots: [\n      {\n        type: \"settingsPage\",\n        id: MEMORY_SETTINGS_PAGE,\n        displayName: \"Supermemory settings\",\n        exportName: \"SupermemorySettingsPage\",\n      },\n      {\n        type: \"page\",\n        id: MEMORY_PAGE,\n        displayName: \"Memory\",\n        exportName: \"MemoryPage\",\n        routePath: MEMORY_ROUTE,\n      },\n      {\n        type: \"sidebar\",\n        id: MEMORY_SIDEBAR,\n        displayName: \"Memory\",\n        exportName: \"MemorySidebarLink\",\n      },\n    ],\n  },\n};\n\nexport default manifest;\n"],
+  "mappings": "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",
+  "names": []
+}