@frontmcp/plugin-remember

Gives the tools of a FrontMCP server a small encrypted key-value memory, this.remember, so a tool can store something on one call and read it on a later one: a user's language, a draft, the last record they opened. Values are encrypted before they're stored, in memory, Redis or Vercel KV. Each value lives in a scope (session, user, tool or global) that decides who can read it back. Turn on tools.enabled and the plugin also gives the model four tools to remember things itself.

Install

npm install @frontmcp/plugin-remember

The plugin runs inside a FrontMCP server, so your app needs @frontmcp/sdk, at the same version as this package, and Node.js 24 or later. Its peer dependency @frontmcp/lazy-zod comes with the SDK.

For the Vercel KV store (type: 'vercel-kv', or 'global-store' with a Vercel KV provider), also install the optional peer @vercel/kv. The Redis stores use ioredis, which is already a dependency.

Usage

Register the plugin with RememberPlugin.init() in the plugins of @FrontMcp (every app) or of one @App (that app only). Importing the package also tells TypeScript about this.remember.

import { RememberPlugin } from '@frontmcp/plugin-remember';
import { App, FrontMcp, Tool, ToolContext, z } from '@frontmcp/sdk';

@Tool({
  name: 'set_language',
  description: 'Set the language the user wants answers in',
  inputSchema: { language: z.string() },
})
class SetLanguageTool extends ToolContext {
  async execute({ language }: { language: string }) {
    await this.remember.set('language', language, { scope: 'user' });
    return { language };
  }
}

@Tool({ name: 'get_language', description: 'The language the user wants answers in', inputSchema: {} })
class GetLanguageTool extends ToolContext {
  async execute() {
    const language = await this.remember.get('language', { scope: 'user', defaultValue: 'en' });
    return { language };
  }
}

@App({ id: 'preferences', name: 'Preferences', tools: [SetLanguageTool, GetLanguageTool] })
class PreferencesApp {}

@FrontMcp({
  info: { name: 'assistant', version: '1.0.0' },
  apps: [PreferencesApp],
  plugins: [RememberPlugin.init({ type: 'memory' })],
})
export default class Server {}

user scope needs a signed-in caller. An anonymous caller is refused with RememberIdentityError; see Scopes.

Options

Every option is optional. RememberPlugin.init() and plugins: [RememberPlugin] both keep values in memory.

Stores

A browser build (create() in a web page, WebMCP) has no TCP socket for Redis: there 'redis' and 'redis-client' throw BrowserStoreUnavailableError from init(), and 'global-store' on a Redis redis throws it when the server starts, before anything connects. The message names type: 'memory'. Vercel KV, over HTTPS, is allowed.

this.remember

this.remember is available in tools, resources, prompts and agents. Every method takes a scope option, which defaults to 'session'.

this.get(RememberAccessorToken) returns the same accessor, and this.tryGet(RememberAccessorToken) returns it or undefined where the plugin isn't installed.

Scopes

A scope with no caller to keep values apart throws RememberIdentityError: user scope for an anonymous caller, and session or tool scope for an anonymous caller without a verified session. Under MCP 2026-07-28, which has no sessions, session values belong to the signed-in caller and last across all their requests, so give conversation-sized state a ttl.

Encryption

With encryption on (the default), each value is encrypted with AES-256-GCM, with a key derived (HKDF-SHA256) from a server secret and the scope's identity. The server secret is encryption.customKey when you set it, otherwise:

1. REMEMBER_SECRET, MCP_MEMORY_SECRET or MCP_SESSION_SECRET from the environment.
2. Outside production (NODE_ENV isn't production): a secret the plugin generates and saves to .frontmcp/remember-secret.json. Keep .frontmcp/ out of version control.
3. In production: a random secret for this process, with a warning. Values can't be read after a restart, or by another instance.

Set REMEMBER_SECRET, or encryption.customKey, to the same value on every instance that shares a store.

Memory tools

With tools.enabled: true, the plugin registers four tools, named with tools.prefix if you set one:

Their scope is session (the default), user or global. They don't offer tool scope: it belongs to the tool that runs the call, so recall would never find what remember_this stored there. Up to 1.11.2 they accepted it.

The package also exports their classes, RememberThisTool, RecallTool, ForgetTool and ListMemoriesTool, to list in an app's tools yourself. Use one way or the other, not both.

Docs

• Remember plugin reference: every option, scope and error.
• Remembering across calls: a step-by-step guide.
• Redis: the @FrontMcp({ redis }) store that type: 'global-store' uses.

Related packages

• @frontmcp/sdk: the FrontMCP framework this plugin runs in.
• @frontmcp/plugin-approval: refuses a tool until an approval is recorded for the caller. Tool approval lives there, not in this plugin.
• @frontmcp/plugin-cache: caches tool results.
• @frontmcp/plugins: re-exports this plugin with other official plugins.

Contributing

Source: plugins/plugin-remember. Issues and pull requests are welcome; see CONTRIBUTING.md.

License

Apache-2.0. See LICENSE.