Memory MCP

Persistent memory for AI agents. Plug-and-play with zero infrastructure.

A Model Context Protocol (MCP) server that gives your AI agents persistent, searchable memory. Works out of the box with zero configuration using local embeddings and file-based storage.

Features

• 🔍 Semantic Search - Find memories by meaning, not keywords

• 🔗 Auto-Linking - Related memories are automatically connected

• 🏷️ Auto-Categorization - Memories are categorized by type (knowledge, decision, pattern, etc.)

• ⭐ Importance Scoring - Automatic priority based on content

• 🔌 Pluggable Embeddings - Transformers.js (default), OpenAI, Ollama, or custom

• 📦 Zero Config - No database or API keys required to start

• 🤖 Agent Instructions - Agents automatically learn when and how to use memory tools via MCP protocol

Web Dashboard

Browse and search your memories in the browser with memory-mcp-dashboard — cyberpunk-themed UI, neural graph visualization, same storage.

Related MCP server: SharedBrain

Quick Start

Start the server immediately with zero configuration.

# Run using npx (requires Node 18+)
npx @aalokjha/mem-aj

Or install locally:

npm i @aalokjha/mem-aj

How it works by default:

• Embeddings: Uses in-process Transformers.js (all-MiniLM-L6-v2, 384 dimensions). No external server or Python needed.

• Storage: Uses a local JSON vector store at ~/.memory-mcp/.

• Initialization: The first run downloads a ~90MB model file. Every run after that is instant.

MCP Client Configuration

Add Memory MCP to your favorite AI tools by adding these configurations.

OpenCode / Claude Desktop / Cursor

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@aalokjha/mem-aj"]
    }
  }
}

Production Setup

Configure environment variables to use high-performance storage and external embedding providers.

Qdrant + External Embeddings

1. Run your own Qdrant instance.

2. Set environment variables to point to your services:

export VECTORDB_PROVIDER=qdrant
export QDRANT_URL=http://localhost:6333
export EMBEDDING_PROVIDER=openai
export EMBEDDING_API_KEY=sk-your-key

Configuration

Environment Variables

Embedding Providers

Transformers.js (Default - Zero Config)

Runs locally in your Node.js process. No external services needed.

export EMBEDDING_PROVIDER=transformersjs

OpenAI

export EMBEDDING_PROVIDER=openai
export EMBEDDING_API_KEY=sk-your-key
export EMBEDDING_MODEL=text-embedding-3-small

Ollama

export EMBEDDING_PROVIDER=ollama
export EMBEDDING_URL=http://localhost:11434
export EMBEDDING_MODEL=nomic-embed-text

Custom

Any HTTP endpoint that accepts POST /embed with { inputs: string[] } and returns number[][].

export EMBEDDING_PROVIDER=custom
export EMBEDDING_URL=http://your-service:port

MCP Tools

memory_add

Store a memory with automatic categorization and importance scoring.

{
  "content": "Decided to use PostgreSQL for the main database",
  "type": "auto",
  "tags": ["database", "architecture"],
  "project": "my-app"
}

memory_search

Semantic search across all memories.

{
  "query": "database decisions",
  "limit": 10,
  "min_score": 0.7
}

memory_list

Browse memories by type, tags, or project.

{
  "type": "decision",
  "project": "my-app",
  "limit": 20
}

memory_forget

Delete a memory by ID.

{
  "memoryId": "uuid-here"
}

memory_link

Manually link two related memories.

{
  "id1": "uuid-1",
  "id2": "uuid-2"
}

memory_profile

Store user preferences.

{
  "action": "set",
  "key": "preferred_language",
  "value": "typescript"
}

Memory Types

Development

# Install dependencies
npm install

# Build
npm run build

# Run in dev mode
npm run dev

# Run tests
npm test

Agent Instructions

The server automatically injects usage instructions into the connected agent's context via the MCP instructions protocol field. Agents learn:

• When to search, store, and link memories

• How to write effective memories (word limits adapted to the configured embedding model)

• What memory types to use and cross-tool workflows

No manual prompt engineering or AGENTS.md configuration needed. Just connect and the agent knows what to do.

Token limits per provider default:

Override with EMBEDDING_MAX_TOKENS if using a non-default model.

Architecture

Memory MCP supports two modes:

Zero-Config Mode (Default)

Simple, file-based storage for personal use.

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   MCP Client    │────▶│   Memory MCP    │────▶│   Local JSON    │
│   (Claude/AI)   │     │    Server       │     │   Vector Store  │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                 │
                                 ▼
                        ┌─────────────────┐
                        │ Transformers.js │
                        │  (In-process)   │
                        └─────────────────┘

Production Mode

High-performance configuration for shared environments.

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   MCP Client    │────▶│   Memory MCP    │────▶│     Qdrant      │
│   (Claude/AI)   │     │    Server       │     │    Vector DB    │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                 │
                                 ▼
                        ┌─────────────────┐
                        │    External     │
                        │    Provider     │
                        │ (OpenAI/Ollama) │
                        └─────────────────┘

License

MIT License - see LICENSE

Contributing

Contributions welcome! Please read our contributing guidelines.

Credits

Built by Aalok Jha