Simple Memory

npm version License: MIT TypeScript

Give your AI assistant persistent memory across sessions.

🚀 Looking for the next evolution?

git-memory is now my daily driver — it builds on the ideas from simple-memory and takes them further. If you're starting fresh, check it out! Simple-memory is still functional but is no longer my main focus.

The problem: AI assistants forget everything when you start a new conversation. Your preferences, project context, decisions - all gone.

The solution: Simple Memory lets AI store and retrieve information that persists forever. Local SQLite database, zero cloud, sub-millisecond fast.

Why not RAG? RAG systems need vector databases, embeddings, chunking strategies, and ongoing maintenance. Simple Memory is just keyword search in SQLite - no ML infrastructure, no API costs, works offline. Perfect for personal knowledge that doesn't need semantic similarity.

How It Works

You: "Remember that I prefer TypeScript over JavaScript and use 4-space indentation"

AI: stores this automatically

...days later, new session...

You: "Help me set up a new project"

AI: searches memory, finds your preferences → Sets up TypeScript with 4-space indentation

The AI handles storage and retrieval automatically. You just chat naturally.

Simple by design: Keyword search, not semantic. Local SQLite, not cloud. Zero setup, not configuration hell. If you need vector embeddings or team collaboration, see alternatives.

You: "I'm using PostgreSQL with TypeScript. Decided on Prisma ORM after 
      evaluating TypeORM - better type inference and migrations."

AI: → stores automatically with tags [tech-stack, database, decision]

You: "Setting up a new microservice, what database setup should I use?"

AI: → searches memories, finds your PostgreSQL + Prisma decision
   "Based on your previous work, you standardized on PostgreSQL with Prisma 
    ORM. You chose it over TypeORM for the better type inference..."

{
  "content": "Tech stack decision: PostgreSQL + Prisma ORM. Chose over TypeORM for better type inference and cleaner migrations.",
  "tags": ["tech-stack", "database", "decision"],
  "relevance": 0.92  // BM25 score when searching "database setup"
}

🤔 Why I built this

I got tired of every new conversation starting from zero. I use this daily - saving project status, gotchas, ideas that pop up while I’m deep in work. Instead of breaking flow to write things down somewhere, I just tell the assistant to save it and keep going. Having it all central means I can reference old solutions, things that failed, things that worked - across projects, across time. It’s basically an external memory for my dev brain.

✨ Features

• 🧠 Persistent Memory - Survives across sessions, restarts, forever
• 🔍 Full-Text Search - Find memories by keyword, tags, or content
• 🏷️ Smart Tagging - Organize memories with tags
• 💾 Automatic Backups - Optional sync to OneDrive/Dropbox
• 📦 Zero Config - Works out of the box
• 🚀 Fast - Sub-millisecond queries, 2,000-10,000 ops/sec

🚀 Quick Start

Configure MCP Client

Claude Desktop (claude_desktop_config.json):

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

VS Code (.vscode/mcp.json):

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

Restart your MCP client - that's it! No install needed.

💡 Best Experience: Works best with Claude Sonnet in Agent Mode for optimal auto-capture.

Auto-Configure VS Code & Claude Desktop

npx -y simple-memory-mcp setup

This automatically configures all detected installations.

Optional: Install CLI

For command-line usage (search, stats, export/import):

npm install -g simple-memory-mcp
simple-memory setup  # auto-configure VS Code & Claude

For Contributors

git clone https://github.com/chrisribe/simple-memory-mcp.git
cd simple-memory-mcp
npm run setup  # installs, builds, links, and configures

That's it! The AI assistant can now remember information across conversations.

💻 CLI Commands

# Setup - auto-configure VS Code and Claude Desktop
simple-memory setup

# Search memories
simple-memory search --query "typescript" --limit 5
simple-memory search --tags "project,work"

# Store a memory
simple-memory store --content "Remember this" --tags "note"

# Other operations
simple-memory get --hash "abc123..."
simple-memory delete --hash "abc123..."
simple-memory stats

# Export/import
simple-memory export-memory --output backup.json
simple-memory import-memory --input backup.json

Run simple-memory --help for all options.

🛠️ MCP Tools

The AI uses these tools automatically - you don't need to call them directly.

type Memory { hash, content, title, preview, tags, createdAt, relevance }
type StoreResult { success, hash, error }
type UpdateResult { success, hash, error }
type DeleteResult { success, hash, deletedCount, error }

type Query {
  memories(query: String, tags: [String], limit: Int): [Memory!]!
  memory(hash: String!): Memory
  related(hash: String!, limit: Int): [Memory!]!
  stats: Stats!
}
type Mutation {
  store(content: String!, tags: [String]): StoreResult!
  update(hash: String!, content: String!, tags: [String]): UpdateResult!
  delete(hash: String, tag: String): DeleteResult!
}

⚙️ Configuration

Zero config default: ~/.simple-memory/memory.db

Custom database location:

{
  "mcpServers": {
    "simple-memory": {
      "command": "npx",
      "args": ["-y", "simple-memory-mcp"],
      "env": {
        "MEMORY_DB": "/path/to/memory.db"
      }
    }
  }
}

With automatic backups:

{
  "env": {
    "MEMORY_BACKUP_PATH": "/path/to/OneDrive/backups",
    "MEMORY_BACKUP_INTERVAL": "180"
  }
}

📖 Full configuration guide: docs/configuration.md

• Environment variables reference
• Backup strategies
• Cloud storage best practices
• HTTP transport setup
• Multiple database instances

🔧 Development

npm install          # Install dependencies
npm run build        # Build TypeScript
npm test             # Run tests
npm run benchmark    # Performance benchmarks

Testing:

npm test              # GraphQL tests
npm run test:perf     # Performance tests  
npm run test:migration # Migration tests

📚 Documentation

Developer Docs: docs/dev/ - Manual testing, publishing guide, optimization history

🤝 Contributing

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

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Model Context Protocol SDK
• SQLite & better-sqlite3