Plugins

Why plugins existCopy Anchor Link

Skills and custom tools cover one piece of a feature. A plugin ships the whole feature: a dashboard page, agent tools, and the data they share — without changing Nakama itself.

What you getCopy Anchor Link

After a package is approved and your organization turns it on:

• Members open native plugin pages from Control center → Installed plugins, using the dashboard theme
• Assigned profiles can call the plugin's tools in chat
• Notes and other plugin records stay in that organization

The same note you create on the page is the one the agent reads. Another organization never sees it.

How to use themCopy Anchor Link

1. Install a package (platform admin). Open Control center → Agent tools → Plugins, enter the public npm package name and exact version, choose Preview package, review what it declares, and install it. Installation stores the package. It does not run plugin code and does not turn the plugin on for any organization.

2. Activate it in the organization (org admin). Stay in Control center → Agent tools → Plugins, add the plugin to the active organization, then enable it. Enable is what creates the organization's data store and makes the page available.

3. Assign capabilities (platform admin). Use the existing profile skill and tool pickers. Plugin items show as owned by the plugin. Assign them the same way you assign other skills and tools.

4. Use the page (members). Open the plugin from Control center → Installed plugins. Viewers can read chat only. They cannot open plugin pages or call plugin actions.

5. Update or remove (org admin). Choose Update to move to a newer approved release. A platform admin also sees an Update tag on a plugin when the registry has a version nobody approved yet. Choosing Update there opens the same package review as the first install, then updates the plugin, so the package name is typed only once. An enabled plugin is switched off for the update and back on afterwards, so its tools are unavailable for a moment. To remove a plugin, uninstall it. Uninstall keeps the organization's plugin data until you confirm a separate delete.

SupermemoryCopy Anchor Link

Use Supermemory for the agent memory, shared organization memory, and knowledge base you already use in Nakama. Your existing memory tools, approval flow, and knowledge uploads stay in place.

1. An org admin opens Control center → Agent tools → Plugins → Official plugins → Supermemory → Install.
2. Enable the plugin. Nakama automatically uses your default OpenAI provider, or the first saved OpenAI provider if your default uses another service. If you use a separately managed server, open Supermemory → Settings, save its URL and API token, and use Check saved connection.
3. Keep using your agent's memory and knowledge base. Existing content moves to Supermemory when it is next read or searched; new knowledge uploads also sync automatically. Shared organization facts still require the usual approval before they are saved.
4. Ask your agent to search its knowledge base using everyday language. Explicit regular-expression searches still use the local extracted text.

The managed worker automatically reuses a saved OpenAI provider’s API key, URL, and default model for extraction, with local embeddings. Add an OpenAI provider in Control center → Agent tools → AI Providers if none is available. ChatGPT subscription connections are not supported by this worker. Restart Supermemory in Control center → Workspace → Workers after adding or changing your OpenAI provider. A changed provider configuration reindexes existing content on its next access, including failed documents. Verification makes a small API request; extraction and search also require the configured provider.

Nakama keeps local copies for recovery. Disabling the plugin returns your existing tools to those copies. Before the managed worker first becomes ready, memory stays local. After migration starts, an unavailable backend reports an error; restart the worker or disable the plugin to continue locally. Search can ask you to retry while new content is indexing.

The plugin's separate Memory and Knowledge collections remain available for previously saved items and explicit plugin actions. They are separate from the built-in memory and knowledge base. Installing the plugin does not automatically capture every conversation.

Documents show their processing state. Use Check status for an unresolved save and retry the same submission when asked. Removal pending means the item is excluded from plugin searches, but remote removal still needs retry. Forget is a soft deletion upstream, not permanent erasure.

Knowledge documents are sent as complete extracted text. Supermemory chooses their search chunks and uses its SuperRAG mode, which skips personal-memory extraction. PDF text extraction stays local; this setup does not require a separate Gemini account. Existing documents are reindexed on their next access after upgrading.

For built-in memory, replaced or removed versions stop appearing in search immediately. If Supermemory is still processing them, Nakama retries remote cleanup on later memory operations.

Use a dedicated Supermemory server per organization. Once content has been saved, the plugin keeps that server address fixed; an admin can still rotate its token. Disabling or uninstalling retains the external data. Back up the Supermemory server separately: Nakama's backup contains the connection and tracking records, not the external dataset. Restore into the same organization to retain access; moving records to a different organization requires fresh ingestion.

Who can do whatCopy Anchor Link

TrustCopy Anchor Link

An installed plugin is trusted code. Approving a package lets that code run with the signed-in user's dashboard session and the server process. Organization folders keep one org's notes away from another org by accident. They do not protect you from a malicious plugin author.

BackupCopy Anchor Link

Plugin data is included in a full Control center → Workspace → Settings → Export ZIP backup as a consistent snapshot. Restore leaves plugins disabled until an admin enables them again. If a restored package no longer matches its stored hash, that release stays unavailable.

See Backup and restore.

Next stepsCopy Anchor Link

• Build your first plugin — create a tool, page, and custom chat card

• Profiles — assign plugin skills and tools; profile packs keep plugin references only

• Backup and restore — whole-install ZIP including plugin data

• Skills — how assigned skills show up in chat