Local Context Memory MCP

Um sistema de memória persistente pronto para produção para agentes de IA, oferecendo memória pesquisável entre sessões com busca semântica e suporte a múltiplos bancos de dados.

GitHub

Experimente este MCPPatrocinado

Documentação

Local Context Memory MCP

Já quis o recurso de memória do ChatGPT, mas em todos os seus LLMs e armazenado no seu próprio hardware? Já odiou o fato de haver um limite de quantas memórias o ChatGPT pode armazenar e de você não poder segmentar suas memórias em diferentes domínios?

Aqui está a sua solução.

Dê a qualquer assistente de IA memória persistente e ilimitada que você controla completamente.

Um sistema de memória persistente pronto para produção para agentes de IA usando o Model Context Protocol (MCP). Funciona com Claude Desktop, qualquer cliente compatível com MCP e oferece os recursos de memória que você sempre quis.

Sumário

Por que isso importa
Escolha sua implementação
Ferramentas e capacidades
Diagramas de arquitetura
- Implementação SQLite + FAISS
- Implementação PostgreSQL + pgvector
Recursos
Início rápido
- Pré-requisitos
- Configuração do Ollama
Configuração do Claude Desktop
Exemplos
Componentes
Configuração
Desenvolvimento
- Docker
Instalação manual
Demonstração
Licença

Por que isso importa

Problema tradicional de IA: Os assistentes de IA esquecem tudo entre conversas. Cada interação começa do zero, exigindo que os usuários forneçam repetidamente contexto sobre suas preferências, projetos e histórico.

Solução: O Local Context Memory dá à sua IA memória persistente e pesquisável que:

🧠 Lembra entre sessões - Preferências do usuário, detalhes de projetos, histórico de conversas
🎯 Encontra contexto relevante - A busca semântica traz as memórias certas no momento certo
🏢 Organiza por domínio - Contextos separados para trabalho, saúde, vida pessoal (PostgreSQL)
🔒 Permanece privado - Todos os dados armazenados localmente sob seu controle
⚡ Funciona imediatamente - Compatibilidade imediata com Claude Desktop e clientes MCP

Escolha sua implementação

SQLite + FAISS: Perfeito para uso pessoal, desenvolvimento e implantações simples
PostgreSQL + pgvector: Pronto para produção com segmentação de domínio e colaboração em equipe

Ferramentas e 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

Ferramentas disponíveis

`store_memory`

Armazene novas informações na memória persistente com indexação semântica automática.

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

`update_memory`

Modifique memórias existentes preservando a indexação de busca.

SQLite: update_memory(memory_id, content?, importance?)
PostgreSQL: update_memory(memory_id, content?, importance?, domain?)
Caso de uso: Atualize informações desatualizadas ou altere níveis de importância

`search_memories`

Encontre memórias relevantes usando busca semântica ou por palavras-chave.

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

`list_memory_domains` (Somente PostgreSQL)

Descubra domínios de memória disponíveis para alternância organizada de contexto.

Retorna: ["default", "work", "health", "personal"]
Caso de uso: Alterne entre diferentes contextos de memória

Recursos disponíveis

`memory://query` (SQLite)

Busca semântica rápida via padrão de URI para recuperação simples de memória.

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

Busca semântica com escopo de domínio para contextos de memória isolados.

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

Prompts disponíveis

`summarize_memories`

Gere resumos inteligentes de coleções de memória recuperadas.

Entrada: Lista de objetos de memória
Saída: Resumo estruturado destacando padrões e insights principais
Caso de uso: Crie resumos de contexto para tópicos complexos

Arquiteturas

Implementação 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

Implementação PostgreSQL + pgvector (Nova)

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

Recursos

Recursos comuns

Busca semântica: Usa embeddings do Ollama para recuperação inteligente de memória
Divisão inteligente: Divide automaticamente textos longos para melhores resultados de busca
Padrão MCP: Conformidade total com o protocolo MCP para integração com Claude Desktop
Pronto para Docker: Implantação simples em contêineres com imagens autossuficientes
Busca de fallback: Fallback automático para busca por texto quando a busca vetorial não estiver disponível

Específico do SQLite + FAISS

Armazenamento local: Tudo roda localmente com arquivos SQLite + FAISS
Zero configuração: Nenhum servidor de banco de dados necessário
Portátil: Um único diretório contém todos os dados

Específico do PostgreSQL + pgvector

Segmentação de domínio: Contextos de memória separados (startup, saúde, pessoal, etc.)
Pronto para produção: Conformidade ACID, acesso concorrente, suporte a replicação
Operações vetoriais nativas: Busca de similaridade eficiente sem arquivos de índice separados
Escalável: Lida com grandes conjuntos de dados com indexação adequada

Início rápido

Recomendado: Use Docker para a configuração mais fácil! Pule todo o gerenciamento de dependências e comece a usar em segundos.

Opção 1: Docker (Recomendado)

Versão SQLite (mais simples):

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

Versão PostgreSQL (com segmentação de domínio):

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

É isso! Os contêineres são autossuficientes e lidam com todas as dependências automaticamente.

Pré-requisitos

Docker (para implantação em contêineres) ou Python 3.12+ (para instalação local)
Ollama com modelo nomic-embed-text (opcional, mas recomendado para busca semântica aprimorada)

