DecisionsSearch 🔍

Servidor de Memoria Híbrido para Agentes de IA — un servidor MCP con memoria compartida persistente (Neo4j + Qdrant) y un investigador autónomo de errores CI/CD que encuentra causas raíz y propone correcciones.

🇧🇷 Leia em Português

Qué es DecisionsSearch

Los agentes de IA de codificación lo olvidan todo en cuanto termina una sesión. La siguiente sesión —la tuya o la de un compañero— vuelve a derivar el mismo contexto, vuelve a litigar las mismas decisiones y repite errores que el equipo ya solucionó una vez. Los pipelines de CI/CD tienen el mismo punto ciego: ocurren errores, se trian manualmente y se pierde la conexión entre "este error" y "el PR que lo causó".

DecisionsSearch es una capa de memoria persistente y consultable que se sitúa entre tus agentes de IA y un grafo de conocimiento. Proporciona a los agentes tres cosas que no tienen por sí solos:

1. Memoria duradera entre sesiones — las decisiones, reglas de negocio, patrones de código e historial de PRs sobreviven al cierre de la ventana de chat. Neo4j almacena las relaciones (qué implementa qué, qué reemplazó a qué); Qdrant permite la búsqueda semántica sobre todo ello.

2. Un vocabulario estructurado para "qué vale la pena recordar" — no un volcado de transcripción en bruto, sino categorías tipadas (regla de negocio, decisión arquitectónica, patrón de código, registro de PR, episodio de tarea) que siguen siendo útiles meses después.

3. Investigación autónoma de errores — apunta tu CI/CD al webhook de DecisionsSearch, y encuentra los PRs sospechosos, ejecuta un agente de codificación para investigar la causa raíz, y puede abrir un PR de corrección por sí mismo.

Related MCP server: Memory-MCP

Cuándo usarlo

• Estás ejecutando Claude Code (u otro agente compatible con MCP) sobre una base de código que tocas repetidamente, y estás cansado de reexplicar la misma arquitectura y reglas en cada sesión.

• Múltiples agentes/desarrolladores trabajan en la misma base de código y necesitan una fuente de verdad compartida para por qué las cosas son como son, no solo qué hace el código.

• Quieres que tu CI/CD haga un triaje de primera pasada sobre los errores antes de que un humano los revise.

No lo uses para: un script puntual, un prototipo desechable, o como reemplazo de tu documentación/wiki real — DecisionsSearch complementa los documentos estructurados, no los reemplaza (ver archivos .decisionssearch/ más abajo).

Inicio rápido

Prerrequisitos

• Python >= 3.11

• uv (recomendado) o pip

• Docker (para Neo4j + Qdrant en modo completo)

Instalar

git clone https://github.com/Renzo-Tognella/DecisionsSearch.git
cd DecisionsSearch
uv sync

Configurar

cp .env.example .env
cp config/decisionssearch.yaml.example config/decisionssearch.yaml

Edita .env con tus claves API y config/decisionssearch.yaml para tu configuración.

Ejecutar

Modo completo (Neo4j + Qdrant, recomendado — búsqueda más rica, recorrido de grafos):

# Start infrastructure
docker compose up -d

# Bootstrap vector collection (idempotent — safe to re-run)
uv run python -m scripts.bootstrap_qdrant

# Start server (HTTP + MCP on port 8000)
uv run decisionssearch

El servidor HTTP/MCP actual usa la composición completa y requiere Neo4j + Qdrant. El campo mode se conserva para compatibilidad de configuración; establecer mode: light no activa actualmente una ruta de servidor solo JSONL. JSONL se usa para la zona de aterrizaje, instantáneas y estado operativo local; el benchmark tiene un backend local explícito separado.

Verificar

# MCP endpoint responds (406 without proper MCP headers is expected — it means the route is alive)
curl http://localhost:8000/api/health   # real health path lives under /api
curl http://localhost:8000/mcp/

Conectando tu agente

