Semantic Memory

Persistent memory with semantic search for Claude and MCP-compatible clients

License: MIT Node.js Version MCP Compatible

Give your AI assistant persistent memory that survives between conversations. Save context once, retrieve it intelligently forever.

✨ Features

• 🔍 Semantic Search - Find memories by meaning, not just keywords
• 💾 SQLite Storage - Fast, reliable, and scalable
• 👤 User Biography - Structured profile (name, occupation, tech stack, etc.)
• 🏠 100% Local - No external APIs, all processing on your machine
• ⚡ Fast - Powered by all-MiniLM-L6-v2 embeddings (~50ms searches)
• 🔒 Private - Your data never leaves your computer

🎯 Problem & Solution

Problem: Claude forgets everything between conversations. You constantly re-explain your context, projects, preferences, and tech stack.

Solution: This MCP server gives Claude persistent memory with intelligent semantic search. Save information once, and Claude retrieves it automatically when relevant.

Example

// Save once
save_memory("project-info", "Working on an e-commerce site with Next.js and Stripe")

// Days later, in a new conversation
User: "How do I add payments to my project?"
Claude: *searches memory* "Since you're using Stripe in your e-commerce project..."

🚀 Quick Start

Installation

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

# Install dependencies (pnpm recommended)
pnpm install
# or: npm install

Configuration

Add to your MCP client config (e.g., Claude Desktop):

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "semantic-memory": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-semantic-memory/index.js"]
    }
  }
}

Example (Windows):

{
  "mcpServers": {
    "semantic-memory": {
      "command": "node",
      "args": ["C:\\Users\\YourName\\mcp-semantic-memory\\index.js"]
    }
  }
}

First Run

1. Restart your MCP client (e.g., Claude Desktop)
2. The server will download the embedding model (~25MB) on first use
3. Start saving memories!

📚 Available Tools

Memory Management

save_memory(id, text, metadata?)

Save a memory with semantic embedding.

save_memory({
  id: "my-cat",
  text: "My cat's name is Mia, she's orange and very playful",
  metadata: { category: "personal", type: "pet" }
})

search_memory(query, n_results?, threshold?)

Search memories by semantic similarity.

search_memory({
  query: "what's my pet's name?",
  n_results: 5,      // optional, default: 5
  threshold: 0.3     // optional, default: 0.3 (0-1 scale)
})

get_memory(id)

Retrieve a specific memory by ID.

delete_memory(id)

Delete a memory permanently.

list_all_memories()

List all stored memories (ordered by last update).

User Biography

get_user_bio()

Get the user's complete biographical profile.

set_user_bio(data)

Create or update user biography. All fields are optional.

set_user_bio({
  nombre: "Angel",
  ocupacion: "Student",
  ubicacion: "Santiago, Chile",
  tecnologias: ["Python", "JavaScript", "Node.js"],
  herramientas: ["VS Code", "Docker", "pnpm"],
  idiomas: ["Spanish", "English"],
  timezone: "America/Santiago",
  mascotas: ["Mia (cat)"]
})

update_user_bio(field, value)

Update a single field in the biography.

update_user_bio({
  field: "tecnologias",
  value: ["Python", "JavaScript", "TypeScript"]
})

🎨 Use Cases

For Developers

• Remember your tech stack and project context
• Store solutions to common problems
• Keep track of configurations and preferences

For Students

• Save study notes and learning progress
• Remember assignment deadlines and requirements
• Track research topics and sources

For Everyone

• Personal preferences and interests
• Important dates and events
• Conversation context across sessions

🔧 How It Works

Semantic Search

Traditional keyword search:

Query: "what's my pet's name?"
Memory: "My cat Mia is orange"
Result: ❌ No matches (different words)

Semantic search:

Query: "what's my pet's name?"
Memory: "My cat Mia is orange"
Result: ✅ 78% similarity (understands meaning)

Technical Details

• Embeddings: all-MiniLM-L6-v2 (384 dimensions)
• Storage: SQLite with optimized indexes
• Search: Cosine similarity between vectors
• Performance: ~50-100ms per save, ~200ms search in 100 memories

📊 Database Schema

-- Memories table
CREATE TABLE memories (
  id TEXT PRIMARY KEY,
  text TEXT NOT NULL,
  embedding TEXT NOT NULL,  -- JSON array of 384 floats
  metadata TEXT,            -- JSON object
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);

-- User biography table
CREATE TABLE user_bio (
  id INTEGER PRIMARY KEY CHECK (id = 1),
  nombre TEXT,
  ocupacion TEXT,
  ubicacion TEXT,
  tecnologias TEXT,  -- JSON array
  herramientas TEXT, -- JSON array
  idiomas TEXT,      -- JSON array
  timezone TEXT,
  mascotas TEXT,     -- JSON array
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);

🆚 Comparison with Alternatives

Feature	This MCP	@modelcontextprotocol/server-memory
Semantic Search	✅	❌
User Biography	✅	❌
Storage	SQLite	In-memory
Persistence	✅ Disk	❌ RAM only
Scalability	1000s of memories	Limited
Search Speed	Fast (indexed)	N/A

🛠️ Development

# Install dependencies
pnpm install

# Run locally
node index.js

# Test with MCP inspector
npx @modelcontextprotocol/inspector node index.js

📝 Requirements

• Node.js >= 18.0.0
• ~100MB disk space (model + dependencies)
• MCP-compatible client (Claude Desktop, LM Studio, etc.)

🐛 Troubleshooting

First run takes 30-60 seconds

The embedding model is being downloaded (~25MB). Subsequent runs are instant.

sharp installation fails on Windows

pnpm rebuild sharp
# or
pnpm install --force

Database is locked

Close other connections to memory.db or restart your MCP client.

Memories not loading

Check that the absolute path in your MCP config is correct.

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest features
• Submit pull requests
• Improve documentation

📄 License

MIT License - feel free to use this in your own projects!

🙏 Acknowledgments

• Built with @modelcontextprotocol/sdk
• Embeddings by @xenova/transformers
• Powered by better-sqlite3

⭐ Star History

If you find this useful, consider giving it a star! It helps others discover the project.

---

Made with ❤️ for the MCP community

Report Bug · Request Feature