brain-v42

Memoria persistente para agentes de codificación, servida a través de MCP.

brain-v42 ofrece a Claude Code, Codex y cualquier otro cliente MCP un segundo cerebro duradero: decisiones, aprendizajes, fragmentos de código, runbooks, ADRs, tickets y hojas de ruta de proyectos — almacenados en PostgreSQL, recuperados mediante búsqueda de texto completo + semántica con reranking, y consolidados cada noche por un pipeline de agentes.

• Conocimiento tipado, no un volcado de notas — una decisión registra su POR QUÉ y sus alternativas; un fragmento registra su intención; un runbook registra pasos ejecutables. Cada tipo tiene su propio ciclo de vida (cadenas de sustitución, aceptación de ADR, validación de aprendizajes).

• Ciclo de vida de sesión explícito — el usuario controla cada límite de sesión. Las sesiones capturan los artefactos que produjeron, y el cierre es a prueba de fallos: una sesión termina con conocimiento capturado o con una razón explícita de «nada que capturar», nunca en silencio.

• Búsqueda con ranking — búsqueda semántica con pgvector + FTS de PostgreSQL, fusionados y reordenados por un cross-encoder.

• Consolidación nocturna («dream») — un pipeline de agentes limpia enlaces huérfanos, fusiona duplicados, sintetiza aprendizajes y propone promociones, tras killswitches por fase que se distribuyen todos cerrados.

• Multiproyecto — enfoque por proyecto con revisiones compare-and-swap, hojas de ruta, tickets entre proyectos.

Arquitectura

Claude Code / Codex (MCP client)
       │ HTTP loopback :8765/mcp (production) · stdio (dev/fallback)
  brain-v42 (FastMCP)
       ├── SQLAlchemy async ─▶ PostgreSQL 16 + pgvector   (source of truth)
       ├── HTTP ─────────────▶ embedding endpoint :8003   (optional, pluggable)
       ├── HTTP ─────────────▶ :8003/rerank               (optional reranker)
       └── bolt ─────────────▶ Neo4j 5 Community          (relationship index, optional)

Transporte MCP: producción = bucle local HTTP http://127.0.0.1:8765/mcp; configuración predeterminada y dev/fallback = stdio.

PostgreSQL es la única fuente de verdad. Neo4j es una proyección desechable alimentada por un ledger relacional/outbox — siempre se puede reconstruir desde PostgreSQL, nunca al revés. La ruta canónica está activa en producción desde el 22 de julio de 2026; el diseño y la evidencia viven en docs/ARCHITECTURE.md y en el runbook del graph ledger.

Los embeddings son opcionales y conectables. El propio servidor es agnóstico al modelo: solo habla un contrato HTTP de tres rutas (POST /embed, POST /embed/query, POST /rerank) y degrada con elegancia cuando el endpoint no está disponible — brain_search cae en la búsqueda de texto completo, las escrituras persisten con un embedding NULL y se rellenan después. Cualquier servidor que implemente ese contrato funciona. La pila de referencia incluida (services/) sirve Qodo-Embed-1-1.5B como GGUF mediante llama.cpp en una GPU local. EMBEDDING_DIMENSION se elige en la instalación; cambiar de modelo más adelante implica volver a generar los embeddings del corpus (scripts/regen_embeddings.py).

Inicio rápido

git clone https://github.com/hawkixs/brain-v42 && cd brain-v42
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# 1. Local Neo4j secret (skip if you run without the graph)
install -d -m 0700 .secrets
read -rsp "Neo4j password (same value as NEO4J_PASSWORD in .env): " PW
(umask 0022; printf 'neo4j/%s\n' "$PW" > .secrets/neo4j-auth); unset PW

# 2. Databases (PostgreSQL 16 + pgvector, Neo4j)
docker compose up -d

# 3. Migrations
export POSTGRES_URL="postgresql+asyncpg://brain:REPLACE_WITH_PASSWORD@localhost:5433/brain"
BRAIN_ALEMBIC_ALLOW_PROD=1 alembic upgrade head

# 4. Run the MCP server (stdio)
python -m brain_v42.mcp.server

