Mnemosyne MCP

Knowledge graph memory for AI agents with local semantic search. Zero API costs.

Named after Mnemosyne, the Greek goddess of memory and mother of the Muses.

Overview

Mnemosyne provides persistent memory for AI agents using Neo4j knowledge graphs and local vector embeddings. Unlike traditional solutions requiring paid API access, Mnemosyne runs embeddings locally via ONNX Runtime.

Key Features:

• Local semantic search with BGE embeddings
• No API keys or external dependencies
• Works offline after initial setup
• Compatible with Model Context Protocol (MCP)
• Drop-in replacement for cloud-based solutions

Performance Comparison

Metric	Cloud Services	Mnemosyne
Cost	~$0.02/1M tokens	Free
API Key	Required	None
Network	Always required	Initial download only
Privacy	External	Local
Latency	~100ms	~200-500ms

Installation

Prerequisites

• Node.js >= 20.0.0
• Neo4j Database (Download)

Quick Start (NPM)

npx @zhadyz/mnemosyne-mcp

From Source

git clone https://github.com/zhadyz/mnemosyne-mcp.git
cd mnemosyne-mcp
npm install
npm run build

Neo4j Setup

1. Install Neo4j Desktop
2. Create a database instance
3. Set credentials (default password: neo4j)
4. Start the database (default port: 7687)

Environment Configuration

Create .env in project root:

EMBEDDING_PROVIDER=local
LOCAL_EMBEDDING_MODEL=Xenova/bge-base-en-v1.5

NEO4J_URI=bolt://127.0.0.1:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=neo4j
# NEO4J_DATABASE - Automatically set by router based on project config

Multi-Project Database Routing

Mnemosyne includes built-in dynamic database routing that automatically selects the correct Neo4j database based on your current project.

Why Use Multi-Database Architecture?

Performance at Scale:

• Query 10⁴ entities instead of 10⁵+ in monolithic architecture
• O(log n) query complexity through database partitioning
• Linear project addition without performance degradation

Project Isolation:

• Namespace separation prevents cross-contamination of knowledge graphs
• Each project gets its own isolated database
• Global patterns database for cross-project learnings

Setup

1. Create project databases in Neo4j:

CREATE DATABASE my_project_db IF NOT EXISTS;
CREATE DATABASE another_project_db IF NOT EXISTS;

2. Add .mnemosyne file to each project root:

# Project-specific database name (required)
MNEMOSYNE_DATABASE=my_project_db

# Optional metadata
PROJECT_NAME=My Project
RETENTION_DAYS=90
AUTO_CLEANUP=true
ISOLATION_LEVEL=project

3. Router automatically detects database:

Your Projects:
├─ project-alpha/
│  └─ .mnemosyne          → MNEMOSYNE_DATABASE=alpha_db
│     Routes to "alpha_db" database ✓
│
├─ project-beta/
│  └─ .mnemosyne          → MNEMOSYNE_DATABASE=beta_db
│     Routes to "beta_db" database ✓
│
└─ unconfigured-project/
   No .mnemosyne → Routes to "neo4j" (global patterns) ✓

The router walks up the directory tree from your current working directory, finds .mnemosyne or .env, and routes to the specified database. If no config is found, it defaults to neo4j (global patterns database).

Template: Copy the included template to your project:

cp node_modules/@zhadyz/mnemosyne-mcp/.mnemosyne.template .mnemosyne
# Edit MNEMOSYNE_DATABASE to your database name

Claude Integration

Claude Code (Recommended)

Add Mnemosyne to Claude Code with a single command:

claude mcp add --scope user mnemosyne -- npx -y @zhadyz/mnemosyne-mcp

Verify it's installed:

claude mcp list

You should see mnemosyne: npx -y @zhadyz/mnemosyne-mcp - ✓ Connected

Default Configuration:

• Neo4j URI: bolt://localhost:7687
• Username/Password: neo4j / neo4j
• Database: Automatic (via router - neo4j if no .mnemosyne file found)
• Embeddings: Local (BGE base-en-v1.5, 768 dimensions)

Custom Neo4j Setup: If you use different credentials, edit ~/.claude.json and add environment variables:

claude mcp add --scope user mnemosyne \
  -e NEO4J_PASSWORD=your_password \
  -- npx -y @zhadyz/mnemosyne-mcp

Dual MCP Instance Setup (Project + Global Memory)

For advanced workflows, run two separate Mnemosyne instances - one for project-specific knowledge and one for cross-project patterns.

Architecture:

• Project Instance: Uses automatic routing (finds .mnemosyne in your project)
• Global Instance: Always routes to neo4j database (forced override)

Setup:

# Project-specific knowledge (automatic routing)
claude mcp add --scope user mnemosyne-project -- npx -y @zhadyz/mnemosyne-mcp

# Global cross-project patterns (forced to neo4j database)
claude mcp add --scope user mnemosyne-global \
  -e MNEMOSYNE_FORCE_DATABASE=neo4j \
  -- npx -y @zhadyz/mnemosyne-mcp

Agent Usage:

Tools appear with prefixes in Claude:

