Hipocampo MCP Server

Elimina un recuerdo del Hipocampo (memoria_vectorial) por su ID. Esta operación es irreversible. Una vez eliminado, el recuerdo no podrá recuperarse ni aparecerá en búsquedas futuras. Args: id: ID numérico del recuerdo a eliminar. Returns: Confirmación de eliminación.

Obtiene una memoria exacta por ID, sin pasar por el ranking. Acepta el ID numérico de memoria_vectorial (4039), con prefijo (#4039, v4039) o el ID de memory_items (vmi<uuid>). Es la vía determinista para "tráeme el recuerdo N": no compite con decenas de resultados. Args: id: ID de la memoria (numérico o vmi<uuid>). format: "compact" (default), "full" o "json". Returns: La memoria completa (compact muestra un fragmento de 800 chars; full/json incluyen todo el contenido y metadatos).

Intenta reparar automáticamente problemas detectados en el sistema. Reparaciones posibles: - Reiniciar PostgreSQL si está caído - Crear tablas faltantes desde esquema.sql - Verificar/configurar NVIDIA_API_KEY Returns: Reporte de reparaciones ejecutadas.

Gestiona el presupuesto de memoria (budget + tiering automático). 3 tiers: - HOT: embedding presente (memoria_vectorial con pgvector) - WARM: embedding=NULL (excluido de HNSW, sigue buscable léxicamente) - COLD: contenido movido a memoria_historica (fuera de búsqueda principal) Protecciones: automatica/semantica/critico/enlazadas → exemptas. Args: dry_run: True (default) = solo análisis. False = ejecuta tiering.

Comprime memorias antiguas usando checkpointing logarítmico. Con dry_run=True (default) es solo lectura — seguro, no modifica datos. Con dry_run=False es destructivo: comprime memorias antiguas de forma irreversible (las originales se eliminan tras comprimir). Idempotente: ejecutar múltiples veces no daña datos. Para ejecutar checkpoint como parte del ciclo completo de mantenimiento, usar hipocampo_maintenance (paso 3 del ciclo). Esta herramienta es para ejecución puntual o previsualización. Recomendado ejecutar periódicamente (semanal o mensual) para mantener el rendimiento del sistema. Args: dry_run: Si es True (default), solo muestra qué se comprimiría. Si es False, ejecuta la compresión (irreversible). Returns: Reporte del checkpointing ejecutado o simulado. Incluye: cantidad de registros comprimidos, espacio liberado.

Detecta y opcionalmente fusiona duplicados en las tablas de memoria. Con merge=False (default) es solo lectura — seguro de ejecutar, no modifica datos. Con merge=True es destructivo: consolida filas duplicadas en una sola, operación irreversible. Usar con precaución. Ejecutar primero sin merge para previsualizar. ¿Qué es un duplicado? Dos registros con alta similitud semántica (embedding + texto), por encima del umbral configurable (default 0.95). El reporte incluye: cantidad de duplicados encontrados, IDs afectados y resumen de fusión si se ejecutó merge. Para ejecutar dedup como parte del ciclo completo de mantenimiento, usar hipocampo_maintenance (paso 2 del ciclo). Esta herramienta es para uso puntual o previsualización antes del merge. Args: merge: Si es True, fusiona los duplicados encontrados (irreversible). Si es False (default), solo muestra análisis (seguro). Returns: Reporte de duplicados encontrados o fusionados.

Ejecuta un health check completo del sistema Hipocampo. Verifica: PostgreSQL, NVIDIA API, tablas, espacio en disco, extensiones. Returns: Reporte formateado del estado del sistema.

Ejecuta el ciclo completo de mantenimiento: 1. Health check → auto-repair si es necesario 2. Dedup → fusiona duplicados 3. Checkpoint → comprime memorias antiguas 4. Purge → limpia access logs antiguos (>30d) 5. Tune → ajusta thresholds según métricas Nota: hipocampo_budget y decay_hipocampo se ejecutan manualmente o via cron separado (son destructivos y requieren dry_run previo). Returns: Reporte consolidado del mantenimiento.

Muestra estadísticas de rendimiento del sistema Hipocampo. Analiza latencia de queries, métodos usados, scores promedios y da recomendaciones de optimización. Returns: Reporte de métricas y recomendaciones.

Ajusta automáticamente los thresholds y pesos del SSC basado en las métricas de rendimiento acumuladas. Es destructivo: modifica los thresholds y pesos de forma irreversible. Sin embargo, es idempotente: ejecutarlo múltiples veces converge al mismo resultado. Usar con precaución. Para solo ver estadísticas sin modificar nada, usar hipocampo_stats (solo lectura). Para ejecutar el ciclo completo de mantenimiento (que incluye tune como paso 5), usar hipocampo_maintenance. Recomendado ejecutar solo después de acumular suficientes métricas (al menos 100 consultas registradas). No usar si el sistema funciona correctamente sin degradación. Returns: Reporte de ajustes aplicados (nuevos thresholds y pesos).

Busca en el Hipocampo con carriles estructurados + semánticos. Es solo lectura (no modifica memorias). Devuelve una salida compacta por defecto: id, relevancia, code/fecha/nivel, un fragmento corto y el motivo. Sintaxis de query (opcional, se puede combinar con texto libre): code:opencode_session_forensics category:infraestructura,trigger:mcp nivel:automatica | type:decision | id:4039 | #4039 after:2026-10-01 | since:7d | before:today "frase exacta entre comillas" También acepta filtros por argumentos (code=, categories=, nivel=, memory_type=, ids=, created_after=, created_before=). Los argumentos explícitos tienen prioridad sobre la sintaxis de la query. Args: query: Texto libre y/o filtros. Puede ir vacío si se usan filtros. session_id: Filtra a una sesión concreta. rerank: "auto" (default; re-rankea solo si puede cambiar la decisión), "always" (TypeSafe/classifier, acotado) o "never". El booleano antiguo se acepta: True≈always, False≈never. k: Resultados a devolver (1-20, default 5). offset: Paginación (0-based). code: Filtro exacto por code. categories: Filtro por una o más categorías (coincidencia cualquiera). nivel: episodica | semantica | automatica. memory_type: event | decision | profile | ... ids: Lista de IDs numéricos de memoria_vectorial. created_after / created_before: Fechas ISO (YYYY-MM-DD) o "7d"/"today". include_pending: Si False, oculta filas cuyo embedding aún no está listo. rerank_top_k: Cuántos resultados re-rankear (3-20, default 8). rerank_budget_ms: Presupuesto HTTP del re-rank (100-5000 ms, default 800). format: "compact" (default), "full" (formato histórico) o "json". snippet_chars: Longitud del fragmento (80-2000, default 300). include_scores: Muestra el score numérico en la salida compacta. explain: Muestra el desglose de canales (vec/lex/struct). Returns: Texto formateado (compact/full) o JSON. Si no hay coincidencias, indica que la búsqueda fue válida pero sin resultados.

Actualiza un recuerdo existente en el Hipocampo (memoria_vectorial). Si se proporciona content, el embedding se regenera en BACKGROUND (no bloquea la llamada, igual que save_hipocampo): la fila conserva su embedding anterior hasta el backfill y la búsqueda semántica pasa al nuevo en cuanto esté listo. Los campos no proporcionados no se modifican. Args: id: ID numérico del recuerdo a actualizar. content: Nuevo texto del recuerdo (opcional). Si se provee, el embedding se regenera en background. memory_type: Nuevo tipo de memoria (opcional). Ej: "event", "decision". code: Código o etiqueta corta (opcional). categories: Nueva lista de categorías (opcional). meta_patch: Dict opcional que se FUSIONA sobre metadatos (sobrescribe solo las claves incluidas; el resto se conserva). Pensado para sincronizar md5/bytes sin escribir SQL a mano. Ej: {"md5": "6dbe9bdb...", "bytes": 52790} Returns: Confirmación de la actualización.

Agrega un directorio al watch list para auto-reindexación.

Lista los directorios configurados para auto-reindexación.

Elimina un directorio del watch list.

Registra un webhook que se dispara cuando se crea/modifica/elimina un recuerdo cuyo contenido o metadatos contengan el patrón dado. Args: pattern: Texto a buscar en contenido o metadatos del recuerdo. webhook_url: URL que recibirá un POST con event, id, content, metadatos. Returns: Confirmación con ID del watch creado.

Revisa reglas 'automatica' sin revisión en los últimos N días. Las reglas automatica son permanentes por diseño, pero pueden degradarse a 'semantica' si no han sido útiles (review_count=0) después de max_age_days. Con dry_run=True solo lista las reglas candidatas a degradación. Con dry_run=False las degrada a 'semantica' (no se borran, solo pierden inmunidad de compresión). Args: max_age_days: Edad máxima sin revisión antes de considerar degradación (default 30). dry_run: Si True, solo muestra qué se degradaría. Returns: Reporte de reglas encontradas.

Revisa memorias de conocimiento del oficio candidatas a decaer. Presenta memorias con domain_profile='infrastructure' que están cerca de su fecha límite de decay (150+ días sin acceso de los 180). El agente puede: - Refuerza (reinforce): resetea el contador de acceso - Permite decay: la memoria sigue el ciclo normal Ejecutar cada 3 meses via systemd timer o manualmente.

Busca código fuente indexado en Hipocampo (RAG). Similar a search_hipocampo pero filtra solo recuerdos de tipo code_snippet y devuelve fragmentos de código real con ubicación de archivo. Args: query: Consulta en lenguaje natural. k: Número de resultados (default 5, max 20). language: Filtrar por lenguaje (php, javascript, python, sql, etc.). Vacío = todos los lenguajes. Returns: Fragmentos de código relevantes con metadatos de archivo.

Compress retrieved memories using a hybrid approach (extractive + LLM). First searches Hipocampo (SSC v1.0), then compresses the top-k results: - method="extractive": sentence-level keyword relevance (fast, no API cost) - method="llm": summarization via NVIDIA NIM (highest quality, API cost) - method="hybrid" (default): uses LLM for technical/code content, extractive for generic text Use this tool BEFORE sending context to another LLM to reduce prompt size while preserving critical information. Args: query: Natural language search query. k: Number of memories to retrieve (default 5, max 20). method: Compression method: "hybrid" (default), "extractive", or "llm". target_token: Target token count (-1 = auto, based on content). include_metadata: Include per-memory details in output. budget_ratio: Scale factor for auto-estimated tokens (default 1.0). Returns: Compressed context as plain text with compression statistics. Includes: compressed text, original/compressed char counts, ratio, latency.

Consolidación jerárquica: migra memorias episódicas antiguas a semánticas. Busca recuerdos con nivel 'episodica' más antiguos que min_age_days y los promueve a 'semantica', opcionalmente comprimiendo su contenido. Args: min_age_days: Edad mínima en días para consolidar (default 7). dry_run: Si True, solo muestra qué se consolidaría. Returns: Reporte de la consolidación.

Detecta contradicciones semánticas de una memoria existente. Con TypeSafe activo (HIPOCAMPO_TYPESAFE=1): un Noul por candidato en una sola llamada, con probabilidad calibrada (umbral 0.7). Fallback: negation-probe embedding: embedea "AFIRMACIÓN: {contenido} — ¿Esto es FALSO según: ..." y compara con el embedding original. Si la distancia de la sonda de negación es MENOR que la del contenido original → señal de contradicción. Args: memory_id: ID numérico de la memoria en memoria_vectorial.

Aplica decaimiento temporal a enlaces del grafo Y memorias antiguas. ENLACES: peso exponencial, half-life 90 días. Elimina enlaces < 0.01. MEMORIAS: archiva episodica sin acceso ni protección a memoria_historica. Protecciones (nunca se archivan): - nivel = automatica o semantica - metadatos.critico = true - con enlaces entrantes en memory_links Args: dry_run: True (default) = solo lectura. False = ejecuta cambios. min_age_days: Edad mínima en días para considerar memoria candidata. Returns: Reporte del decaimiento aplicado.

Explora el grafo de memoria desde un nodo raíz. Args: node_id: ID del recuerdo raíz. Si es 0, lista todos los nodos con enlaces (vista general). depth: Profundidad de exploración (default 2, max 5). max_nodes: Máximo de nodos a mostrar (default 50). Returns: Árbol ASCII del grafo de memoria.

Indexa archivos de código fuente de un proyecto en Hipocampo (RAG). Escanea archivos PHP, JS, TS, Python, SQL, HTML, CSS, JSON, YAML, los divide en chunks significativos y los guarda como recuerdos con embedding para búsqueda semántica. La segunda corrida solo indexa archivos modificados (por mtime). Args: project_path: Ruta absoluta del proyecto a indexar. Si está vacía, usa el directorio actual. force: Si True, re-indexa todo aunque no haya cambios. Returns: Estadísticas de la indexación.

Crea un enlace entre dos recuerdos en el grafo de memoria. Args: source_id: ID del recuerdo origen (numérico: memoria_vectorial; string: memory_items). target_id: ID del recuerdo destino. relation_type: Tipo de relación. Valores comunes: "related" (default), "follow_up", "part_of", "references", "similar", "chain", "validates", "contradicts". weight: Peso de la relación (0.0 a 1.0, default 1.0). Returns: Confirmación del enlace creado.

Cambia el nivel jerárquico de un recuerdo. Niveles: - "episodica" — detalle completo, comprimible por checkpoint - "semantica" — conocimiento consolidado, protegido de compresión - "automatica" — regla permanente, nunca se comprime/checkpointea Args: id: ID del recuerdo. nivel: Nuevo nivel: "episodica", "semantica", o "automatica". Returns: Confirmación del cambio.

Encuentra el camino más corto entre dos recuerdos en el grafo de memoria. Args: from_id: ID del recuerdo origen. to_id: ID del recuerdo destino. max_depth: Profundidad máxima de búsqueda (default 5, max 10). Returns: Camino encontrado como secuencia de nodos.

Pre-load context for a project or workspace. Extracts relevant memories from the project path and returns them as a compressed summary. Use this when starting work on a known project to restore working context. Args: project_path: Absolute path to the project or workspace. If empty, uses current working directory. k: Number of relevant memories to retrieve (default 8, max 20). rerank: Opcional (TypeSafe). Re-ordena los resultados antes de comprimir, con un juicio de relevancia calibrado. Returns: Compressed context summary with project-relevant memories.

Guarda un dato de perfil personal en Hipocampo (memory_items). A diferencia de save_hipocampo (que guarda en memoria_vectorial técnica), esta herramienta guarda en memory_items, que está diseñado para datos personales: gustos, familia, preferencias, datos biográficos. Args: summary: Texto corto con el dato personal. Ej: "Al usuario le gusta el té de hierbas". extra: Información adicional en texto plano (opcional). categories: Categorías (opcional). Ej: ["personal_info", "gustos"]. Returns: Confirmación con el ID asignado.

Búsqueda rápida en el Hipocampo (alias corto de search_hipocampo). Es solo lectura — no modifica datos. Comportamiento y argumentos idénticos a search_hipocampo (filtros code:/category:/id:/after:, format compact/full/json, rerank auto/always/never).

Fuerza reindexación inmediata de un directorio (o todos los watch).

Restaura una memoria desde memoria_historica a memoria_vectorial. Reconstruye embedding automáticamente. La memoria vuelve al tier HOT. Args: historica_id: ID de la memoria en memoria_historica.

Revierte un checkpoint usando el snapshot guardado previamente. Busca el snapshot por ID y verifica qué IDs originales fueron comprimidos. Si los originales aún existen, reporta que no se necesita rollback. Si fueron eliminados, intenta restaurarlos. Args: snapshot_id: ID del snapshot [CHECKPOINT SNAPSHOT] guardado. Returns: Reporte de la operación de rollback.

Guarda un recuerdo en el Hipocampo (memoria_vectorial). INSERT inmediato y NO bloqueante: el embedding se genera en background (_finalize_save_bg) junto con dedup semántico, auto-link y auditoría de contradicciones. Hasta que el embedding se backfillea (~segundos), la memoria queda en tier WARM (embedding=NULL) y es recuperable por texto. Si ya existe un recuerdo casi idéntico (trigram), se advierte y se omite el guardado a menos que force=True. El dedup semántico (>0.9) corre en background y solo loguea — no bloquea. Args: content: Texto del recuerdo a guardar. memory_type: Tipo de memoria. Valores comunes: "event" (evento/experiencia), "decision" (decisión tomada), "profile" (dato personal). Por defecto: "event". code: Código o etiqueta corta para agrupar recuerdos (opcional). Ej: "documentacion", "bugfix", "feature", "setup". categories: Lista de categorías (opcional). Ej: ["python", "mcp", "infraestructura"]. session_id: Opcional. Identificador de sesión para aislar memorias. force: Si True, guarda incluso si existe un recuerdo muy similar. auto_link: Si True, busca recuerdos semánticamente similares (>0.75) y crea enlaces "similar" automáticamente. nivel: Nivel de memoria jerárquica: "episodica" (default) — detalle completo, comprimible, "semantica" — conocimiento consolidado, protegido, "automatica" — regla permanente, nunca se comprime. critico: Si True, la memoria NUNCA se olvida ni se archiva. Protección de por vida independiente del nivel. snapshot_for: Si se proporciona un ID de regla inmunológica, después de guardar se crea automáticamente un enlace "part_of" desde este recuerdo hacia esa regla. Esto permite que validate_immune_rule encuentre el snapshot pre-cambio vinculado. autor: Procedencia del recuerdo (capa de fuente, 2026-10-17): "agente" (default; lo escribiste tú en una sesión), "usuario" (dictado o habla directa del usuario), "catalogo" (entrada generada al indexar archivos). Viaja en metadatos.autor y aparece como línea 🔖 en la búsqueda, para distinguir reencontrar de consultar. Returns: Confirmación con el ID asignado.

Lista todas las memorias marcadas como conocimiento del oficio. Muestra id, preview, reusability, domain_profile y days since last access.

Elimina un enlace del grafo de memoria. Args: id: ID del enlace a eliminar (si se conoce). source_id: Si no se provee id, elimina por source+target+type. target_id: ID destino (requerido si no hay id). relation_type: Tipo de relación (opcional si no hay id). Returns: Confirmación de eliminación.

Elimina un webhook registrado por su ID. Args: id: ID del watch a eliminar. Returns: Confirmación de eliminación.

Valida una regla inmunológica (Nivel 4). Analiza una regla 'automatica' marcada como REGLA INMUNOLÓGICA: 1. Verifica snapshots pre-cambio vinculados en memory_links 2. Detecta reglas contradictorias sobre el mismo archivo/proyecto 3. Reporta reglas huérfanas (>30d sin enlaces entrantes) Args: rule_id: ID de la regla inmunológica a validar. Returns: Reporte de validación con recomendaciones.

Lista todos los webhooks registrados. Returns: Lista de watches con ID, patrón y URL.