Hipocampo

title: Hipocampo MCP emoji: 🧠 colorFrom: blue colorTo: purple sdk: docker pinned: false

⚠️ 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:

URL: https://alexbell1-hipocampo-mcp.hf.space/mcp

🧪 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.).

{
  "mcpServers": {
    "hipocampo": {
      "url": "https://alexbell1-hipocampo-mcp.hf.space/mcp",
      "type": "streamable-http"
    }
  }
}

Embedding model: sentence-transformers/all-MiniLM-L6-v2 (384 dims) via Hugging Face Inference API (free, no credit card required).

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 same NVIDIA NIM endpoint already used for embeddings. 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.

Real impact: If you call compress_hipocampo before every search_hipocampo → LLM round-trip, you save 200-800 tokens per interaction. At scale (hundreds of queries), this translates to meaningful cost reduction and faster responses.

🚀 Key Features

• Dual-Memory Architecture: Distinct storage layers for technical records (memoria_vectorial) and user profile data (memory_items), each utilizing 1024-dimensional embeddings.
• BIRE v3.7 (default): Hybrid search engine combining NVIDIA embeddings (1024d), query expansion, GIN trigram, and composite scoring — used by all MCP tools.
• SSC (experimental): Alternative four-phase progressive pipeline: Tag Router → pgvector Top-K → GIN Trigram → ILIKE Fallback.
• Logarithmic Checkpointing: Intelligently compresses historical memories based on time decay, shrinking 24-hour granular details into unified 90-day checkpoints.
• Automated Tagging Engine: A robust, Regex-based rule engine that autonomously categorizes and tags records upon persistence.
• Cross-System Vector Search: Unified semantic search across over 1,100 records for deep cross-referencing.
• Hybrid Prompt Compression (v4.0): Two-phase compression pipeline — extractive (sentence-level) for generic text and LLM summarization (via NVIDIA NIM) for technical/code content. Reduces prompt tokens by 20-50% while preserving critical information. Available as compress_hipocampo MCP tool.
• Memory Graph (v4.0): Directed graph of semantic relationships between memories. Link related records, navigate with BFS tree, find shortest paths. Available as link_hipocampo, graph_hipocampo, path_hipocampo MCP tools.
• Memory Hierarchy with Trigger-Based Prevention (v4.1): 🧠🧠 Three-level memory (episodic → semantic → automatic) inspired by human mnemonic consolidation. NEW: Tag memories with contextual triggers (trigger:php, trigger:chartjs, trigger:tomcat) — when the agent starts working in that context, it searches for matching automatica rules and reactivates past errors before making the same mistake. This mirrors the biological hippocampus: a partial cue (project + language) triggers full memory retrieval of the error and its solution. Automatic rules are permanent — never compressed, never deleted. set_nivel_hipocampo(id, nivel) + consolidate_hipocampo tools included.
• Code Immune System — Regression Protection (v4.2): 🛡️ Prevents agents from breaking code that was working. 3-step cycle: (1) Snapshot functional state before editing, (2) Verify after editing, (3) If something broke → create a permanent automatica rule capturing the exact cause, symptom, and fix. Uses immune economy: pre-change snapshots are cheap episodica (auto-compressed if no damage), post-break rules are permanent automatica. Pre-loaded with fragile file catalog — header.php, conexion.php, utils.php, auth.php, etc. Agents search trigger:regression trigger:<file> before every edit to learn what other agents broke before.
• Code RAG (v4.0): Index project source code (PHP, JS, TS, Python, SQL) as semantic embeddings. Search with search_code(query, language) — returns real code snippets with file paths and line numbers, not just summaries.
• Exponential Time Decay (v4.0): final_score = relevance × exp(-λ × days) with λ=0.05 configurable and 20% floor. Recent knowledge naturally outranks old memories.
• MMR Diversity Anti-Cluster (v4.3): Maximum Marginal Relevance post-fusion re-ranking prevents dense embedding clusters from monopolizing search results. Iteratively selects results that balance relevance with diversity: diversity_lambda × relevance - (1-diversity_lambda) × max_similarity_to_selected. Configurable in hipocampo_hybrid_config.json.
• Link Weight Decay (v4.3): Exponential weight decay on memory graph links (half-life 90 days). Links that aren't traversed lose strength over time; links <0.01 are pruned. graph_hipocampo() and path_hipocampo() auto-reinforce traversed links. New decay_hipocampo(dry_run) tool for graph maintenance. Columns: last_accessed, reinforced_at.
• Session Memory & Auto-Summarization: Session-isolated save/search. After 20+ saves, Hipocampo auto-generates a consolidated session summary in the background.
• Proactive Context Preloading: preload_context(project_path) extracts meaningful keywords from the project path, searches relevant memories, and returns a compressed summary — ideal for session start.
• Context Budget Awareness: compress_hipocampo auto-estimates token budget and adjusts k dynamically. budget_ratio parameter gives fine-grained control over output size.
• Auto-Linking: save_hipocampo(..., auto_link=True) auto-discovers semantically similar memories (>0.75 cosine) and creates similar edges in the memory graph.
• HNSW Auto-Recovery: hipocampo_health() checks the HNSW index on startup and auto-creates it if missing — no more manual CREATE INDEX commands.
• Model Context Protocol (MCP): Native integration via a FastMCP server with 25 tools, exposing seamless read/write capabilities to modern MCP clients (e.g., Claude Desktop, OpenCode).