Configuração do Ollama (Opcional, mas Recomendado)

O Ollama permite busca semântica aprimorada com embeddings vetoriais. Sem ele, o sistema recorre à busca baseada em texto.

Instalação:

macOS/Windows: Baixe o instalador de ollama.com/download
Linux: curl -fsSL https://ollama.com/install.sh | sh

Configuração:

# 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

Configuração do Claude Desktop

Depois de ter os contêineres Docker prontos (ou instalação local), conecte-se ao Claude Desktop adicionando isto às suas configurações de MCP:

Configuração 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"]
    }
  }
}

Caminhos de volume: Substitua /path/to/your/memory-data e /path/to/your/postgres-data por qualquer diretório onde você queira armazenar suas memórias (por exemplo, ~/Documents/memory-data, /Users/yourname/my-memories, etc.)

Configuração de instalação local (Alternativa)

Nota: Use apenas se não puder usar Docker. Requer configuração manual primeiro (veja Instalação manual).

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

Exemplos

Implementação 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

Implementação 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

Implementação SQLite

FastMCP: Framework de servidor MCP em Python
SQLite: Metadados estruturados e fallback de busca por texto
FAISS: Busca de similaridade vetorial
Ollama: Geração de embeddings local (opcional)
Smart Chunker: Processamento de texto para recuperação ideal

Implementação PostgreSQL

FastMCP: Framework de servidor MCP em Python
PostgreSQL: Banco de dados completo com metadados e armazenamento vetorial
pgvector: Busca de similaridade vetorial nativa do PostgreSQL
Ollama: Geração de embeddings local (opcional)
Tabelas de domínio: Contextos de memória isolados para melhor organização

Configuração

Variáveis de ambiente comuns

OLLAMA_API_URL: Endpoint do Ollama (padrão: http://localhost:11434)
OLLAMA_EMBEDDING_MODEL: Nome do modelo (padrão: nomic-embed-text)
MCP_SERVER_NAME: Nome do servidor para MCP (padrão: Local Context Memory)

Específico do SQLite

MCP_DATA_DIR: Caminho de armazenamento de dados (padrão: ./data)

Específico do PostgreSQL

POSTGRES_HOST: Host do banco de dados (padrão: localhost)
POSTGRES_PORT: Porta do banco de dados (padrão: 5432)
POSTGRES_DB: Nome do banco de dados (padrão: postgres)
POSTGRES_USER: Usuário do banco de dados (padrão: postgres)
POSTGRES_PASSWORD: Senha do banco de dados (obrigatória)
DEFAULT_MEMORY_DOMAIN: Domínio padrão para memórias (padrão: default)

Desenvolvimento

Versão SQLite

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

Versão PostgreSQL

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

Docker

O suporte a Docker é totalmente funcional com contêineres autossuficientes! As versões SQLite e PostgreSQL rodam completamente de forma independente.

# 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

Compilando a partir do código-fonte (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 .

Instalação manual

⚠️ Recomendamos fortemente usar Docker em vez disso - ele lida com todas as dependências automaticamente. Use esta seção apenas se o Docker não estiver disponível ou se você tiver requisitos específicos.

SQLite + FAISS (Simples, 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 (Produção, Escalável)

Para sistemas baseados em 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

⚠️ AVISO DE SEGURANÇA: Por favor, vá para sql/create_user.sql e crie um usuário e senha mais seguros; os listados são apenas para fins de exemplo! Proteja seus dados e leve a segurança dos seus dados a sério.

Licença

Licença MIT

Demonstração

Veja o sistema de memória local em ação:

Exemplo 1

Example 1

Exemplo 2

Example 2

Local Context Memory MCP

Documentação

Local Context Memory MCP

Sumário

Por que isso importa

Escolha sua implementação

Ferramentas e capacidades

Ferramentas disponíveis

store_memory

update_memory

search_memories

list_memory_domains (Somente PostgreSQL)

Recursos disponíveis

memory://query (SQLite)

memory://domain/query (PostgreSQL)

Prompts disponíveis

summarize_memories

Arquiteturas

Implementação SQLite + FAISS (Original)

Implementação PostgreSQL + pgvector (Nova)

Recursos

Recursos comuns

Específico do SQLite + FAISS

Específico do PostgreSQL + pgvector

Início rápido

Opção 1: Docker (Recomendado)

Pré-requisitos

Configuração do Ollama (Opcional, mas Recomendado)

Configuração do Claude Desktop

Configuração Docker (Recomendado)

Configuração de instalação local (Alternativa)

Exemplos

Implementação SQLite

Implementação PostgreSQL

Componentes

Implementação SQLite

Implementação PostgreSQL

Configuração

Variáveis de ambiente comuns

Específico do SQLite

Específico do PostgreSQL

Desenvolvimento

Versão SQLite

Versão PostgreSQL

Docker

Instalação manual

SQLite + FAISS (Simples, Local)

PostgreSQL + pgvector (Produção, Escalável)

Licença

Demonstração

Exemplo 1

Exemplo 2

`store_memory`

`update_memory`

`search_memories`

`list_memory_domains` (Somente PostgreSQL)

`memory://query` (SQLite)

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

`summarize_memories`