Hipocampo

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

Hipocampo: Dual-Memory System with Sparse Selective Caching

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

🚀 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.
• Model Context Protocol (MCP): Native integration via a FastMCP server, exposing seamless read/write capabilities to modern MCP clients (e.g., Claude Desktop, OpenCode).

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

⚙️ How to configure your agent

To enable this behavior, you need to instruct your agent to use the cycle above. This is done by adding instructions to the agent's configuration file, depending on the client:

Minimal example for AGENTS.md / CLAUDE.md:

## Error Learning Cycle

1. Before running any command, search: `search_hipocampo("error <command> <context>")`
2. If a similar error is found, apply the documented solution and skip the failing attempt
3. If the command fails (exit code != 0, timeout, "error"/"failed" in output):
   - Save to Hipocampo: `save_hipocampo(content="Error: {stderr[:500]}. Attempt: {what was tried}. Result: {what happened}.", memory_type="decision", code="error_<hash>", categories=["bugfix", "<language/tool>"])`

💡 Tip: For MCP-native agents (OpenCode, Claude Code), Hipocampo tools are available directly. For others, use the HTTP endpoint or CLI scripts.

Other use cases

• Persistent user profile: Remember preferences, configs, and personal data across sessions
• Project state tracking: Keep context on ongoing projects, decisions made, and pending tasks
• Cross-session knowledge: Build on previous work without repeating context

🛠️ Quick Start

Prerequisites

• PostgreSQL 17+ (with pgvector and pg_trgm extensions enabled)
• Python 3.13+
• NVIDIA API Key (for nvidia/nv-embedqa-e5-v5 embeddings) — or Hugging Face API Key for sentence-transformers/all-MiniLM-L6-v2 (free via HF Inference API)

Installation

# 1. Clone the repository
git clone https://github.com/carrasquelalex1/hipocampo.git
cd hipocampo

# 2. Setup the PostgreSQL Database
createdb hipocampo_db
psql -d hipocampo_db -c "CREATE EXTENSION vector; CREATE EXTENSION pg_trgm;"
psql -d hipocampo_db -f esquema.sql

# 3. Initialize Python Environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 4. Environment Configuration
cp .env.example .env
# Edit .env with your DB_HOST, DB_USER, and NVIDIA_API_KEY

Basic Usage

Hipocampo provides specialized scripts to interact with the core engine:

# Perform a search using BIRE v3.7 (modern, recommended)
python3 scripts/hipocampo_search.py "query term"

# Perform a search using SSC v1.0 (experimental, legacy)
python3 scripts/hipocampo_ssc_search.py "query term"

# Compress older memories using Logarithmic Checkpointing
python3 scripts/hipocampo_checkpoint.py --dry-run
python3 scripts/hipocampo_checkpoint.py --force

🧠 System Architecture

The core of Hipocampo is backed by a relational and vector hybrid design:

hipocampo_db (PostgreSQL 17 + pgvector + pg_trgm)
├── memoria_vectorial (Technical Knowledge)
│   ├── Columns: contenido (text), metadatos (jsonb), embedding (vector 1024d)
│   └── Indexes: HNSW (cosine similarity, 1024d), GIN (trigram)
├── memory_items (User Profile & Events)
│   ├── Columns: memory_type (profile|event|decision), summary, embedding, extra
│   └── Indexes: HNSW (cosine similarity, 1024d), GIN (trigram)
├── memory_categories (Classification Taxonomy)
├── category_items (M:N Mapping)
└── resources (Referenced Assets & URLs)

BIRE v3.7 — Hybrid Search Engine

BIRE (Búsqueda Integrada por Relevancia Expansiva) is the default search engine used by all MCP tools. It combines vector and lexical search with dynamic score fusion:

1. Query Expansion — Expands terms using synonyms and stemming before search.
2. Vector Search — NVIDIA embeddings (1024d) cosine similarity across both tables.
3. GIN Trigram — Lexical expansion when vector confidence is low.
4. Composite Scoring — Weighted fusion of vector + lexical scores with adaptive cutoff.

An SSC (Sparse Selective Caching) pipeline is also available as an experimental alternative:

1. Phase 1: Tag Router – Classifies the query intent (profile vs. technical) and dynamically assigns weights.
2. Phase 2: PGVector Top-K – Semantic search across both tables. Execution halts here if confidence ≥ 70%.
3. Phase 3: GIN Trigram – Lexical expansion via Trigram indexing if semantic confidence is < 70%.
4. Phase 4: ILIKE Scan – Final fallback full-table scan triggered only if confidence falls < 40%.

🔌 MCP Server Integration

Hipocampo includes a fully functional FastMCP server, allowing LLM agents to autonomously read and write memories.

Available MCP Tools

Memory Operations:

• search_hipocampo(query, session_id?): Unified semantic and lexical search (auto-records metrics). Optionally filter by session.
• quick_hipocampo_search(query): Shorthand alias for rapid queries.
• save_hipocampo(content, memory_type, code, categories, session_id?): Persist data into the technical memory store (memoria_vectorial). Supports optional session isolation.
• profile_hipocampo(summary, extra, categories): Store personal or event-driven user data (memory_items).

CRUD Operations:

• update_hipocampo(id, content?, memory_type?, code?, categories?): Update an existing memory. Regenerates embedding if content changes.
• delete_hipocampo(id): Permanently delete a memory by ID.

Self-Diagnosis & Auto-Repair (Fase 1):

• hipocampo_health(): Full system health check (PostgreSQL, NVIDIA API, disk, extensions).
• hipocampo_auto_repair(): Automatically repairs detected issues (restart PostgreSQL, create missing tables).

Performance Optimization (Fase 2):

• hipocampo_stats(): Query performance metrics, latency analysis, and optimization recommendations.
• hipocampo_tune(): Auto-adjusts BIRE/SSC thresholds and hybrid weights based on real usage data.

Memory Maintenance (Fase 3):

• hipocampo_dedup(merge): Detects and merges duplicate memories (exact + semantic via cosine similarity).
• hipocampo_checkpoint(dry_run): Logarithmic checkpointing to compress old memories.
• `hipocampo

…