vector-memory-pg

Memoria técnica institucional para agentes IA — PostgreSQL + pgvector + embeddings de OpenAI + HTTP API + MCP + UI web.

Instalación • CLI • HTTP API • MCP • Seguridad • Arquitectura • Contribuir

Versión en inglés: README.en.md

Tu agente olvida todo al terminar la sesión. vector-memory-pg le da memoria.

Una base de conocimiento técnico consultable: decisiones de arquitectura, bugs conocidos, convenciones, restricciones y sesiones de trabajo. Separada por organización, proyecto y repositorio. Con control de vigencia, criticidad y búsqueda híbrida semántica + full-text.

Funciona desde cualquier directorio sin interferir con las variables de entorno de otros proyectos.

Instalación

npm install -g vector-memory-pg
vector-memory up              # PostgreSQL 17 + pgvector en Docker (:5433)
vector-memory quickstart      # configura ~/.vector-memory.env y aplica schema
vector-memory worker --open   # levanta el servidor y abre la UI en el navegador

Usa Tu Propio Agente De Código

Funciona con cualquier agente IA que soporte MCP. Un comando configura todo:

vector-memory init --tools claude-code    # o cursor, codex, opencode, openclaw

Eso ejecuta en un solo paso: crea .vector-memory.json, instala las instrucciones de uso en el archivo de config del agente, instala comandos slash (donde aplica) y muestra el snippet de configuración MCP.

Comandos slash disponibles: /vm-context, /vm-search, /vm-save, /vm-reflect, /vm-iterate

# Instalar solo las instrucciones de uso
vector-memory skills install --target opencode

# Instalar solo los comandos slash
vector-memory commands install --target claude-code

# Combinar múltiples agentes
vector-memory init --tools claude-code,cursor

Ver guías detalladas en docs/integrations/.

Ciclo completo

1. Guardar      save_memory / POST /memories
                → decisiones, bugs, patrones, restricciones

2. Buscar       search_memories / vector-memory search
                → híbrida: semántica (70%) + texto completo (20%)

3. Cronología   memory_timeline / GET /timeline / UI Timeline
                → historial cronológico agrupado por día

4. Reflexionar  reflect_memories / POST /reflect / UI Reflect
                → detecta contradicciones, duplicados y gaps con IA
                → devuelve sugerencias sin modificar nada

5. Deprecar     deprecate_memory / POST /memories/:id/deprecate
                → botón Deprecar en UI Reflect aplica sugerencias

6. Concluir     save_session_summary / POST /events/session-end
                → persiste el resumen de la sesión al finalizar

UI Web

Interfaz web local accesible en http://localhost:3010/ui:

• Search — búsqueda semántica con filtros de estado, tipo y límite
• Recientes — últimas N memorias ordenadas por fecha
• Timeline — historial agrupado por día con rango configurable
• Stats — totales, tamaño de DB y distribución por tipo
• Reflect — analiza memorias con IA; detecta contradicciones y gaps; botones para deprecar o guardar sugerencias directamente

vector-memory worker --open   # inicia el servidor y abre el navegador automáticamente

Arquitectura

Agente (Claude Code / OpenCode / Cursor)
        |
        |-- MCP (stdio)          save_memory, search_memories, reflect_memories ...
        |-- HTTP API (:3010)     GET /query, POST /reflect, /events/session-*
        `-- CLI                  vector-memory search, ingest, doctor ...
                |
                v
        PostgreSQL + pgvector
                |-- vector(1536) + HNSW   (búsqueda semántica)
                |-- tsvector + GIN        (full-text)
                `-- metadata + vigencia + criticidad
                        |
                        v
                OpenAI text-embedding-3-small

Características

Búsqueda

• Híbrida: similitud vectorial (70%) + PostgreSQL Full-Text Search (20%)
• Boosts por criticidad, estado y fecha de verificación
• search_memories_compact — salida reducida para minimizar context window
• get_memories — recupera memorias completas por lista de IDs
• memory_timeline — historial cronológico agrupado por fecha

Escritura desde MCP

• save_memory — guarda decisiones, bugs, patrones, restricciones; acepta auto_classify: true para inferir tipo, criticidad y tags con IA
• save_session_summary — resumen de sesión al finalizar
• update_memory, deprecate_memory, verify_memory

Análisis con IA (Reflect)

• reflect_memories — analiza memorias recientes con gpt-4o-mini
• Detecta contradicciones, duplicados y gaps en el conocimiento acumulado
• Devuelve hallazgos, memorias sugeridas y deprecaciones sugeridas
• Solo sugiere; nunca modifica nada
• La UI Reflect permite aplicar cada sugerencia con un solo clic

Ciclo de vida de sesión

• POST /events/session-start — inyecta contexto relevante al iniciar
• POST /events/post-tool-use — guarda observaciones automáticamente
• POST /events/session-end — persiste el resumen de la sesión

Metadatos y vigencia

• Separación por organization, project, repo_name, memory_type
• Estados: active, deprecated, superseded, archived
• Criticidad: low, normal, high, critical
• public_id legible: VM-000001, VM-000042...

Seguridad e ingesta

• Denylist de paths + detector de 8 patrones de secretos
• Modos block (default) y redact
• Dry-run y log de sanitización auditable
• Ingesta incremental de Markdown y JSONL con detección por mtime

Configuración aislada

• VECTOR_MEMORY_DATABASE_URL — var dedicada que no colisiona con otros proyectos
• ~/.vector-memory.env — config global de usuario, aplica desde cualquier directorio
• Content policy: @no-memory omite una memoria, <private>...</private> redacta bloques sensibles

Configuración rápida

# ~/.vector-memory.env  (config global, una sola vez)
VECTOR_MEMORY_DATABASE_URL=postgres://vector:vector@localhost:5433/vector_memory
OPENAI_API_KEY=sk-...

# Config MCP para tu agente
vector-memory mcp-config --target claude-code

Por seguridad, mcp-config omite secretos reales por defecto. Usa --show-secrets solo si necesitas imprimirlos en terminal.

{
  "mcpServers": {
    "vector-memory-pg": {
      "command": "vector-memory",
      "args": ["mcp"],
      "env": {
        "VECTOR_MEMORY_DATABASE_URL": "YOUR_VECTOR_MEMORY_DATABASE_URL",
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY"
      }
    }
  }
}

Herramientas MCP

Documentación

Contribuciones

Bugs, mejoras, documentación e ideas de arquitectura son bienvenidos. Revisa CONTRIBUTING.md antes de abrir un PR.

Créditos

Inspirado por el tutorial de Carlos Azaustre, evolucionado hacia una memoria técnica institucional para agentes IA.

Autor: Carlos Vallejos (cabupy)

Licencia

MIT. Ver LICENSE.