Local Context Memory MCP

Local Context Memory MCP

¿Alguna vez quisiste la función de memoria de ChatGPT pero en todos tus LLMs y almacenada en tu propio hardware? ¿Odias que haya un límite en cuántos recuerdos puede almacenar ChatGPT y que no puedas segmentar tus recuerdos en diferentes dominios?

Aquí está tu solución.

Dale a cualquier asistente de IA memoria persistente e ilimitada que controles por completo.

Un sistema de memoria persistente listo para producción para agentes de IA que utiliza el Model Context Protocol (MCP). Funciona con Claude Desktop, cualquier cliente compatible con MCP, y te ofrece las funciones de memoria que estabas buscando.

Tabla de contenidos

• Por qué es importante
• Elige tu implementación
• Herramientas y capacidades
  • Herramientas disponibles
  • Recursos disponibles
  • Prompts disponibles
• Diagramas de arquitectura
  • Implementación SQLite + FAISS
  • Implementación PostgreSQL + pgvector
• Características
• Inicio rápido
  • Requisitos previos
  • Configuración de Ollama
• Configuración de Claude Desktop
• Ejemplos
• Componentes
• Configuración
• Desarrollo
  • Docker
• Instalación manual
• Demo
• Licencia

Por qué es importante

Problema tradicional de la IA: Los asistentes de IA olvidan todo entre conversaciones. Cada interacción comienza desde cero, lo que obliga a los usuarios a proporcionar repetidamente contexto sobre sus preferencias, proyectos e historial.

Solución: Local Context Memory le da a tu IA una memoria persistente y buscable que:

• 🧠 Recuerda entre sesiones - Preferencias del usuario, detalles de proyectos, historial de conversaciones
• 🎯 Encuentra contexto relevante - La búsqueda semántica muestra los recuerdos correctos en el momento adecuado
• 🏢 Organiza por dominio - Contextos separados para trabajo, salud, vida personal (PostgreSQL)
• 🔒 Permanece privado - Todos los datos se almacenan localmente bajo tu control
• ⚡ Funciona de inmediato - Compatibilidad directa con Claude Desktop y clientes MCP

Elige tu implementación

• SQLite + FAISS: Perfecto para uso personal, desarrollo e implementaciones simples
• PostgreSQL + pgvector: Listo para producción con segmentación de dominios y colaboración en equipo

Herramientas y capacidades

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

Herramientas disponibles

store_memory

Almacena nueva información en memoria persistente con indexación semántica automática.

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

update_memory

Modifica recuerdos existentes preservando la indexación de búsqueda.

• SQLite: update_memory(memory_id, content?, importance?)
• PostgreSQL: update_memory(memory_id, content?, importance?, domain?)
• Caso de uso: Actualizar información desactualizada o cambiar niveles de importancia

search_memories

Encuentra recuerdos relevantes mediante búsqueda semántica o por palabras clave.

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

list_memory_domains (Solo PostgreSQL)

Descubre dominios de memoria disponibles para un cambio de contexto organizado.

• Devuelve: ["default", "work", "health", "personal"]
• Caso de uso: Cambiar entre diferentes contextos de memoria

Recursos disponibles

memory://query (SQLite)

Búsqueda semántica rápida mediante patrón URI para recuperación simple de memoria.

memory://domain/query (PostgreSQL)

Búsqueda semántica con alcance de dominio para contextos de memoria aislados.

• Ejemplos:
  • memory://work/project deadlines
  • memory://health/medication schedule

Prompts disponibles

summarize_memories

Genera resúmenes inteligentes de colecciones de memoria recuperadas.

• Entrada: Lista de objetos de memoria
• Salida: Resumen estructurado que destaca patrones clave y perspectivas
• Caso de uso: Crear resúmenes de contexto para temas complejos

Arquitecturas

