Local Context Memory MCP

★ 12

from cunicopia-dev

A production-ready persistent memory system for AI agents, offering searchable memory across sessions with semantic search and support for multiple database backends.

🔥🔥🔥🔥✓ VerifiedFreeQuick setup

#automation #database #devops #git #security #memory

Local Context Memory MCP

Ever wanted the ChatGPT memory feature but across all your LLMs and stored on your own hardware? Ever hate how there's a limit to how many memories ChatGPT can store, and that you can't segment your memories into different domains?

Here's your fix.

Give any AI assistant persistent, unlimited memory that you control completely.

A production-ready persistent memory system for AI agents using the Model Context Protocol (MCP). Works with Claude Desktop, any MCP-compatible client, and gives you the memory features you've been wanting.

Why This Matters
Choose Your Implementation
Tools & Capabilities
Architecture Diagrams
- SQLite + FAISS Implementation
- PostgreSQL + pgvector Implementation
Features
Quick Start
- Prerequisites
- Ollama Setup
Claude Desktop Setup
Examples
Components
Configuration
Development
- Docker
Manual Installation
Demo
License

Why This Matters

Traditional AI Problem: AI assistants forget everything between conversations. Every interaction starts from scratch, requiring users to repeatedly provide context about their preferences, projects, and history.

Solution: Local Context Memory gives your AI persistent, searchable memory that:

🧠 Remembers across sessions - User preferences, project details, conversation history
🎯 Finds relevant context - Semantic search surfaces the right memories at the right time
🏢 Organizes by domain - Separate contexts for work, health, personal life (PostgreSQL)
🔒 Stays private - All data stored locally under your control
⚡ Works immediately - Drop-in compatibility with Claude Desktop and MCP clients

Choose Your Implementation

SQLite + FAISS: Perfect for personal use, development, and simple deployments
PostgreSQL + pgvector: Production-ready with domain segmentation and team collaboration

Tools & Capabilities

