mcp-memory-sqlite

This repository has been superseded by alexfayers/mcp-memory, a full rewrite in Python. This TypeScript version is no longer maintained.

A personal knowledge graph and memory system for AI assistants using SQLite with FTS5 full-text search. Perfect for giving Claude (or any MCP-compatible AI) persistent memory across conversations!

Fork of spences10/mcp-memory-sqlite with additional tools and FTS5 search upgrade.

Why Use This?

Give your AI assistant a memory! This tool lets Claude (or other AI assistants) remember entities, concepts, and their relationships across conversations. Perfect for:

• 📚 Personal Knowledge Management - Build your own knowledge graph
• 🤖 AI Assistant Memory - Help Claude remember important information about your projects, preferences, and context
• 🔗 Relationship Tracking - Connect ideas, people, projects, and concepts
• 🔍 Smart Text Search - Find information using FTS5 full-text search with BM25 relevance ranking

Features

• 100% Local & Private: All your data stays on your machine
• Easy Setup: Works out-of-the-box with Claude Desktop
• FTS5 Full-Text Search: Multi-word queries with BM25 relevance ranking
• Smart Deduplication: Automatically prevents duplicate relationships
• Context-Optimized: Designed specifically for LLM context efficiency
• Safe Observation Updates: Append or delete individual observations without overwriting
• Graph Traversal: Explore 1-hop entity relationships filtered by type

Quick Start

For Claude Desktop users (recommended):

Add this to your Claude Desktop config:

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

That's it! Claude can now remember things across conversations.

Installation

If you want to use it in your own project:

npm install mcp-memory-sqlite
# or
pnpm add mcp-memory-sqlite

Configuration

Optional: Customize the database location with an environment variable:

• SQLITE_DB_PATH: Where to store your data (default: ./sqlite-memory.db)

MCP Tools

create_entities

Create or update entities with observations. Note: This overwrites all existing observations for an entity - use add_observations to append instead.

Parameters:

• entities: Array of entity objects
  • name (string): Unique entity identifier
  • entityType (string): Type/category of the entity
  • observations (string[]): Array of observation strings

Example:

{
	"entities": [
		{
			"name": "Claude",
			"entityType": "AI Assistant",
			"observations": [
				"Created by Anthropic",
				"Focuses on being helpful, harmless, and honest"
			]
		}
	]
}

add_observations

Append observations to an existing entity without overwriting existing ones. Skips duplicate observations. Throws if the entity does not exist.

Parameters:

• entityName (string): Name of the entity to update
• observations (string[]): Observations to add

Example:

{
	"entityName": "Claude",
	"observations": ["Supports extended thinking mode"]
}

delete_observations

Delete specific observations from an existing entity by content match. Returns the count of deleted observations. Throws if the entity does not exist.

Parameters:

• entityName (string): Name of the entity to update
• observations (string[]): Exact observation strings to delete

Example:

{
	"entityName": "Claude",
	"observations": ["Focuses on being helpful, harmless, and honest"]
}

search_nodes

Search for entities and their relations using FTS5 full-text search with BM25 relevance ranking. Multi-word queries match terms independently across entity names, types, and all observations.

Parameters:

• query (string): Text to search for
• limit (number, optional): Maximum results to return (default: 10, max: 50)

Example:

{
	"query": "AI Assistant",
	"limit": 5
}

read_graph

Get recent entities and their relations (returns last 10 entities by default).

Parameters: None

create_relations

Create relationships between entities. Duplicate relations (same source, target, and type) are automatically ignored.

Parameters:

• relations: Array of relation objects
  • source (string): Source entity name
  • target (string): Target entity name
  • type (string): Relationship type

Example:

{
	"relations": [
		{
			"source": "Claude",
			"target": "Anthropic",
			"type": "created_by"
		}
	]
}

get_entity_with_relations

Get an entity along with all its relations and directly connected entities.

Parameters:

• name (string): Entity name to retrieve

Example:

{
	"name": "Claude"
}

search_related_nodes

Get an entity along with all its directly related entities. Optionally filter by entity type and/or relation type for targeted graph traversal.

Parameters:

• name (string): Entity name to retrieve
• entityType (string, optional): Filter related entities by type
• relationType (string, optional): Filter relations by type

Example:

{
	"name": "my-project",
	"entityType": "task",
	"relationType": "implements"
}

delete_entity

Delete an entity and all associated data (observations and relations).

Parameters:

• name (string): Entity name to delete

delete_relation

Delete a specific relation between entities.

Parameters:

• source (string): Source entity name
• target (string): Target entity name
• type (string): Relationship type

Usage with Claude Desktop

Add to your Claude Desktop configuration:

Minimal configuration (uses default ./sqlite-memory.db):

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

With custom database path:

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

Database Schema

Tables

• entities: Stores entity metadata (name, type, creation time)
• observations: Stores observations linked to entities
• relations: Stores relationships between entities
• schema_version: Tracks applied migrations
• entities_fts: FTS5 virtual table for full-text search (with sync triggers)

Migrating from Old Single-Project Databases

If you have existing single-project memory databases (e.g., global.db, project.db), use the alexfayers-mcp-memory-sqlite-migrate tool to import them into the new unified multi-project database:

Migrate global memory:

alexfayers-mcp-memory-sqlite-migrate --source ~/.memory/global.db --project global --dest ~/.memory/memory.db

Migrate project memory (run from project root):

alexfayers-mcp-memory-sqlite-migrate --source .memory/project.db --project "$(basename "$PWD")" --dest ~/.memory/memory.db

The tool will:

• Create the destination DB if it doesn't exist
• Run all schema migrations automatically
• Import entities with their observations
• Import relations between entities
• Skip entities with no observations
• Deduplicate observations that already exist

Development

# Install dependencies
pnpm install

# Build
pnpm run build

# Run in development mode
pnpm run dev

License

MIT

Credits

Built with:

• better-sqlite3 - Fast SQLite driver
• tmcp - MCP server framework

Originally by Scott Spence.