carrasquelalex1/hipocampo

title: Hipocampo MCP
emoji: 🧠
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
---
Hipocampo
Dual-Memory System with Sparse Selective Caching
Persistent memory for autonomous AI agents · PostgreSQL 17 + pgvector · Hybrid Search · MCP Server
> **⚠️ Transport Note:** SSE transport is deprecated since MCP spec 2025-03-26.
> Hipocampo now uses **Streamable HTTP** (single endpoint /mcp) as the recommended remote transport.
> SSE (/sse) remains available for backward compatibility but will be removed in a future release.
🌐 MCP Server — Live on Hugging Face
Hipocampo runs as a **free MCP server** on Hugging Face Spaces. Connect from any MCP client:
**🧪 Interactive Playground:** Try saving and searching memories from your browser at https://alexbell1-hipocampo-mcp.hf.space/ — no registration or MCP client needed.
> **⚠️ Important:** The Hugging Face free tier is **ephemeral** — data is lost on restart/deploy. This instance is intended for testing only. For persistent storage, run Hipocampo locally (see Quick Start) or connect an external database (Neon, Supabase, etc.).
**Embedding model:** sentence-transformers/all-MiniLM-L6-v2 (384 dims) via **Hugging Face Inference API** (free, no credit card required).
⚡ Instalación Zero-Touch — Auto-Installer v6.0
> **Una sola línea.** La terminal hace todo: PostgreSQL + pgvector, embeddings, base de datos, venv, clientes MCP, servicio systemd con timer de mantenimiento automático.
> ### 🪟 ¿Usas Windows?
> install.sh es un script de **Linux/macOS**. En Windows necesitas **WSL2** (Windows Subsystem for Linux):
>
>
>
> Abre la terminal de WSL (Ubuntu), **actualiza los paquetes** y vuelve a ejecutar el instalador:
>
>
>
> **⚠️ En Windows puro (CMD/PowerShell) el instalador NO funciona.** Sin WSL2 verás errores como Package 'python3-venv' has no installation candidate o apt: command not found.
🚀 Instalar en 10 segundos
Máquinas sin interacción (VPS, contenedores):
🔄 Las 8 fases automáticas
| Fase | Qué instala | 🕐 |
|:----:|-------------|:--:|
| ① | Diagnóstico: OS, gestor de paquetes, RAM, disco | ~2s |
| ② | PostgreSQL 17 + pgvector (apt · dnf · pacman · brew) | ~15s |
| ③ | Base de datos + esquema: 10 tablas, HNSW + GIN, ownership | ~3s |
| ④ | Embeddings: Ollama local (qwen3-embedding:0.6b) o API externa | ~60s |
| ⑤ | Python .venv + pip + archivo .env | ~10s |
| ⑥ | **Clientes MCP**: OpenCode · Claude · Gemini/Antigravity · Cursor · VS Code · Windsurf | ~2s |
| ⑦ | Servicio systemd + **timer semanal** de mantenimiento automático | ~1s |
| ⑧ | Autodiagnóstico: health · save · search · cleanup | ~3s |
🛡️ Características del instalador
| | |
|:---|:---|
| ✅ **Idempotente** | Vuelve a ejecutarlo sin miedo — repara ownership, actualiza repo y configs |
| ✅ **6 clientes MCP** | OpenCode, Claude, Gemini/Antigravity, Cursor, VS Code, Windsurf |
| ✅ **Mantenimiento automático** | Timer semanal (domingo 03:00) con Persistent=true — catch-up si la PC estaba apagada |
| ✅ **Sin root** | Todo en ~/.local/share/hipocampo |
| ✅ **Opciones** | --unattended, --embed-api, --install-dir, --db-user, --no-clients, --no-timer, --no-ollama |
| ✅ **Desinstalación limpia** | bash uninstall.sh — para servicios, BD opcional, clientes, archivos |
| ✅ **Compilación desde fuente** | Fallback si el paquete pgvector no está en el repositorio |
---
---
**Hipocampo** is an advanced dual-memory persistence architecture designed for autonomous AI agents. By maintaining both technical knowledge and user profiling data across sessions, Hipocampo provides a reliable, stateful context that enables agents to learn, adapt, and scale efficiently.
Built on top of **PostgreSQL 17** with pgvector, it features **BIRE v3.7** — a hybrid retrieval engine combining semantic embeddings (1024d), lexical expansion, and GIN trigram search with dynamic score fusion. Also includes **Sparse Selective Caching (SSC)** as an experimental pipeline.
---
💡 Why Prompt Compression?
Hipocampo already reduces context through SSC (selective retrieval). But even the top-5 most relevant memories can consume 500-2000+ tokens when concatenated — a significant portion of any LLM's context window.
**Hybrid compression** adds a second reduction layer:
- **Extractive phase**: Removes redundant sentences (filtering by keyword relevance to your query). Reduces generic text by 30-50% instantly, with no API calls.
- **LLM phase**: Summarizes technical/code content using the configured embedding endpoint (Ollama local or NVIDIA NIM). Preserves all code, variable names, and syntax while dropping explanatory verbosity.
- **Combined**: 20-50% token reduction with near-zero quality loss. A 1500-token memory block becomes 750-1200 tokens — that's real savings on every LLM call.