🧠 Simple Memory MCP Server

A blazingly fast Model Context Protocol (MCP) server for persistent memory storage with intelligent tagging and full-text search.

Perfect for AI assistants that need to remember context across conversations, store project notes, or build a personal knowledge base.

✨ Features

🧠 Auto-Capture - LLM proactively stores important information during conversations
🚀 Sub-millisecond Performance - 2,000-10,000 operations/second
🔍 Full-Text Search - SQLite FTS5 with 0.14ms average query time
🏷️ Smart Tagging - Organize and filter memories with tags
🔗 Auto-Relationships - Automatically link related memories
💾 Automatic Backups - Optional lazy backups to cloud storage
🔄 Safe Migrations - Automatic schema upgrades without data loss
📦 Zero Config - Works out of the box with sensible defaults

📊 Performance Highlights

Operation	Average Time	Throughput
Store Memory (1KB)	0.1ms	~10,000 ops/sec
Tag Search	0.18ms	~5,500 ops/sec
Full-Text Search	0.14ms	~7,000 ops/sec
Bulk Relationships	0.26ms	~3,800 ops/sec

All operations complete in sub-millisecond timeframes with optimized indexes and prepared statements.

🚀 Quick Start

1️⃣ Install

Option A: From npm (when published)

npm install -g simple-memory-mcp

Option B: For development/testing (current)

# Clone and build the repository
git clone https://github.com/chrisribe/simple-memory-mcp.git
cd simple-memory-mcp
npm install

# Link globally (builds automatically)
npm run link

# Now 'simple-memory' command works globally!
simple-memory memory-stats

# To unlink later
npm run unlink

💡 What's the difference? Option A installs from npm's registry (not available yet). Option B creates a symlink to your local code, perfect for testing and development. Both make the simple-memory command available globally.

2️⃣ Configure Your MCP Client

Add to your MCP client config (e.g., Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "simple-memory": {
      "command": "simple-memory"
    }
  }
}

💡 Windows users: Config is usually at %APPDATA%\Claude\claude_desktop_config.json
💡 macOS users: Config is usually at ~/Library/Application Support/Claude/claude_desktop_config.json

3️⃣ Restart Your MCP Client

That's it! Start storing and retrieving memories with your AI assistant.

💻 Usage

As MCP Server

The server exposes tools that your AI assistant can use directly. Once configured, your assistant will:

🧠 Auto-Capture Mode - Proactively store important information:

Preferences you mention ("I prefer dark mode")
Decisions you make ("Let's use PostgreSQL")
Facts about people, projects, or tools
Learnings and insights you discover

📝 Manual Storage - You can also explicitly ask:

"Remember that I prefer dark mode"
"Store this meeting summary with tags project and planning"
"Search my memories for Python tips"
"Show me all memories tagged with 'important'"

The assistant stores memories silently and retrieves them when relevant, creating a seamless conversation experience.

Command Line Interface

You can also use the CLI directly:

# Store a memory
simple-memory store-memory --content "Your content here" --tags "tag1,tag2"

# Search by content
simple-memory search-memory --query "search term"

# Search by tags
simple-memory search-memory --tags "tag1,tag2"

# View statistics
simple-memory memory-stats

# Delete by tag
simple-memory delete-memory --tag "old-notes"

🛠️ Available Tools

`store-memory`

Store content with optional tags.

🧠 Auto-Capture: This tool is enhanced with guidelines that encourage your AI assistant to proactively store important information during conversations without explicit requests. The assistant learns to:

Capture preferences, decisions, and facts automatically
Store silently without announcing
Use descriptive tags for easy retrieval
Link related memories intelligently

Parameters:

content (string, required) - The text content to store
tags (array, optional) - Tags to associate with the memory
autoLink (boolean, optional) - Auto-link to similar memories (default: true)

Example:

{
  "content": "Remember to use TypeScript for all new projects",
  "tags": ["coding", "best-practices"],
  "autoLink": true
}

`search-memory`

Search stored memories by content or tags.

💡 Proactive Usage: Enhanced with guidance for your AI assistant to search memories proactively at conversation start or when relevant topics arise, providing personalized context-aware responses.

Parameters:

query (string, optional) - Text to search for in content
tags (array, optional) - Filter by tags
limit (number, optional) - Max results to return (default: 10)
includeRelated (boolean, optional) - Include related memories (default: false)

Example:

{
  "query": "TypeScript",
  "tags": ["coding"],
  "limit": 5
}

`delete-memory`

Delete memories by hash or tag.

Parameters:

hash (string, optional) - Hash of specific memory to delete
tag (string, optional) - Delete all memories with this tag

Example:

{
  "tag": "temporary"
}

`memory-stats`

Get statistics about stored memories.

Returns:

Total memories count
Total relationships count
Database size in bytes
Schema version
Backup status (if configured):
- Backup path
- Number of backup files
- Minutes since last backup
- Minutes until next backup

