Show & Tell: Hipocampo — Dual-Memory MCP System (11 tools: health, stats, dedup, checkpoint) #2909

🧠 Hipocampo — Dual-Memory System for AI Agents

Hipocampo is an open-source dual-memory persistence system built for AI agents. It combines PostgreSQL 17 + pgvector with NVIDIA NIM embeddings to give LLMs persistent, searchable memory across sessions.

Inspired by the human hippocampus, it stores both technical knowledge and user profiling data with Sparse Selective Caching (SSC) — a 4-phase progressive retrieval pipeline.

🔌 11 MCP Tools

Memory:

• search_hipocampo — hybrid semantic + lexical search
• save_hipocampo — persist technical memory (memoria_vectorial)
• profile_hipocampo — store user profile data (memory_items)

Self-Diagnosis:

• hipocampo_health — full system health check (PostgreSQL, NVIDIA API, disk, extensions)
• hipocampo_auto_repair — auto-fix detected issues

Performance:

• hipocampo_stats — query latency, score metrics, optimization tips
• hipocampo_tune — auto-adjust SSC thresholds based on real usage

Maintenance:

• hipocampo_dedup — detect and merge duplicate memories (exact + semantic)
• hipocampo_checkpoint — logarithmic compression of old memories
• hipocampo_maintenance — full cycle (repair → dedup → checkpoint → tune)

🚀 Quick Start

git clone https://github.com/carrasquelalex1/hipocampo.git
cd hipocampo
createdb hipocampo_db
psql -d hipocampo_db -c "CREATE EXTENSION vector; CREATE EXTENSION pg_trgm;"
psql -d hipocampo_db -f esquema.sql
pip install -r requirements.txt
python scripts/hipocampo_mcp_server.py

⚙️ Tech Stack

• PostgreSQL 17 + pgvector (768-dim embeddings)
• NVIDIA NIM (nv-embedqa-e5-v5)
• FastMCP (Python SDK)
• SSC: Tag Router → pgvector Top-K → GIN Trigram → ILIKE fallback

📊 Stats

• 750+ technical memories, 230+ profile records after dedup cleanup
• Hybrid search with configurable α=0.3 (30% vectorial + 70% lexical)
• Auto-maintenance cycle keeps the system healthy

🇪🇸 Hipocampo — Sistema de Memoria Dual para Agentes de IA

Hipocampo es un sistema de memoria dual open source para agentes de IA. Combina PostgreSQL 17 + pgvector con embeddings de NVIDIA NIM para darle a los LLMs memoria persistente y buscable a través de sesiones.

Inspirado en el hipocampo humano, almacena tanto conocimiento técnico como datos de perfil de usuario mediante Sparse Selective Caching (SSC) — un pipeline de recuperación progresiva en 4 fases.

🔌 11 Herramientas MCP

Memoria:

• search_hipocampo — búsqueda híbrida semántica + léxica
• save_hipocampo — guardar memoria técnica (memoria_vectorial)
• profile_hipocampo — almacenar datos de perfil (memory_items)

Autodiagnóstico:

• hipocampo_health — chequeo completo de salud (PostgreSQL, API NVIDIA, disco, extensiones)
• hipocampo_auto_repair — reparación automática de problemas detectados

Rendimiento:

• hipocampo_stats — métricas de latencia, scores y consejos de optimización
• hipocampo_tune — ajuste dinámico de umbrales SSC según uso real

Mantenimiento:

• hipocampo_dedup — detecta y fusiona recuerdos duplicados (exacto + semántico)
• hipocampo_checkpoint — compresión logarítmica de recuerdos antiguos
• hipocampo_maintenance — ciclo completo (reparar → dedup → checkpoint → tune)

🚀 Inicio Rápido

git clone https://github.com/carrasquelalex1/hipocampo.git
cd hipocampo
createdb hipocampo_db
psql -d hipocampo_db -c "CREATE EXTENSION vector; CREATE EXTENSION pg_trgm;"
psql -d hipocampo_db -f esquema.sql
pip install -r requirements.txt
python scripts/hipocampo_mcp_server.py

⚙️ Stack Tecnológico

• PostgreSQL 17 + pgvector (embeddings de 768 dimensiones)
• NVIDIA NIM (nv-embedqa-e5-v5)
• FastMCP (Python SDK)
• SSC: Tag Router → pgvector Top-K → GIN Trigram → fallback ILIKE

📊 Estadísticas

• 750+ recuerdos técnicos, 230+ registros de perfil (tras limpieza de duplicados)
• Búsqueda híbrida con α=0.3 configurable (30% vectorial + 70% léxica)
• Ciclo de auto-mantenimiento mantiene el sistema saludable

🔗 GitHub: https://github.com/carrasquelalex1/hipocampo
📖 Docs: https://github.com/carrasquelalex1/hipocampo/blob/main/docs/mcp-server-guide.md
🐍 Licencia MIT