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):
The repo includes agent instructions that teach AI agents how to use memory effectively (automatic recall, save patterns, deduplication):
File
Purpose
skills/long-term-memory/SKILL.md
Self-contained skill — auto-loaded by Claude Code plugin, can be referenced from any MCP client
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-<timestamp>.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:
Each memory has a memory_type that determines how it's categorized and how quickly it decays:
Type
Description
Decay half-life
general
Default catch-all
60 days
fact
Verified information
120 days
preference
User/project preferences
90 days
conversation
Conversation context
45 days
task
Task-related notes
30 days
ephemeral
Short-lived context
10 days
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.
Backups
Backups are managed automatically and can also be triggered manually via the create_backup tool.
Auto-backup: Triggers every 24 hours or when the memory count reaches a multiple of 100.
Retention: The last 10 backups are kept; older ones are pruned automatically.
Format: Each backup is a timestamped directory containing a consistent snapshot of the SQLite database and a JSON export of all memories.
Location: ~/.longterm-memory-mcp/backups/ by default, or set MEMORY_BACKUP_PATH:
Save: Text is embedded locally using all-MiniLM-L6-v2 (384-dim vectors) and stored in SQLite alongside the raw content, metadata, tags, importance, and type. Content is deduplicated via SHA-256 hash.
Search: Your query is embedded with the same model, then compared against every stored memory using cosine similarity. Results above the threshold are returned ranked by relevance. Accessed memories are reinforced automatically.
Decay: Over time, unused memories lose importance based on their type's half-life. Protected and frequently accessed memories resist decay.
Persist: Every change is written straight to the SQLite database on disk, so concurrent sessions share one consistent store. No background processes, no servers to maintain.
The embedding model (~30MB quantized) is downloaded once on first use and cached locally.
Run with npm run bench. Results from an in-memory store using mock embeddings (isolates store/SQLite performance from model latency):
Cosine Similarity
Operation
Throughput
Notes
Single computation (384-dim)
~4.2M ops/s
Matches real embedding dimensions
128 dimensions
~8.6M ops/s
768 dimensions
~2.4M ops/s
1536 dimensions
~1.3M ops/s
Scales linearly with dimensions
Memory Store Operations
Operation
Throughput
Notes
Save (single)
~1,120 ops/s
Includes embed + SQLite insert + dedup check
Save 100 batch
~18 ops/s
~55ms per batch of 100
Save 1000 batch
~0.3 ops/s
~3.1s per batch of 1000
Update (content, re-embed)
~155 ops/s
Update (metadata only)
~344 ops/s
2.2x faster than content update
Delete
~469 ops/s
Search (semantic, at scale)
Store Size
Operation
Notes
10 memories
search (limit=5)
Full scan + cosine similarity per memory
100 memories
search (limit=5)
500 memories
search (limit=5)
1000 memories
search (limit=5)
Linear scan — scales with store size
Decay Engine
Operation
Throughput
Single decay computation
~21M ops/s
Single reinforcement
~25.7M ops/s
shouldProtect (tag check)
~22M ops/s
Development
npm install # Install dependencies
npm run build # Compile TypeScript
npm test # Run all tests
npm run bench # Run benchmarks
npm run test:watch # Watch mode
npm run test:coverage # Coverage report
Determines the next version (major / minor / patch)
Generates release notes from commits
Updates CHANGELOG.md
Publishes to npm
Creates a GitHub Release
No manual version bumps or tags needed.
Dependency Updates
Dependencies are managed automatically by Renovate. Patch and minor devDependency updates are auto-merged after CI passes. Major updates create PRs for manual review.