• mcp__mnemosyne-project__create_entities → stores in project database
• mcp__mnemosyne-global__create_entities → stores in global neo4j database

Decision Heuristic for Agents:

Store in project database when knowledge is:

• Project-specific code: classes, functions, APIs, models
• Project context: dependencies, architecture decisions, local conventions
• Temporary learnings: current sprint patterns, debugging insights

Store in global database when knowledge is:

• Reusable patterns: error handling strategies, design patterns
• Framework best practices: Next.js optimization, React patterns
• Security patterns: authentication flows, input validation
• Meta-learnings: what works across multiple projects

Default Rule: When uncertain, store in project database. Manually promote proven patterns to global database after validation.

Claude Desktop

Basic Setup:

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "mnemosyne": {
      "command": "npx",
      "args": ["-y", "@zhadyz/mnemosyne-mcp"],
      "env": {
        "NEO4J_URI": "bolt://127.0.0.1:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "neo4j",
        "EMBEDDING_PROVIDER": "local",
        "LOCAL_EMBEDDING_MODEL": "Xenova/bge-base-en-v1.5"
      }
    }
  }
}

Dual Instance Setup (Project + Global):

{
  "mcpServers": {
    "mnemosyne-project": {
      "command": "npx",
      "args": ["-y", "@zhadyz/mnemosyne-mcp"],
      "env": {
        "NEO4J_URI": "bolt://127.0.0.1:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "neo4j",
        "EMBEDDING_PROVIDER": "local",
        "LOCAL_EMBEDDING_MODEL": "Xenova/bge-base-en-v1.5"
      }
    },
    "mnemosyne-global": {
      "command": "npx",
      "args": ["-y", "@zhadyz/mnemosyne-mcp"],
      "env": {
        "NEO4J_URI": "bolt://127.0.0.1:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "neo4j",
        "EMBEDDING_PROVIDER": "local",
        "LOCAL_EMBEDDING_MODEL": "Xenova/bge-base-en-v1.5",
        "MNEMOSYNE_FORCE_DATABASE": "neo4j"
      }
    }
  }
}

Local Development

{
  "mcpServers": {
    "mnemosyne": {
      "command": "node",
      "args": ["/absolute/path/to/mnemosyne-mcp/dist/router.js"],
      "env": {
        "NEO4J_URI": "bolt://127.0.0.1:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "neo4j",
        "EMBEDDING_PROVIDER": "local",
        "LOCAL_EMBEDDING_MODEL": "Xenova/bge-base-en-v1.5"
      }
    }
  }
}

Embedding Models

Mnemosyne supports multiple BGE models:

Model	Dimensions	Size	Use Case
bge-base-en-v1.5	768	90MB	Balanced (default)
bge-small-en-v1.5	384	30MB	Resource-constrained
bge-large-en-v1.5	1024	200MB	Maximum accuracy
bge-m3	1024	200MB	Multilingual

Models download automatically on first use and cache to ~/.cache/huggingface/.

Usage

Create Entities

{
  "name": "create_entities",
  "arguments": {
    "entities": [{
      "name": "TypeScript",
      "entityType": "programming_language",
      "observations": [
        "Strongly typed superset of JavaScript",
        "Compiles to JavaScript",
        "Static type checking"
      ]
    }]
  }
}

Semantic Search

{
  "name": "semantic_search",
  "arguments": {
    "query": "type-safe languages for web development",
    "limit": 5
  }
}

Create Relations

{
  "name": "create_relations",
  "arguments": {
    "relations": [{
      "from": "TypeScript",
      "to": "JavaScript",
      "relationType": "compiles_to"
    }]
  }
}

Architecture

EmbeddingServiceFactory
├── DefaultEmbeddingService (testing)
├── OpenAIEmbeddingService (cloud)
└── LocalEmbeddingService (ONNX)

All services implement IEmbeddingService, enabling seamless provider swapping.

Local Embeddings Stack

• ONNX Runtime: Optimized ML inference
• Transformers.js: JavaScript ML library
• BGE Models: BAAI general embeddings
• L2 Normalization: Vector similarity search

Development

npm test              # Run tests
npm run test:watch    # Watch mode
npm run build         # Build
npm run dev           # Development mode
npm run fix           # Lint and format

Configuration

Variable	Options	Description
EMBEDDING_PROVIDER	auto, local, openai	Provider selection
LOCAL_EMBEDDING_MODEL	BGE model name	Local model choice
NEO4J_URI	bolt://...	Database connection
NEO4J_USERNAME	string	Database user
NEO4J_PASSWORD	string	Database password
NEO4J_DATABASE	string	Database name

Provider Selection:

• auto: OpenAI if API key present, otherwise local
• local: Always use local embeddings
• openai: Always use OpenAI (requires API key)

Credits

Forked from memento-mcp by Gannon Hall.

Additions:

• Local ONNX embedding support
• BGE model integration
• Auto-fallback configuration
• Zero-dependency operation

License

MIT License - see LICENSE file.

Contributing

Pull requests welcome.

---

Built by zhadyz Powered by ONNX Runtime + Transformers.js + BGE Embeddings