Conéctalo a Claude Code — el .mcp.json en la raíz del repositorio ya apunta al endpoint de bucle local HTTP de producción; para una configuración de desarrollo simple con stdio:

claude mcp add brain-v42 -- python -m brain_v42.mcp.server

BRAIN_ALEMBIC_ALLOW_PROD solo se requiere cuando el nombre de la base de datos es exactamente brain; mantenlo como una opción de un solo comando, nunca exportado de forma persistente. Alembic rechaza los parámetros de consulta del DSN; usa la forma simple anterior con host, puerto, usuario y contraseña presentes.

Herramientas MCP

Catálogo completo con firmas: docs/MCP_TOOLS.md.

El perfil de catálogo predeterminado es compact: las siete herramientas del ciclo de vida de sesión permanecen visibles, y cualquier otra herramienta se alcanza a través de dos puertas de enlace — brain_find_tool para descubrir, brain_call_tool para invocar. Establece BRAIN_MCP_PROFILE=native para exponer todas las herramientas directamente.

Sesiones

El usuario controla cada límite de sesión: start, resume, end y abandon son comandos explícitos, nunca inferidos por un hook, un agente o un cliente. Las sesiones capturan los artefactos duraderos que produjeron en un ledger exclusivo, y el cierre es a prueba de fallos: conocimiento capturado o una razón explícita de «nada que capturar», nunca silencio.

Después de 24 horas sin un heartbeat, una sesión abierta expone is_stale=true; el marcador se deriva, el estado persistente sigue siendo open, y solo la limpieza del servidor a los 7 días abandona una sesión sin un comando explícito del usuario.

El contrato completo del ciclo de vida (reglas de captura, semántica de enfoque, informe) vive en docs/MCP_TOOLS.md; el contrato es v4 y sigue evolucionando.

Configuración (.env)

# Required
POSTGRES_URL=postgresql+asyncpg://brain:REPLACE_WITH_PASSWORD@localhost:5433/brain

# Optional — semantic search and reranking
EMBEDDING_SERVICE_URL=http://localhost:8003
EMBEDDING_DIMENSION=1536
RERANKER_URL=http://localhost:8003

# Optional — relationship graph (safe defaults for a fresh environment)
GRAPH_ENABLED=false
GRAPH_LEDGER_WRITE_ENABLED=false

# Tool catalog profile
BRAIN_MCP_PROFILE=compact   # compact (default) or native

LOG_LEVEL=INFO

Nunca coloques MCP_HTTP_TOKEN ni MCP_HTTP_DREAM_TOKENS en el .env compartido: los tokens de portador viven en un archivo privado 0600 (~/.config/brain-v42/mcp-token.env), y la credencial del proyector de grafos en el suyo propio (~/.config/brain-v42/graph-projector.env). Referencia completa — cada variable, los archivos secretos privados, los preflights y los portones de despliegue: docs/OPERATIONS.md.

Modelo de confianza de red

El despliegue apunta a agentes personales en una LAN de confianza. MCP, PostgreSQL y Neo4j se vinculan a loopback; las métricas y la automatización usan loopback por defecto.

Topología de embeddings: producción/valor predeterminado = endpoint unificado local http://localhost:8003; deploy/dev-pc es una ruta de rollback/referencia superada.

El reranker comparte el endpoint unificado de embeddings :8003/rerank. Trata :8003 como expuesto a la LAN hasta que hayas comprobado el enlace real por ti mismo, y nunca lo expongas — ni el puerto MCP — a Internet. El código del repositorio por sí solo no demuestra un estado de firewall real.

Modo Dream

Pipeline de agente nocturno (scripts/dream.sh: scan → clean → connect → synth → promote → reorg) más trabajos del lado del servidor de extracción de tickets, curación de hojas de ruta y limpieza de sesiones. Cada fase mutante está tras un killswitch y todos los killswitches se distribuyen cerrados; el dry-run es el valor predeterminado distribuido. Cada fase se ejecuta con una lista de permitidos de herramientas MCP exacta. Detalles: docs/ARCHITECTURE.md y docs/OPERATIONS.md.