graph LR
    subgraph "Client"
        USER[User]
        CD[Claude Desktop]
    end
    
    subgraph "MCP Server"
        subgraph "Tools"
            SM[store_memory]
            UM[update_memory]
            SRCH[search_memories]
            LMD[list_memory_domains]
        end
        
        subgraph "Resources"
            RES_SQL[memory://query]
            RES_PG[memory://domain/query]
        end
        
        subgraph "Prompts"
            SUM[summarize_memories]
        end
    end
    
    subgraph "Domain Context"
        DC[PostgreSQL Only]
        DC2[Multi-domain isolation:<br/>startup, health, personal]
    end
    
    USER --> CD
    CD -->|MCP Protocol| SM
    CD -->|MCP Protocol| UM
    CD -->|MCP Protocol| SRCH
    CD -->|MCP Protocol| LMD
    CD -->|MCP Protocol| RES_SQL
    CD -->|MCP Protocol| RES_PG
    CD -->|MCP Protocol| SUM
    
    LMD -.->|Available in| DC
    RES_PG -.->|Available in| DC
    DC --> DC2
    
    classDef client fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#0d47a1
    classDef server fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c
    classDef tool fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#e65100
    classDef resource fill:#e8f5e8,stroke:#388e3c,stroke-width:2px,color:#1b5e20
    classDef prompt fill:#fce4ec,stroke:#c2185b,stroke-width:2px,color:#880e4f
    classDef domain fill:#f1f8e9,stroke:#689f38,stroke-width:2px,color:#33691e
    
    class USER,CD client
    class SM,UM,SRCH,LMD tool
    class RES_SQL,RES_PG resource
    class SUM prompt
    class DC,DC2 domain

Available Tools

`store_memory`

Store new information in persistent memory with automatic semantic indexing.

SQLite: store_memory(content, source?, importance?)
PostgreSQL: store_memory(content, domain?, source?, importance?)
Examples:
- "User prefers TypeScript over JavaScript for new projects"
- "Weekly team meeting every Tuesday at 2 PM PST"

`update_memory`

Modify existing memories while preserving search indexing.

SQLite: update_memory(memory_id, content?, importance?)
PostgreSQL: update_memory(memory_id, content?, importance?, domain?)
Use case: Update outdated information or change importance levels

`search_memories`

Find relevant memories using semantic or keyword search.

SQLite: search_memories(query, limit?, use_vector?)
PostgreSQL: search_memories(query, domain?, limit?)
Examples:
- "What programming languages does the user prefer?"
- "Recent project decisions about database choices"

`list_memory_domains` (PostgreSQL Only)

Discover available memory domains for organized context switching.

Returns: ["default", "work", "health", "personal"]
Use case: Switch between different memory contexts

Available Resources

`memory://query` (SQLite)

Quick semantic search via URI pattern for simple memory retrieval.

`memory://domain/query` (PostgreSQL)

Domain-scoped semantic search for isolated memory contexts.

Examples:
- memory://work/project deadlines
- memory://health/medication schedule

Available Prompts

`summarize_memories`

Generate intelligent summaries of retrieved memory collections.

Input: List of memory objects
Output: Structured summary highlighting key patterns and insights
Use case: Create context summaries for complex topics

Architectures

SQLite + FAISS Implementation (Original)

graph TB
    subgraph "Client Layer"
        CD[Claude Desktop]
        AI[AI Agent]
    end
    
    subgraph "MCP Server Layer"
        SMS[SQLite Memory Server]
    end
    
    subgraph "API Layer" 
        SMA[SQLite Memory API]
        SVA[SQLite Vector API]
        OE[Ollama Embeddings]
        SC[Smart Chunker]
    end
    
    subgraph "Storage Layer"
        SQL[(SQLite Database)]
        FAISS[(FAISS Index)]
    end
    
    subgraph "External Services"
        OL[Ollama API]
        EM[nomic-embed-text]
    end
    
    CD -->|MCP Protocol| SMS
    AI -->|HTTP/JSON-RPC| SMS
    
    SMS --> SMA
    SMA --> SVA
    SVA --> SC
    SVA --> OE
    
    SMA -->|Store Metadata| SQL
    SVA -->|Vector Operations| FAISS
    
    OE -->|Generate Embeddings| OL
    OL --> EM
    
    classDef client fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#0d47a1
    classDef server fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c
    classDef api fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#e65100
    classDef storage fill:#e8f5e8,stroke:#388e3c,stroke-width:2px,color:#1b5e20
    classDef external fill:#fce4ec,stroke:#c2185b,stroke-width:2px,color:#880e4f
    
    class CD,AI client
    class SMS server
    class SMA,SVA,OE,SC api
    class SQL,FAISS storage
    class OL,EM external

PostgreSQL + pgvector Implementation (New)

graph TB
    subgraph "Client Layer"
        CD[Claude Desktop]
        AI[AI Agent]
    end
    
    subgraph "MCP Server Layer"
        PMS[PostgreSQL Memory Server]
    end
    
    subgraph "API Layer"
        PMA[PostgreSQL Memory API]
        OE[Ollama Embeddings]
    end
    
    subgraph "PostgreSQL Database"
        subgraph "Domain Tables"
            DT1[default_memories]
            DT2[startup_memories]
            DT3[health_memories]
        end
        PGV[pgvector Extension]
    end
    
    subgraph "External Services"
        OL[Ollama API]
        EM[nomic-embed-text]
    end
    
    CD -->|MCP Protocol| PMS
    AI -->|HTTP/JSON-RPC| PMS
    
    PMS --> PMA
    PMA --> OE
    PMA -->|SQL + Vector Ops| PGV
    PGV --> DT1
    PGV --> DT2
    PGV --> DT3
    
    OE -->|Generate Embeddings| OL
    OL --> EM
    
    classDef client fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#0d47a1
    classDef server fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c
    classDef api fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#e65100
    classDef storage fill:#e8f5e8,stroke:#388e3c,stroke-width:2px,color:#1b5e20
    classDef external fill:#fce4ec,stroke:#c2185b,stroke-width:2px,color:#880e4f
    
    class CD,AI client
    class PMS server
    class PMA,OE api
    class DT1,DT2,DT3,PGV storage
    class OL,EM external

Features

Common Features

Semantic Search: Uses Ollama embeddings for intelligent memory retrieval
Smart Chunking: Automatically breaks down long text for better search results
MCP Standard: Full MCP protocol compliance for Claude Desktop integration
Docker Ready: Simple containerized deployment with self-contained images
Fallback Search: Automatic fallback to text search when vector search unavailable

SQLite + FAISS Specific

Local Storage: Everything runs locally with SQLite + FAISS files
Zero Setup: No database server required
Portable: Single directory contains all data

PostgreSQL + pgvector Specific

Domain Segmentation: Separate memory contexts (startup, health, personal, etc.)
Production Ready: ACID compliance, concurrent access, replication support
Native Vector Ops: Efficient similarity search without separate index files
Scalable: Handles large datasets with proper indexing

Examples

SQLite Implementation

// Store a memory
store_memory(
  "User prefers Python for backend development", 
  "conversation", 
  0.8
)

// Search memories
search_memories("programming preferences", 5, true)

// Get memories via resource
// Access: memory://programming

PostgreSQL Implementation

// List available domains
list_memory_domains()
// Returns: ["default", "startup", "health"]

// Store memories in different domains
store_memory(
  "Series A funding closed at $10M",
  "startup",  // domain
  "meeting",   // source
  0.9         // importance
)

store_memory(
  "User has peanut allergy",
  "health",
  "medical_record",
  1.0
)

// Search within specific domain
search_memories("funding", "startup", 5)

// Get memories via resource
// Access: memory://startup/funding%20strategy

Components

SQLite Implementation

FastMCP: Python MCP server framework
SQLite: Structured metadata and text search fallback
FAISS: Vector similarity search
Ollama: Local embedding generation (optional)
Smart Chunker: Text processing for optimal retrieval

PostgreSQL Implementation

FastMCP: Python MCP server framework
PostgreSQL: Full database with metadata and vector storage
pgvector: Native PostgreSQL vector similarity search
Ollama: Local embedding generation (optional)
Domain Tables: Isolated memory contexts for better organization

Development

SQLite Version

pip install -r requirements.sqlite.txt
python src/sqlite_memory_server.py

PostgreSQL Version

pip install -r requirements.pgvector.txt
python src/postgres_memory_server.py

Docker

Docker support is fully functional with self-contained containers! Both SQLite and PostgreSQL versions run completely independently.

# Run pre-built images directly (recommended)
# SQLite version - replace './data' with your preferred data directory
docker run --rm -i -v ./data:/app/data cunicopia/local-memory-mcp:sqlite

# PostgreSQL version - replace './postgres_data' with your preferred data directory  
docker run --rm -i -v ./postgres_data:/var/lib/postgresql/data cunicopia/local-memory-mcp:postgres

Building from source (optional):

# Only needed if you want to build yourself
docker build -f Dockerfile.sqlite_version -t local-memory-mcp:sqlite_version .
docker build -f Dockerfile.postgres_version -t local-memory-mcp:postgres_version .

License

MIT License

Demo

See the local memory system in action:

Example 1

Example 2

Copy & paste — that's it

# Run immediately - no setup required!
docker run --rm -i -v ./memory-data:/app/data cunicopia/local-memory-mcp:sqlite

Quick Start

Recommended: Use Docker for the easiest setup! Skip all dependency management and get running in seconds.

Option 1: Docker (Recommended)

SQLite Version (simplest):

# Run immediately - no setup required!
docker run --rm -i -v ./memory-data:/app/data cunicopia/local-memory-mcp:sqlite

PostgreSQL Version (with domain segmentation):

# Run immediately - includes full PostgreSQL database!
docker run --rm -i -v ./postgres-data:/var/lib/postgresql/data cunicopia/local-memory-mcp:postgres

That's it! The containers are self-contained and handle all dependencies automatically.

Prerequisites

Docker (for containerized deployment) or Python 3.12+ (for local installation)
Ollama with nomic-embed-text model (optional but recommended for enhanced semantic search)

Ollama Setup (Optional but Recommended)

Ollama enables enhanced semantic search with vector embeddings. Without it, the system falls back to text-based search.

Installation:

macOS/Windows: Download installer from ollama.com/download
Linux: curl -fsSL https://ollama.com/install.sh | sh

Setup:

# Install the embedding model
ollama pull nomic-embed-text:v1.5

# Verify it's running (should show localhost:11434)
curl http://localhost:11434/api/tags

Claude Desktop Setup

Once you have the Docker containers ready (or local installation), connect to Claude Desktop by adding this to your MCP settings:

Docker Configuration (Recommended)

{
  "mcpServers": {
    "localMemoryMCP-SQLite": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "/path/to/your/memory-data:/app/data", "cunicopia/local-memory-mcp:sqlite"]
    },
    
    "localMemoryMCP-PostgreSQL": {
      "command": "docker", 
      "args": ["run", "--rm", "-i", "-v", "/path/to/your/postgres-data:/var/lib/postgresql/data", "cunicopia/local-memory-mcp:postgres"]
    }
  }
}