Local, stdio (lo más simple para uso personal):

{
  "mcpServers": {
    "decisionssearch": {
      "command": "uv",
      "args": ["--directory", "/path/to/DecisionsSearch", "run", "decisionssearch-mcp"]
    }
  }
}

Local o remoto, HTTP (necesario si el servidor ya se ejecuta como un proceso persistente, p.ej. mediante uv run decisionssearch):

{
  "mcpServers": {
    "decisionssearch": { "url": "http://localhost:8000/mcp" }
  }
}

Coloca esto en el .mcp.json de un proyecto (a nivel de proyecto) o en tu configuración MCP global. Los servidores MCP solo se detectan cuando se inicia una sesión — después de añadir o cambiar esta configuración, abre una nueva sesión de agente en ese proyecto en lugar de esperar que las herramientas aparezcan a mitad de sesión.

Memoria a nivel de proyecto

Para las herramientas de memoria, project es opcional. Cuando se omite, DecisionsSearch usa el nombre de la raíz del repositorio Git (o la carpeta actual para un espacio de trabajo sin Git) como la partición del proyecto. Las nuevas memorias reciben ese valor de proyecto, y memory.query/memory.find_duplicates filtran Qdrant y Neo4j por él antes del ranking híbrido y la fusión RRF. Establece DECISIONSSEARCH_PROJECT cuando el servidor se inicia fuera del espacio de trabajo o cuando un despliegue necesita una partición explícita.

Esta es una partición lógica de memoria, no un límite de autenticación. El orden de resolución es:

1. DECISIONSSEARCH_PROJECT, cuando está configurado;

2. un argumento project explícito, útil para importaciones y trabajos por lotes;

3. el nombre de la raíz del repositorio Git;

4. el nombre de la carpeta actual cuando no existe una raíz Git.

Omitir project es el flujo de trabajo de agente recomendado. El valor resuelto se escribe con la memoria y se pasa a cada rama de recuperación. Una consulta primero filtra el proyecto en el libro mayor canónico, Qdrant y Neo4j, luego realiza recuperación densa, dispersa y estructural, fusión RRF y reranking opcional.

Cómo funciona la memoria

DecisionsSearch no trata una transcripción, diff o embedding como una memoria por sí mismo. Una memoria es conocimiento tipado y duradero con un proyecto, evidencia, contexto y una razón para seguir siendo útil después de la tarea actual.

workspace → project tag → raw event → sanitization → extraction
         → admission gates → proposal/approval → canonical ledger
         → outbox → Qdrant search projection

La ruta de escritura es deliberadamente selectiva:

• memory.ingest_raw almacena la fuente sanitizada en la zona de aterrizaje y pide al extractor candidatos tipados;

• la cadena de admisión requiere un proyecto y evidencia, verifica duplicados o refinamientos, valida el contexto específico de la categoría y evalúa el peso;

• con el libro mayor canónico habilitado, el agente crea una propuesta con una vista previa antes/después, diff de campos, evidencia y preview_hash;

• un operador o política de confianza aprueba la propuesta; la aplicación usa cabezas esperadas (CAS) y crea una revisión inmutable, cabeza, linaje y evento de bandeja de salida;

• el materializador publica la cabeza activa en Qdrant de forma idempotente. Qdrant es un índice de recuperación derivado, nunca la fuente de verdad.

El modelo canónico separa la identidad del contenido: MemoryFamily es la memoria lógica estable, MemoryRevision es una versión inmutable y MemoryHead apunta a la versión publicada para un ámbito y rama. Evidencia, alias, relaciones, ventanas de validez y eventos de auditoría permanecen consultables. Actualizar un título o resumen, por lo tanto, crea una nueva revisión en lugar de borrar silenciosamente el historial.

