Hipocampo

What carrasquelalex1/hipocampo does

carrasquelalex1/hipocampo is a 🧠 Knowledge & Memory server for persistent agent context. It uses PostgreSQL 17 and pgvector to store technical memories in memoria_vectorial and personal profile information in memory_items. The two storage paths are exposed separately: technical records can carry memory types, codes, categories, sessions, hierarchy levels, and metadata, while profile records hold concise personal facts and optional extra text.

The server supports hybrid retrieval through search_hipocampo and its shorter alias, quick_hipocampo_search. Queries may combine free text with filters such as code, category, memory level, ID, session, and date. Results can be compact, full, or JSON, with optional scores and channel explanations. get_hipocampo provides deterministic lookup by a numeric ID, # or v form, or a vmi identifier.

How it works

Saving is non-blocking. A new technical memory is inserted immediately and remains searchable by text while its embedding is generated in the background. The background process can perform semantic duplicate checks, create similarity links, and audit contradictions. A near-identical trigram match prevents saving unless force is enabled.

Retrieval can use Sparse Selective Caching with progressive phases covering structured filters, vector search, lexical matching, and fallback text matching. The material also describes a hybrid retrieval engine using embeddings, lexical expansion, and trigram search. compress_hipocampo searches first and then applies extractive, LLM, or hybrid compression. preload_context performs a project-oriented retrieval and returns a compressed context summary.

Memory lifecycle controls include episodic, semantic, and automatic levels. Consolidation can promote older episodic records, while review can downgrade unused automatic rules. Checkpointing compresses older memories and can preserve snapshots for rollback. The memory graph supports typed links, graph traversal, and shortest-path searches.

Setup and configuration

A local installation is available through the repository's shell installer:

curl -fsSL https://raw.githubusercontent.com/carrasquelalex1/hipocampo/main/install.sh | bash

For unattended machines, the installer accepts --unattended. It is intended for Linux and macOS; Windows users need WSL2. The installer can set up PostgreSQL 17, pgvector, the database schema, a Python virtual environment, embedding options, MCP client configurations, and a weekly systemd maintenance timer. Options include an installation directory, external embedding API, disabling clients, disabling the timer, and disabling Ollama.

A hosted Streamable HTTP endpoint is also documented at https://alexbell1-hipocampo-mcp.hf.space/mcp. The hosted free-tier instance is ephemeral, so data may disappear after a restart or deployment. Run the server locally or connect an external database when persistence is required.

Tools and capabilities

carrasquelalex1/hipocampo includes tools for:

• Saving, profiling, updating, deleting, and directly retrieving memories.
• Searching, reranking, compressing, and preloading relevant context.
• Linking memories, exploring the graph, and finding paths between nodes.
• Indexing source files from PHP, JavaScript, TypeScript, Python, SQL, HTML, CSS, JSON, and YAML projects.
• Detecting contradictions, validating immune rules, and managing hierarchy levels.
• Running health checks, auto-repair, statistics, deduplication, checkpointing, rollback, tuning, and full maintenance.
• Registering, listing, and removing webhooks triggered by matching memory content or metadata.

Limitations and notes

Several operations are destructive. Merging duplicates, executing checkpoint compression, tuning thresholds, deleting memories, and full maintenance can modify or remove data; preview modes are available for deduplication and checkpointing, while tuning is explicitly irreversible. NVIDIA API access may be used for configured reranking or LLM compression, while the documented hosted setup uses the Hugging Face Inference API for embeddings. SSE remains available for compatibility, but Streamable HTTP is the recommended transport.

The repository is licensed under MIT.