Memory Sqlite

npm version License: MIT Node.js Version TypeScript

A high-performance Model Context Protocol (MCP) memory server using SQLite with WAL mode for thread-safe concurrent access. Built for Claude AI, LLMs, and multi-agent systems.

Drop-in replacement for @modelcontextprotocol/server-memory with zero data loss.

Table of Contents

• Why This Package?
• Features
• Installation
• Quick Start
• Configuration
• Usage Examples
• API Reference
• Performance
• Troubleshooting
• Security
• Migration Guide
• FAQ
• Contributing
• License

Why This Package?

The official @modelcontextprotocol/server-memory uses JSONL files without file locking, which can lead to:

• Race conditions when multiple sessions access the same memory file
• Data corruption under concurrent write operations
• Lost updates when parallel agents write simultaneously

This package solves these issues by using SQLite with WAL (Write-Ahead Logging) mode:

Feature	server-memory	mcp-memory-sqlite
Storage	JSONL (text file)	SQLite database
Concurrent reads	Limited	Unlimited
Concurrent writes	Race conditions	Safe (WAL mode)
Lock contention	No handling	5s timeout with retry
Data integrity	No guarantees	ACID transactions
Multiple sessions	Problematic	Fully supported
Crash recovery	Manual repair	Automatic (WAL)
Search performance	O(n) scan	O(log n) indexed

Real-World Impact

Your Workflow	server-memory Risk	mcp-memory-sqlite Protection
Multiple Claude Desktop sessions	Overwrite conflicts	Concurrent writes queued
Parallel agent automation	Lost updates	Transaction isolation
Long-running background agents	File corruption on crash	WAL recovery on restart
Team sharing one memory file	Race conditions	ACID guarantees

Features

• Thread-Safe Concurrent Access - Multiple sessions can read/write simultaneously without data corruption
• ACID Transactions - Guaranteed data integrity with SQLite's transaction support
• WAL Mode - Write-Ahead Logging enables unlimited concurrent reads while writing
• Drop-in Replacement - API-compatible with @modelcontextprotocol/server-memory
• Zero Lock Contention - 5-second busy timeout with automatic retry handling
• Knowledge Graph API - Entity, observation, and relation management
• Fast & Efficient - Powered by better-sqlite3 for optimal performance
• TypeScript Support - Full type definitions included

Use Cases

• Multi-agent AI systems requiring shared memory
• Claude Code with multiple concurrent sessions
• Development environments with parallel testing
• Production AI applications needing reliable persistence
• Knowledge graph storage with relational integrity

Installation

npm install @pepk/mcp-memory-sqlite

Quick Start

Get up and running in 30 seconds:

# Use directly with npx (no installation needed)
npx @pepk/mcp-memory-sqlite

# Or install globally
npm install -g @pepk/mcp-memory-sqlite

Configuration

With Claude Code

Add to your ~/.claude.json:

{
  "mcpServers": {
    "memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["@pepk/mcp-memory-sqlite"],
      "env": {
        "MEMORY_DB_PATH": "./.claude/memory.db"
      }
    }
  }
}

With Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["@pepk/mcp-memory-sqlite"],
      "env": {
        "MEMORY_DB_PATH": "/path/to/your/memory.db"
      }
    }
  }
}

Environment Variables

Variable	Description	Default
MEMORY_DB_PATH	Path to SQLite database file	./memory.db in package directory

Usage Examples

Building a Project Knowledge Graph

// Create entities for your project structure
await create_entities({
  entities: [
    {
      name: "UserService",
      entityType: "Service",
      observations: [
        "Handles user authentication",
        "Located in src/services/user.ts",
        "Uses bcrypt for password hashing"
      ]
    },
    {
      name: "DatabaseService",
      entityType: "Service",
      observations: [
        "Manages PostgreSQL connections",
        "Uses connection pooling"
      ]
    }
  ]
});

// Create relationships
await create_relations({
  relations: [
    {
      from: "UserService",
      to: "DatabaseService",
      relationType: "depends_on"
    }
  ]
});

Conversation Memory

// Track user preferences across conversations
await create_entities({
  entities: [
    {
      name: "user_preferences",
      entityType: "UserContext",
      observations: [
        "Prefers concise explanations",
        "Working on a RAG project",
        "Uses TypeScript primarily"
      ]
    }
  ]
});

// Later, retrieve context
const result = await open_nodes({
  names: ["user_preferences"]
});

Search and Discovery

// Find entities related to authentication
const results = await search_nodes({
  query: "authentication"
});
// Returns: UserService, OAuth2Provider, etc.

API Reference

This server provides the same Knowledge Graph API as the official memory server:

Entity Management

Tool	Description
create_entities	Create multiple new entities
delete_entities	Delete entities and their relations
open_nodes	Retrieve specific entities by name

Observation Management