⚡ Why PostgreSQL + pgvector (Not SQLite)?

You might wonder why Hipocampo uses PostgreSQL 17 with pgvector instead of a lighter stack like SQLite. The answer: hybrid search requires more than vector similarity alone.

Hipocampo's retrieval pipeline combines pgvector (HNSW) for semantic search, pg_trgm (GIN) for lexical expansion, and ILIKE for fallback — fused into a single weighted score. SQLite extensions like sqlite-vec offer vector search, but lack:

• GIN trigram indexes for fuzzy/partial matching
• Full-text + vector hybrid fusion in a single query
• Production-grade HNSW indexing with concurrent writes
• pg_trgm-based query expansion when embeddings alone are insufficient

With ~1,100+ records across two memory tables and growing, Hipocampo needs a database that scales without sacrificing retrieval quality. PostgreSQL + pgvector isn't "heavy" for the sake of it — it's the minimum viable stack to deliver the hybrid accuracy that BIRE and SSC require.

🎯 Use Cases

Error → Learn → Never Repeat (AI Agent Learning Loop)

Hipocampo enables AI agents to learn from mistakes across sessions using a simple cycle:

┌─ 1. SEARCH ─────────────────────────────┐
│  Before executing a command, the agent   │
│  searches Hipocampo for similar errors:  │
│  search_hipocampo("error <context>")     │
└───────────────────┬──────────────────────┘
                    │
┌─ 2. EXECUTE ──────▼──────────────────────┐
│  If match found → apply known solution   │
│  If not → attempt new approach           │
└───────────────────┬──────────────────────┘
                    │
┌─ 3. EVALUATE ─────▼──────────────────────┐
│  Did it fail? Capture:                   │
│  - error context & exit code             │
│  - what was attempted                    │
│  - what happened                         │
└───────────────────┬──────────────────────┘
                    │
┌─ 4. PERSIST ──────▼──────────────────────┐
│  save_hipocampo(                          │
│    content="Error X: tried Y, result Z", │
│    memory_type="decision",               │
│    code="error_<hash>",                  │
│    categories=["bugfix", "<tool>"]       │
│  )                                        │
└──────────────────────────────────────────┘

Real example: An agent tries flatpak install npm and fails. It saves the error to Hipocampo: "npm is a Node.js package manager, not a Flatpak package. Use npm directly." Next time the same command is attempted, the agent finds this record and knows the solution immediately — without repeating the mistake.

Over time, the agent's error knowledge base grows organically. Each failure makes future sessions smarter. This turns Hipocampo from a simple archive into a continuous learning system for AI agents.

🧠 Context-Aware Error Prevention (NEW v4.1) — Proactive, not Reactive

Going beyond reactive lear

…