⚙️ Configuration

Environment Variables

Variable	Description	Default	Example
`MEMORY_DB`	Database file path	`./memory.db`	`/home/user/memories.db`
`MEMORY_BACKUP_PATH`	Backup directory (optional)	None	`/home/user/backups`
`MEMORY_BACKUP_INTERVAL`	Minutes between backups	`0` (disabled)	`180`
`MEMORY_BACKUP_KEEP`	Number of backups to keep	`10`	`24`
`MEMORY_CLOUD_SAFE`	Cloud storage safe mode	`false`	`true`
`DEBUG`	Enable debug logging	`false`	`true`

Custom Database Location

{
  "mcpServers": {
    "simple-memory": {
      "command": "simple-memory",
      "env": {
        "MEMORY_DB": "/path/to/your/memory.db"
      }
    }
  }
}

With Automatic Backups

{
  "mcpServers": {
    "simple-memory": {
      "command": "simple-memory",
      "env": {
        "MEMORY_DB": "/home/user/memory.db",
        "MEMORY_BACKUP_PATH": "/home/user/OneDrive/MCP-Backups",
        "MEMORY_BACKUP_INTERVAL": "180",
        "MEMORY_BACKUP_KEEP": "24"
      }
    }
  }
}

💡 Backup Strategy:

Lazy backups - Only backs up after write operations
Throttled - Won't backup again until interval passes
Efficient - No wasted backups when idle

⚠️ Cloud Storage Best Practices:

✅ Recommended: Store database locally, backup to cloud (as shown above)
⚠️ Not Recommended: Store database directly in OneDrive/Dropbox
- WAL mode creates 3 files that sync at different times → corruption risk
- File locking conflicts cause "database locked" errors
- 2-10x slower performance

If you must store directly in cloud storage, enable safe mode:

{
  "env": {
    "MEMORY_DB": "/path/to/OneDrive/memory.db",
    "MEMORY_CLOUD_SAFE": "true"
  }
}

This uses DELETE journal mode instead of WAL (30-50% slower but safer).

Multiple Database Instances

Run multiple instances for different contexts:

{
  "mcpServers": {
    "memory-work": {
      "command": "simple-memory",
      "env": {
        "MEMORY_DB": "/path/to/work-memory.db"
      }
    },
    "memory-personal": {
      "command": "simple-memory",
      "env": {
        "MEMORY_DB": "/path/to/personal-memory.db"
      }
    }
  }
}

🗄️ Database

Technology

SQLite with WAL mode for better concurrency
FTS5 for lightning-fast full-text search
Normalized tags with proper indexing (50-200x faster than LIKE queries)
Automatic relationships between related memories

Schema Features

✅ Automatic migrations with data integrity guarantees
✅ Optimized indexes on all hot paths
✅ Prepared statements for all queries
✅ 64MB cache with memory-based temp storage
✅ Transaction-based bulk operations

Size Limits

Maximum content size: 5MB per memory
No limit on number of memories
No limit on number of tags

🔧 Development

Setup

# Clone the repository
git clone https://github.com/chrisribe/simple-memory-mcp.git
cd simple-memory-mcp

# Install dependencies
npm install

# Build
npm run build

Commands

# Development mode with hot reload
npm run dev

# Build TypeScript
npm run build

# Run all tests (28 tests)
npm run test:all

# Run specific test suites
npm test              # Core functionality (9 tests)
npm run test:perf     # Performance tests (6 tests)
npm run test:migration # Migration tests (13 tests)

# Performance benchmarks
npm run benchmark

# Link/unlink globally for testing
npm run link          # Build and link globally (makes 'simple-memory' command available)
npm run unlink        # Remove global link

# Or manually
npm link              # Link current directory globally
npm unlink -g         # Unlink from global
simple-memory memory-stats  # Test the global command

Testing

The project has comprehensive test coverage:

✅ Core Tests (9) - CRUD operations, search, basic functionality
✅ Performance Tests (6) - Large content, size limits, throughput
✅ Migration Tests (13) - Schema upgrades, rollback safety, data integrity
✅ Benchmarks - Detailed performance metrics

All tests pass with 100% backward compatibility.

📝 Examples

Real-World Usage with AI Assistants

Simple Memory shines when used with AI assistants through MCP. Here are real conversation flows:

🎯 Example 1: Building Project Context Over Time

Day 1:

You: "I'm starting a new project. It's a React app with TypeScript, using Vite for bundling. We'll deploy to Vercel."

Assistant: Stores this with tags: project, react, typescript, vite, vercel

Day 3:

You: "What stack am I using for my project again?"

Assistant: Searches memories and finds: "You're using React with TypeScript, Vite for bundling, and deploying to Vercel."

Week 2:

You: "We decided to add Prisma ORM with PostgreSQL for the database."