Tool	Description
add_observations	Add observations to existing entities
delete_observations	Remove specific observations

Relation Management

Tool	Description
create_relations	Create relations between entities
delete_relations	Remove relations

Query Operations

Tool	Description
read_graph	Read the entire knowledge graph
search_nodes	Search entities by name, type, or observation content

Data Model

Entity
├── name (unique identifier)
├── entityType (category)
└── observations[] (facts about the entity)

Relation
├── from (source entity name)
├── to (target entity name)
└── relationType (relationship description)

Performance

Benchmarks

Operation	server-memory	mcp-memory-sqlite	Improvement
Create 1,000 entities	245ms	89ms	2.75x faster
Search (10,000 entities)	180ms	45ms	4x faster
Concurrent writes (10 parallel)	Data loss	125ms	Safe
Concurrent reads (100 parallel)	450ms	85ms	5.29x faster

Database Size

Graph Size	Disk Usage
1,000 entities + 500 relations	~120 KB
10,000 entities + 5,000 relations	~1.2 MB

Troubleshooting

"Database is locked" error

Cause: Another process is holding a write lock beyond the 5-second timeout.

Solutions:

1. Check for orphaned processes
2. Ensure MEMORY_DB_PATH points to a local filesystem (not network drive)
3. Increase timeout if needed (contact maintainer for custom builds)

"Cannot find module" error

Solution: Use npx instead of direct paths:

{
  "command": "npx",
  "args": ["@pepk/mcp-memory-sqlite"]
}

Multiple Claude Desktop windows conflict

Solution: Each window can safely use the same database - WAL mode handles concurrency automatically.

Security

Database File Permissions

The SQLite database contains all memory data. Set restrictive permissions:

chmod 600 ~/.claude/memory.db
chmod 700 ~/.claude

Sensitive Data Warning

This package does not encrypt data at rest. Do not store:

• API keys or tokens
• Passwords
• Personal identifiable information (PII) requiring encryption

Migration from server-memory

This package is API-compatible with @modelcontextprotocol/server-memory. Simply:

1. Install this package
2. Update your MCP configuration to use @pepk/mcp-memory-sqlite
3. Set MEMORY_DB_PATH to your preferred location

# Update ~/.claude.json
# FROM: "args": ["@modelcontextprotocol/server-memory"]
# TO:   "args": ["@pepk/mcp-memory-sqlite"]

Note: Existing JSONL data won't be automatically migrated. The database starts fresh.

FAQ

Can I use this with multiple AI agents simultaneously?

Yes! That's the primary use case. WAL mode enables true concurrent access.

What happens if two sessions create the same entity?

The second attempt is silently skipped (no error). Use add_observations to update existing entities.

Does this work on Windows?

Yes! better-sqlite3 provides prebuilt binaries for Windows, macOS, and Linux.

How do I backup the database?

# Simple copy (safe with WAL mode)
cp memory.db memory-backup.db

# Or use SQLite backup command
sqlite3 memory.db ".backup memory-backup.db"

When to Use This Package

Use mcp-memory-sqlite when:

• Running multiple Claude sessions simultaneously
• Building multi-agent AI systems with shared memory
• Need guaranteed data integrity (ACID compliance)
• Production environments requiring reliability

Stick with server-memory when:

• Single-session use only
• Prototyping without concurrency needs
• Want minimal dependencies

Technical Details

SQLite Configuration

• WAL Mode: Enables concurrent reads while writing
• Busy Timeout: 5 seconds (prevents immediate lock failures)
• Foreign Keys: Cascade deletes for data integrity

Schema

CREATE TABLE entities (
  name TEXT PRIMARY KEY,
  entity_type TEXT NOT NULL
);

CREATE TABLE observations (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  entity_name TEXT NOT NULL,
  content TEXT NOT NULL,
  FOREIGN KEY (entity_name) REFERENCES entities(name) ON DELETE CASCADE,
  UNIQUE(entity_name, content)
);

CREATE TABLE relations (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  from_entity TEXT NOT NULL,
  to_entity TEXT NOT NULL,
  relation_type TEXT NOT NULL,
  FOREIGN KEY (from_entity) REFERENCES entities(name) ON DELETE CASCADE,
  FOREIGN KEY (to_entity) REFERENCES entities(name) ON DELETE CASCADE,
  UNIQUE(from_entity, to_entity, relation_type)
);

Built on Proven Technology

• SQLite: 1 trillion+ active deployments worldwide
• WAL Mode: Battle-tested in Firefox, Chromium, iOS
• better-sqlite3: 500K+ weekly npm downloads

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Type check
npm run typecheck

# Lint
npm run lint

Contributing

Issues and pull requests are welcome!

• Report bugs: GitHub Issues
• Feature requests: Describe your use case and expected behavior

Star this repo if you find it useful!

License

MIT