En las lecturas, el proyecto resuelto se aplica antes de la generación de candidatos. Los embeddings densos encuentran similitud semántica, la recuperación dispersa preserva términos técnicos exactos y el grafo aporta contexto estructural. Estas listas clasificadas se combinan mediante RRF; la activación por propagación opcional, la puntuación compuesta y el reranking luego refinan los candidatos. Una puntuación de relevancia alta es una señal de recuperación, no una prueba de que una afirmación sea cierta.

Para el ciclo de vida completo, el modelo de datos, el aislamiento de proyectos y los límites operativos, consulta docs-public/relatorio_memoria.md, ARCHITECTURE.md y el PDF público docs-public/relatorio_resultados.pdf.

Documentos públicos

• docs-public/instalacao.md — instalación y operación compatibles;

• docs-public/relatorio_memoria.md — ciclo de vida de la memoria y particionamiento de proyectos;

• docs-public/relatorio_resultados.md — evidencia reproducible y límites actuales;

• docs-public/instalacao.pdf y docs-public/relatorio_resultados.pdf — versiones PDF visuales.

Usando DecisionsSearch en el Día a Día: El Conjunto de Habilidades

Conectar el servidor MCP le da a tu agente más de 40 herramientas en bruto (memory.query, memory.pr.create, graph.project.create, ...) — potentes, pero no algo que quieras invocar manualmente cada vez. skills-memory/ incluye un conjunto de 13 habilidades de agente que envuelven esas herramientas en un flujo de trabajo:

Instala con decisionssearch-init en un proyecto nuevo; el conjunto incluye su propio README, una plantilla canónica que sigue cada habilidad y un archivo de prueba de conjunto dorado por habilidad (más una prueba de enrutamiento consolidada entre habilidades) — consulta skills-memory/README.md.

Modos de Uso

Modo 1: Memoria Personal (Local)

Ejecuta DecisionsSearch localmente. Tu agente de IA se conecta mediante MCP stdio o HTTP (ver arriba).

El servidor local usa la misma composición completa que el servidor compartido. Para una regresión reproducible sin infraestructura, usa el backend local explícito del benchmark en lugar de tratar JSONL como un almacén de memoria canónico.

# config/decisionssearch.yaml
mode: full
data_dir: data

El modo completo (Neo4j + Qdrant) proporciona recorrido de grafos y consultas híbridas vectoriales+estructurales.

Modo 2: Memoria Compartida de Equipo (Servidor)

Despliega DecisionsSearch en un servidor. Los agentes de todos los miembros del equipo leen/escriben en la misma base de conocimiento.

# On your server
uv run decisionssearch --host 0.0.0.0 --port 8000

Los miembros del equipo apuntan sus agentes al endpoint MCP compartido:

{
  "mcpServers": {
    "decisionssearch": { "url": "https://your-domain.example/mcp" }
  }
}

Las sesiones de agente de todos contribuyen memorias. El trabajo de escaneo diario ingiere automáticamente PRs y tarjetas de GitHub, construyendo un grafo de conocimiento compartido de las decisiones, patrones e historia arquitectónica del equipo.

Modo 3: Investigador Autónomo de Errores

Configura en config/decisionssearch.yaml:

agent:
  provider: codex          # opencode | codex | claude | zai | openrouter
  timeout: 600
  codex:
    model: gpt-4o
    api_key: ${OPENAI_API_KEY}

safety:
  min_confidence: 0.7
  max_auto_fixes_per_hour: 3
  blocked_paths:
    - auth/
    - security/
    - .env

notifications:
  slack:
    enabled: true
    webhook_url: ${SLACK_WEBHOOK_URL}

Apunta tu pipeline de CI/CD para enviar errores:

# GitHub Actions example
curl -X POST https://your-domain.example/api/webhook/errors \
  -H "Content-Type: application/json" \
  -H "X-Signature: $(echo -n "$body" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET")" \
  -d '{
    "error_type": "RuntimeError",
    "error_message": "Null pointer in UserService",
    "stack_trace": "at UserService.java:42\nat Controller.java:15",
    "service": "api",
    "environment": "production"
  }'