Implementación SQLite + FAISS (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

Implementación PostgreSQL + pgvector (Nueva)

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

Características

Características comunes

• Búsqueda semántica: Utiliza embeddings de Ollama para la recuperación inteligente de memoria
• Fragmentación inteligente: Divide automáticamente textos largos para mejores resultados de búsqueda
• Estándar MCP: Cumplimiento total del protocolo MCP para integración con Claude Desktop
• Listo para Docker: Implementación contenerizada simple con imágenes autocontenidas
• Búsqueda de respaldo: Respaldo automático a búsqueda de texto cuando la búsqueda vectorial no está disponible

Específico de SQLite + FAISS

• Almacenamiento local: Todo se ejecuta localmente con archivos SQLite + FAISS
• Configuración cero: No se requiere servidor de base de datos
• Portátil: Un solo directorio contiene todos los datos

Específico de PostgreSQL + pgvector

• Segmentación de dominios: Contextos de memoria separados (startup, salud, personal, etc.)
• Listo para producción: Cumplimiento ACID, acceso concurrente, soporte de replicación
• Operaciones vectoriales nativas: Búsqueda de similitud eficiente sin archivos de índice separados
• Escalable: Maneja grandes conjuntos de datos con indexación adecuada

Inicio rápido

Recomendado: ¡Usa Docker para la configuración más fácil! Omite toda la gestión de dependencias y ponte en marcha en segundos.

Opción 1: Docker (Recomendado)

Versión SQLite (la más simple):

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

Versión PostgreSQL (con segmentación de dominios):

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

¡Eso es todo! Los contenedores son autocontenidos y manejan todas las dependencias automáticamente.

Requisitos previos

• Docker (para implementación contenerizada) o Python 3.12+ (para instalación local)
• Ollama con el modelo nomic-embed-text (opcional pero recomendado para búsqueda semántica mejorada)

Configuración de Ollama (Opcional pero Recomendado)

Ollama permite una búsqueda semántica mejorada con embeddings vectoriales. Sin él, el sistema recurre a la búsqueda basada en texto.

Instalación:

• macOS/Windows: Descarga el instalador desde ollama.com/download
• Linux: curl -fsSL https://ollama.com/install.sh | sh

Configuración:

# 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

Configuración de Claude Desktop

Una vez que tengas los contenedores Docker listos (o la instalación local), conéctate a Claude Desktop añadiendo esto a tu configuración de MCP:

Configuración de Docker (Recomendado)

{
  "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"]
    }
  }
}

Rutas de volúmenes: Reemplaza /path/to/your/memory-data y /path/to/your/postgres-data con cualquier directorio donde quieras almacenar tus recuerdos (p. ej., ~/Documents/memory-data, /Users/yourname/my-memories, etc.)

Configuración de instalación local (Alternativa)

Nota: Úsalo solo si no puedes usar Docker. Requiere configuración manual primero (consulta Instalación manual).

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

Ejemplos

Implementación SQLite

// 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

Implementación PostgreSQL

// 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

Componentes

Implementación SQLite

• FastMCP: Framework de servidor MCP en Python
• SQLite: Metadatos estructurados y respaldo de búsqueda de texto
• FAISS: Búsqueda de similitud vectorial
• Ollama: Generación de embeddings local (opcional)
• Smart Chunker: Procesamiento de texto para recuperación óptima

Implementación PostgreSQL

• FastMCP: Framework de servidor MCP en Python
• PostgreSQL: Base de datos completa con metadatos y almacenamiento vectorial
• pgvector: Búsqueda de similitud vectorial nativa de PostgreSQL
• Ollama: Generación de embeddings local (opcional)
• Tablas de dominio: Contextos de memoria aislados para una mejor organización

Configuración

Variables de entorno comunes

• OLLAMA_API_URL: Endpoint de Ollama (predeterminado: http://localhost:11434)
• OLLAMA_EMBEDDING_MODEL: Nombre del modelo (predeterminado: nomic-embed-text)
• MCP_SERVER_NAME: Nombre del servidor para MCP (predeterminado: Local Context Memory)

Específico de SQLite

• MCP_DATA_DIR: Ruta de almacenamiento de datos (predeterminado: ./data)

Específico de PostgreSQL

• POSTGRES_HOST: Host de la base de datos (predeterminado: localhost)
• POSTGRES_PORT: Puerto de la base de datos (predeterminado: 5432)
• POSTGRES_DB: Nombre de la base de datos (predeterminado: postgres)
• POSTGRES_USER: Usuario de la base de datos (predeterminado: postgres)
• POSTGRES_PASSWORD: Contraseña de la base de datos (requerida)
• DEFAULT_MEMORY_DOMAIN: Dominio predeterminado para recuerdos (predeterminado: default)

Desarrollo

Versión SQLite

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

Versión PostgreSQL

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

Docker

¡El soporte de Docker es totalmente funcional con contenedores autocontenidos! Tanto la versión SQLite como la de PostgreSQL se ejecutan de forma completamente independiente.

# 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

Compilación desde el código fuente (opcional):

# 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 .

Instalación manual

⚠️ Recomendamos encarecidamente usar Docker en su lugar - maneja todas las dependencias automáticamente. Usa esta sección solo si Docker no está disponible o tienes requisitos específicos.

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 (Producción, Escalable)

Para sistemas basados en Debian:

# 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

Para 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

⚠️ ADVERTENCIA DE SEGURIDAD: Ve a sql/create_user.sql y crea un usuario y una contraseña más seguros; ¡los que aparecen son solo para fines de ejemplo! Protege tus datos y toma en serio la seguridad de tus datos.

Licencia

Licencia MIT

Demo

Mira el sistema de memoria local en acción:

Ejemplo 1

Ejemplo 2