Assistant: Stores this and auto-links to previous project memories

Week 4:

You: "Give me a summary of all my tech stack decisions."

Assistant: Retrieves all related memories and provides complete context

💡 Example 2: Personal Knowledge Base

Learning Session:

You: "Remember this: TypeScript generics allow type-safe reusable components. The syntax is function name<T>(arg: T): T"

Assistant: Stores with tags: typescript, generics, learning

You: "Also note: Array.reduce() is perfect for transforming arrays into single values. Use it instead of forEach when accumulating."

Assistant: Stores with tags: javascript, arrays, patterns

Later that week:

You: "What did I learn about TypeScript generics?"

Assistant: Retrieves your note with the exact syntax example

You: "Show me all my JavaScript tips"

Assistant: Searches tag javascript and finds all related notes

🔐 Example 3: Secure Information Storage

Storing Credentials:

You: "Store this API key for the payment gateway: sk_live_abc123xyz"

Assistant: Stores securely with tags: api-key, payment, credentials

You: "The database connection string is postgresql://user:pass@host:5432/db"

Assistant: Stores with tags: credentials, database, connection-string

Retrieval:

You: "What's my payment gateway API key?"

Assistant: Searches memories: "Your payment gateway API key is sk_live_abc123xyz"

You: "Show me all my stored credentials"

Assistant: Lists all memories tagged with credentials

📋 Example 4: Meeting Notes & Decisions

After Team Meeting:

You: "Meeting notes: Team agreed on 2-week sprints starting Monday. Sprint planning on Mondays at 10am. Retrospectives on Fridays."

Assistant: Stores with tags: meeting, agile, team, schedule

You: "Important decision: We're going with PostgreSQL instead of MongoDB for better transaction support."

Assistant: Stores with tags: decision, database, architecture

Later:

You: "When are our sprint meetings?"

Assistant: Retrieves schedule from meeting notes

You: "Why did we choose PostgreSQL?"

Assistant: Finds decision and reasoning: "For better transaction support"

🚀 Example 5: Continuous Context Building

The real power comes from persistent memory across all conversations:

Session 1: Store project setup info
  ↓
Session 2: Assistant remembers and builds on it
  ↓
Session 5: Store API decisions
  ↓
Session 10: Assistant recalls everything - full context maintained
  ↓
Session 20: Complete project knowledge base available instantly

This is impossible with standard chat sessions that lose context!

🔧 CLI Usage (For Testing & Direct Access)

You can also use the CLI directly for testing or scripting:

# Store a memory
simple-memory store-memory \
  --content "PostgreSQL connection: postgresql://localhost:5432/mydb" \
  --tags "database,credentials"

# Search by content
simple-memory search-memory --query "PostgreSQL"

# Search by tags
simple-memory search-memory --tags "credentials"

# View statistics
simple-memory memory-stats

# Delete memories by tag
simple-memory delete-memory --tag "temporary"

When to use CLI:

✅ Testing the MCP server works
✅ Bulk operations or scripting
✅ Debugging or inspecting the database
✅ Manual backup before major changes

Primary use case: Let your AI assistant handle everything through natural conversation!

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with the Model Context Protocol SDK
Powered by SQLite and better-sqlite3

📚 Additional Resources

Changelog - Version history and changes

🐛 Issues & Support

Found a bug or have a feature request?

⬆ back to top

Made with ❤️ by chrisribe

Name		Name	Last commit message	Last commit date
Latest commit History 37 Commits
.github		.github
docs		docs
plans		plans
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
IMPLEMENTATION-SUMMARY.md		IMPLEMENTATION-SUMMARY.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

chrisribe/simple-memory-mcp

Folders and files

Latest commit

History

Repository files navigation

🧠 Simple Memory MCP Server

✨ Features

📊 Performance Highlights

🚀 Quick Start

1️⃣ Install

2️⃣ Configure Your MCP Client

3️⃣ Restart Your MCP Client

📖 Table of Contents

💻 Usage

As MCP Server

Command Line Interface

🛠️ Available Tools

store-memory

search-memory

delete-memory

memory-stats

⚙️ Configuration

Environment Variables

Custom Database Location

With Automatic Backups

Multiple Database Instances

🗄️ Database

Technology

Schema Features

Size Limits

🔧 Development

Setup

Commands

Testing

📝 Examples

Real-World Usage with AI Assistants

🎯 Example 1: Building Project Context Over Time

💡 Example 2: Personal Knowledge Base

🔐 Example 3: Secure Information Storage

📋 Example 4: Meeting Notes & Decisions

🚀 Example 5: Continuous Context Building

🔧 CLI Usage (For Testing & Direct Access)

🤝 Contributing

📄 License

🙏 Acknowledgments

📚 Additional Resources

🐛 Issues & Support

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`store-memory`

`search-memory`

`delete-memory`

`memory-stats`

Packages