Estado de producción

El objetivo de migración del repositorio es la migración 045. Ninguna página de este repositorio demuestra una cabecera de esquema en vivo — mídela, no la leas aquí:

docker exec brain_v42_postgres psql -U brain -d brain -Atc "select version_num from alembic_version;"

El build en ejecución se nombra a sí mismo: GET /health devuelve version (la distribución instalada) y alembic_head (la revisión incluida), ambos medidos, nunca escritos a mano.

Desarrollo

pytest tests/unit -v                          # no PostgreSQL required
pytest --cov=brain_v42 --cov-report=term-missing
ruff check src/ tests/ && ruff format --check src/ tests/
mypy src/

• Stack: Python 3.12+, FastMCP 3.x, SQLAlchemy 2.0 async + asyncpg, Alembic, Pydantic 2, structlog.

• TDD es obligatorio — rojo, verde, refactor; los tests nunca se editan para que el código pase.

• Umbral de cobertura: 60% (CI bloquea por debajo).

• La cadena de herramientas de desarrollo está fijada exactamente (pip install -e ".[dev]") para que el entorno local siempre coincida con CI.

Estructura del proyecto

brain-v42/
├── src/brain_v42/
│   ├── config.py              # pydantic-settings — single config surface
│   ├── db/                    # SQLAlchemy engine + tables
│   ├── models/                # Pydantic models
│   ├── repositories/          # CRUD + FTS + pgvector + graph adapters
│   ├── services/              # business logic, embedding, reranker, dream, dedup
│   ├── metrics/               # sidecar + collector + cockpit endpoint
│   ├── automation/            # independent webhook/dedup runtime (:9201)
│   └── mcp/                   # FastMCP server + brain_*/dream_* tool handlers
├── tests/{unit,integration}
├── alembic/versions/          # migrations (shipped inside the wheel)
├── scripts/                   # operational CLIs (dream.sh, canaries, repair)
├── services/                  # GPU embedding service + shim + supervisor
├── deploy/                    # systemd units, per-host compose, install.sh
└── docs/                      # ARCHITECTURE, SCHEMA, MCP_TOOLS, OPERATIONS, runbooks

El grafo de módulos de nivel superior se mantiene acíclico en CI (scripts/check_module_layering.py): cualquier módulo puede extraerse a un servicio independiente sin arrastrar un ciclo consigo.

CI/CD

Etapas: lint → test → security → build. Barreras de seguridad: pip-audit, bandit, gitleaks, comprobaciones de pines de imágenes de contenedor. Las imágenes Docker se construyen y se publican en main; no hay etapa de despliegue — el rollout a un host es siempre un paso manual y fuera de banda. Los lanzamientos están impulsados por etiquetas: el raíl de release construye la wheel + sdist, demuestra que la wheel incluye sus migraciones, y adjunta ambos al release de GitHub.

Versionado

• La versión distribuida es 0.2.0, y se mantiene en 0.x a propósito: un 1.0.0 prometería una interfaz estable y un camino de retorno, y este proyecto no tiene ni lo uno ni lo otro todavía.

• No se promete una degradación sin pérdida, en ninguna versión. Dos migraciones rechazan su propio downgrade: 037 lanza una EXCEPTION de SQL en cuanto se perdería una captura de sesión, y 039 lanza una excepción a menos que el operador pase un opt-in explícito -x.

• Revertir un esquema es, por tanto, un procedimiento del operador con un runbook, nunca una garantía de versión — restaura desde una instantánea en su lugar.

Licencia

Código fuente: Apache-2.0.

Los pesos del modelo no están cubiertos por esa licencia, y esto no es una formalidad. El modelo de embedding de producción, Qodo/Qodo-Embed-1-1.5B, se publica bajo QodoAI-Open-RAIL-M — una licencia con restricciones basadas en el uso, no una permisiva. Ningún peso se almacena ni se distribuye mediante este repositorio: cada modelo se descarga de su host de origen en el momento de la compilación, por el operador, quien acepta los términos de cada modelo directamente de su editor. Consulta NOTICE antes de redistribuir cualquier cosa.