Longterm Memory

LongtermMemory-MCP

A fully local MCP server that gives AI agents persistent, semantic long-term memory — without any cloud dependencies.

Inspired by mcp-mem0, but runs 100% on your machine:

Tools

Core

Search

Maintenance

Quick Start

Claude Code Plugin (recommended)

Install via the Claude Code marketplace — this sets up both the MCP server and a companion skill that teaches Claude how to use memory effectively:

/plugin marketplace add MarcelRoozekrans/LongtermMemory-MCP

/plugin install longterm-memory@longterm-memory-marketplace

This automatically:

• Configures the MCP server (no manual JSON editing), pinned to the plugin's version: a plugin update also updates the server
• Adds the automatic recall hook
• Installs the long-term-memory skill (Claude learns to recall context at session start, save insights after tasks, and deduplicate memories)

Use with npx (no install needed)

npx longterm-memory-mcp

npx keeps running the version it cached first and does not look for updates. To move to a new release, name the version, as in npx -y longterm-memory-mcp@1.6.0, or use @latest, which checks the registry on every start.

Or install globally

npm install -g longterm-memory-mcp

longterm-memory-mcp

Or from source

git clone https://github.com/MarcelRoozekrans/LongtermMemory-MCP.git

cd LongtermMemory-MCP npm install && npm run build npm start

Configuration

Claude Code

If you installed via the plugin marketplace, the MCP server is already configured. For manual setup, add to your MCP settings (~/.claude/settings.json or project .claude/settings.json):

{

"mcpServers": { "longterm-memory": { "command": "npx", "args": ["-y", "longterm-memory-mcp"] } } }

Claude Desktop

Add to claude_desktop_config.json:

{

"mcpServers": { "longterm-memory": { "command": "npx", "args": ["-y", "longterm-memory-mcp"] } } }

Agent Instructions

The repo includes agent instructions that teach AI agents how to use memory effectively (automatic recall, save patterns, deduplication):

Database Location

By default, memories are stored in a shared, user-scoped location:

~/.longterm-memory-mcp/memories.db

This means every project and every MCP client shares the same memory pool — you save a memory in one project and it's available everywhere.

Several sessions can use the same database at once. Each server process reads and writes the shared file directly (SQLite in WAL mode), so a memory saved in one session is visible to every other session right away, and no session overwrites what another saved. Requires Node.js 22.13 or later.

Databases from older releases open unchanged. A database from v1.0–1.3, which has no schema_meta table, is migrated in place with all its memories kept; a copy named memories.db.pre-migration- .bak is written next to it first.

Upgrading from 1.4 or earlier: stop every running session that uses the old version before starting one with the new version. Older releases keep the whole database in memory and rewrite the file on each save, so an old process left running would overwrite what new sessions saved.

Per-project database

To isolate memories for a specific project, set the MEMORY_DB_PATH environment variable:

{

"mcpServers": { "longterm-memory": { "command": "npx", "args": ["-y", "longterm-memory-mcp"], "env": { "MEMORY_DB_PATH": "/path/to/project/memories.db" } } } }

Memory Types

Each memory has a memory_type that determines how it's categorized and how quickly it decays:

Tags & Importance

• Tags: Categorize memories with string tags (e.g. ["auth", "backend"]). Search with search_by_tags.
• Importance (1–10): Controls how resistant a memory is to decay. Default is 5. Higher importance decays more slowly.
• Protected tags: Memories tagged with core, identity, or pinned skip decay entirely.

Decay & Reinforcement

Memories decay over time to keep the store relevant:

• Decay: Each memory type has a half-life (see table above). Importance decreases exponentially based on time since last access, with a floor that prevents full deletion.
• Reinforcement: Every time a memory is accessed via search, its importance increases by +0.1 (up to a max of 10). Frequently accessed memories stay important.
• Lazy evaluation: Decay is calculated on access, not on a timer — no background processes needed.

Content Deduplication

Memory content is hashed (SHA-256) on save. If identical content already exists, the save is rejected with a reference to the existing memory ID. This prevents duplicate entries automatically.

Content Guard

Memories end up in the database and in its JSON backups, so content is filtered before it is stored:

• ` ` spans are removed. Text inside … is never stored, embedded or hashed. An unclosed removes everything after it. Content that is empty once the spans are removed is rejected.
• Secrets are rejected. save_memory and update_memory refuse content, metadata values and tags that look like a secret. The error names the pattern that matched and never the value.

Configure it with environment variables:

{

"mcpServers": { "longterm-memory": { "command": "npx", "args": ["longterm-memory-mcp"], "env": { "MEMORY_GUARD_DISABLE": "jwt,slack-token", "MEMORY_GUARD_EXTRA_PATTERNS": "{\"internal-host\": \"\\\\b[a-z0-9-]+\\\\.corp\\\\.example\\\\b\"}" } } } }

• MEMORY_GUARD_DISABLE: a comma-separated list of pattern names to turn off, or all for every built-in pattern. spans are removed either way. An unknown name stops the server at startup.
• MEMORY_GUARD_EXTRA_PATTERNS: a JSON object of extra patterns to reject, as name → regular expression.

The guard applies to new saves and updates only. Memories stored before it existed are not rescanned.

Automatic Recall

The Claude Code plugin ships a UserPromptSubmit hook that recalls memories without the agent having to ask. On the first prompt of each session it searches with the prompt text and adds the best matches to the context as a short list:

Long-term memories that may be relevant (longterm-memory; search_memory gives the full text):

• [2026-10-22 fact] pkill -f also matches the agent's own shell … (id 31ece450-…)

• Once per session: the hook keeps a marker file per session id in recall-sessions/ next to the database. Later prompts in that session cost one node start, about 30 ms, and no search.
• Project: the hook takes the project name from the session's working directory. A memory that names the project in its content, tags or metadata ranks a little higher. The name is not part of the search text: a short prompt would then match on the project name alone.
• Cheap when it misses: nothing is injected when no memory reaches the threshold, and the block never exceeds the token cap.
• Content guard: a stored memory that the guard rejects, such as one saved before the guard existed, is never injected.
• Never blocks a prompt: errors go to stderr and the prompt continues.
• Pinned version: the hook runs npx longterm-memory-mcp@ recall --hook, so a cached older copy is never used. The plugin's MCP server is pinned the same way.

Configure it with environment variables in your Claude Code settings (env in ~/.claude/settings.json). The hook runs in Claude Code's environment, not the MCP server's, so a custom MEMORY_DB_PATH has to be set there too.

Recall CLI

The hook calls the recall subcommand, which also works on its own:

npx longterm-memory-mcp recall "how do we deploy the stack"

npx longterm-memory-mcp recall --k 3 --threshold 0.4 --project docker "deploy"

It prints the same list the hook injects, or No relevant memories found. on stderr. Options: --k, --threshold, --max-tokens and --project (default: the current directory's name, "" for none). It does not create a database that does not exist yet. With --hook it reads a Claude Code UserPromptSubmit event from stdin and answers with additionalContext.

Backups

Backups are managed automatically and can also be triggered manually via the create_backup tool.