DecisionsSearch:

1. Ingerirá el error y encontrará qué archivos están afectados

2. Buscará PRs que modificaron recientemente esos archivos (sospechosos)

3. Ejecutará un agente de codificación para investigar la causa raíz

4. Si la confianza es suficientemente alta, creará un PR de corrección

5. Notificará al equipo vía Slack

Categorías de Memoria

Cada nodo de memoria tiene una category que determina qué campos son requeridos y aplicados por las puertas de admisión antes de ser aceptado en el grafo:

Las relaciones entre MemoryItems pasan por dos APIs distintas y validadas — no las mezcle:

• PR → memoria (memory.pr.link_memory): IMPLEMENTS, EVIDENCES, MODIFIES.

• memoria → memoria (memory.link): RELATED_TO, DEPENDS_ON, REFINES, DEPRECATES, CONFLICTS_WITH, EVOLVES_FROM.

Sustituir una regla o decisión es memory.deprecate(memory_id, replaced_by, rationale), no un enlace manual — propone (new)-[:DEPRECATES]->(old) y se aplica solo tras la aprobación del operador.

Herramientas MCP

El servidor expone más de 40 herramientas MCP. Categorías clave:

Referencia de configuración

Toda la configuración en config/decisionssearch.yaml. Variables de entorno mediante ${VAR:default}.

Consulte config/decisionssearch.yaml.example para la referencia completa con todas las opciones.

Arquitectura

El código de la aplicación reside directamente en src/ (src/domain, src/application, src/infrastructure, src/interfaces y src/bootstrap). El empaquetado asigna esa disposición física al espacio de nombres público estable decisionssearch.*.

Consulte ARCHITECTURE.md para obtener documentación técnica detallada con diagramas que cubren:

• Pipeline de ingesta de memoria (admisión de 5 puertas)

• Resolución de proyectos y filtrado por proyecto primero

• Ciclo de vida del libro mayor canónico, aprobación, revisión y bandeja de salida

• Pipeline de búsqueda híbrida (fusión RRF + activación por propagación)

• Flujo de investigación de errores (trabajador agente + puertas de seguridad)

• Modelo de datos de grafos

• Topologías de despliegue

Consulte LIMITATIONS.md para conocer las brechas de implementación actuales, su evidencia y la ruta propuesta para resolverlas.

Captura de memoria posterior al commit

El hook versionado .githooks/post-commit recopila HEAD, los archivos modificados, el PR abierto para la rama actual (cuando gh está disponible) y la sesión de DECISIONSSEARCH_SESSION_FILE o .decisionssearch/session.md. Envía ese contexto al LLM con una instrucción explícita para verificar conocimiento duradero antes de crear memoria. no_memory es un resultado válido, por lo que los cambios triviales no se fuerzan a la memoria. Los candidatos aceptados pasan las puertas de admisión y la captura es idempotente por commit + PR + sesión.

Instálelo una vez desde la raíz del repositorio:

uv run python -m scripts.install_git_hooks

El hook se ejecuta en segundo plano y es de fallo abierto, por lo que un fallo de OpenRouter, GitHub, Qdrant o Neo4j nunca bloquea un commit. Para probar de forma síncrona:

DECISIONSSEARCH_COMMIT_MEMORY_HOOK_SYNC=1 \
DECISIONSSEARCH_SESSION_FILE=.decisionssearch/session.md \
git commit -m "my change"

Los agentes que ya tienen el contexto pueden llamar a memory.capture_commit con session_context, commit_sha y los metadatos del PR. Para diagnósticos, ejecute uv run python -m scripts.post_commit_memory_hook --repo . --dry-run.

Desarrollo

# Install dev dependencies
uv sync --group dev

# Run tests
uv run pytest tests/ -q --ignore=tests/e2e

# Lint
uv run ruff check .

# E2E tests (requires running infrastructure)
RUN_E2E=1 uv run pytest tests/e2e -q

Licencia

MIT