Volume Paths: Replace /path/to/your/memory-data and /path/to/your/postgres-data with any directory where you want to store your memories (e.g., ~/Documents/memory-data, /Users/yourname/my-memories, etc.)

Local Installation Configuration (Alternative)

Note: Only use if you cannot use Docker. Requires manual setup first (see Manual Installation).

{
  "mcpServers": {
    "localMemoryMCP": {
      "command": "bash",
      "args": ["/path/to/local-memory-mcp/run_sqlite.sh"]
    }
  }
}

Configuration

Common Environment Variables

OLLAMA_API_URL: Ollama endpoint (default: http://localhost:11434)
OLLAMA_EMBEDDING_MODEL: Model name (default: nomic-embed-text)
MCP_SERVER_NAME: Server name for MCP (default: Local Context Memory)

SQLite Specific

MCP_DATA_DIR: Data storage path (default: ./data)

PostgreSQL Specific

POSTGRES_HOST: Database host (default: localhost)
POSTGRES_PORT: Database port (default: 5432)
POSTGRES_DB: Database name (default: postgres)
POSTGRES_USER: Database user (default: postgres)
POSTGRES_PASSWORD: Database password (required)
DEFAULT_MEMORY_DOMAIN: Default domain for memories (default: default)

Manual Installation

⚠️ We strongly recommend using Docker instead - it handles all dependencies automatically. Use this section only if Docker is not available or you have specific requirements.

SQLite + FAISS (Simple, Local)

git clone https://github.com/cunicopia-dev/local-memory-mcp
cd local-memory-mcp
pip install -r requirements.sqlite.txt
python src/sqlite_memory_server.py

PostgreSQL + pgvector (Production, Scalable)

For Debian-based systems:

# Install PostgreSQL + pgvector
sudo apt install postgresql postgresql-contrib
sudo apt install postgresql-17-pgvector  # Adjust version as needed

# Change directory to where you downloaded the repo
cd /path/to/local-memory-mcp

# Set up database
# PLEASE NOTE: We create a user and basic password here, please change this if you want to host it locally
psql < sql/create_user.sql
psql -U postgres < sql/setup_database.sql

# Install Python dependencies
pip install -r requirements.pgvector.txt

# Configure connection (edit .env file)
cp .env.example .env

# Run server
python src/postgres_memory_server.py

For macOS:

# Install PostgreSQL and pgvector (Homebrew-based)
brew install postgresql@17
brew services start postgresql@17

# Link psql and other tools if needed
brew link --force postgresql@17

# Install pgvector extension (PostgreSQL must be running)
# This installs the extension into your local PostgreSQL environment
brew install pgvector

# OPTIONAL: If pgvector doesn't register properly, you can manually build it
# git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git
# cd pgvector
# make && make install

# PLEASE NOTE: We create a user and basic password here, please change this if you want to host it locally
psql < sql/create_user.sql

# Set up database
psql -U postgres -f sql/setup_database.sql

# Install Python dependencies
pip install -r requirements.pgvector.txt

# Configure connection (edit .env file)
cp .env.example .env

# Run server
python src/postgres_memory_server.py

⚠️ SECURITY CAUTION: Please go to sql/create_user.sql and create a more secure user and password, the ones listed are for example purposes only! Please protect your data and take your data security seriously.

Local Context Memory MCP

Table of Contents

Why This Matters

Choose Your Implementation

Tools & Capabilities

Available Tools

store_memory

update_memory

search_memories

list_memory_domains (PostgreSQL Only)

Available Resources

memory://query (SQLite)

memory://domain/query (PostgreSQL)

Available Prompts

summarize_memories

Architectures

SQLite + FAISS Implementation (Original)

PostgreSQL + pgvector Implementation (New)

Features

Common Features

SQLite + FAISS Specific

PostgreSQL + pgvector Specific

Examples

SQLite Implementation

PostgreSQL Implementation

Components

SQLite Implementation

PostgreSQL Implementation

Development

SQLite Version

PostgreSQL Version

Docker

License

Demo

Example 1

Example 2

Quick Start

Option 1: Docker (Recommended)

Prerequisites

Ollama Setup (Optional but Recommended)

Claude Desktop Setup

Docker Configuration (Recommended)

Local Installation Configuration (Alternative)

Configuration

Common Environment Variables

SQLite Specific

PostgreSQL Specific

Manual Installation

SQLite + FAISS (Simple, Local)

PostgreSQL + pgvector (Production, Scalable)

`store_memory`

`update_memory`

`search_memories`

`list_memory_domains` (PostgreSQL Only)

`memory://query` (SQLite)

`memory://domain/query` (PostgreSQL)

`summarize_memories`