brain-v42

Постоянная память для агентов кодирования, доступная через MCP.

brain-v42 предоставляет Claude Code, Codex и любому другому MCP-клиенту долговечный второй мозг: решения, наработки, фрагменты кода, runbook'и, ADR, тикеты и дорожные карты проектов — хранятся в PostgreSQL, находятся через полнотекстовый + семантический поиск с реранжированием и консолидируются каждую ночь конвейером агентов.

• Типизированные знания, а не свалка заметок — решение записывает своё «почему» и альтернативы; фрагмент записывает своё назначение; runbook записывает исполнимые шаги. Каждый тип имеет свой жизненный цикл (цепочки замены, принятие ADR, валидация наработок).

• Явный жизненный цикл сессии — пользователь владеет каждой границей сессии. Сессии захватывают созданные ими артефакты, и закрытие работает по принципу fail-closed: сессия завершается либо с захваченными знаниями, либо с явной причиной «нечего захватывать», но никогда молча.

• Поиск с ранжированием — семантический поиск pgvector + FTS PostgreSQL, объединяемые и переранжируемые кросс-энкодером.

• Ночная консолидация («dream») — конвейер агентов очищает осиротевшие ссылки, объединяет дубликаты, синтезирует наработки и предлагает продвижения, за пофазовыми killswitch, которые все поставляются выключенными.

• Мультипроектность — фокус на проекте с ревизиями compare-and-swap, дорожными картами, кросс-проектными тикетами.

Архитектура

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)

MCP-транспорт: продакшен = HTTP loopback http://127.0.0.1:8765/mcp; конфигурация по умолчанию и dev/fallback = stdio.

PostgreSQL — единственный источник истины. Neo4j — одноразовая проекция, питаемая реляционным журналом/outbox — её всегда можно пересобрать из PostgreSQL, но не наоборот. Канонический путь активен в продакшене с 22 июля 2026 года; дизайн и обоснование находятся в docs/ARCHITECTURE.md и runbook по графическому журналу.

Эмбеддинги опциональны и подключаемы. Сам сервер не зависит от модели: он говорит только на трёхмаршрутном HTTP-контракте (POST /embed, POST /embed/query, POST /rerank) и корректно деградирует, когда эндпоинт недоступен — brain_search переключается на полнотекстовый поиск, записи сохраняются с NULL-эмбеддингом и позже заполняются. Любой сервер, реализующий этот контракт, подходит. В комплекте эталонный стек (services/) обслуживает Qodo-Embed-1-1.5B в формате GGUF через llama.cpp на локальном GPU. EMBEDDING_DIMENSION выбирается при установке; смена модели позже означает пересоздание эмбеддингов корпуса (scripts/regen_embeddings.py).

Быстрый старт

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

Подключите его к Claude Code — .mcp.json в корне репозитория уже указывает на продакшен-HTTP-loopback эндпоинт; для простой stdio-настройки разработки:

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

BRAIN_ALEMBIC_ALLOW_PROD требуется только когда имя базы данных — ровно brain; оставьте его одноразовым явным согласием в команде, никогда не экспортируйте постоянно. Alembic отвергает параметры запроса DSN; используйте простую форму выше, где присутствуют хост, порт, имя пользователя и пароль.

MCP-инструменты

Полный каталог с сигнатурами: docs/MCP_TOOLS.md.

Профиль каталога по умолчанию — compact: семь инструментов жизненного цикла сессии остаются видимыми, а все остальные инструменты доступны через два шлюза — brain_find_tool для поиска и brain_call_tool для вызова. Установите BRAIN_MCP_PROFILE=native, чтобы раскрыть все инструменты напрямую.

Сессии

Пользователь управляет каждой границей сессии: start, resume, end и abandon — это явные команды, никогда не выводятся из поведения хука, агента или клиента. Сессии захватывают созданные ими долговечные артефакты в эксклюзивный журнал, и закрытие работает по принципу fail-closed: либо захваченные знания, либо явная причина «нечего захватывать», но никогда молчание.

Через 24 часа без heartbeat открытая сессия показывает is_stale=true; маркер вычисляется, постоянный статус остаётся open, и только серверная очистка через 7 дней может завершить сессию без явной команды пользователя.

Полный контракт жизненного цикла (правила захвата, семантика фокуса, бриф) находится в docs/MCP_TOOLS.md; контракт имеет версию v4 и всё ещё развивается.

Конфигурация (.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

Никогда не помещайте MCP_HTTP_TOKEN или MCP_HTTP_DREAM_TOKENS в общий .env: bearer-токены хранятся в приватном файле с правами 0600 (~/.config/brain-v42/mcp-token.env), а учётные данные проектора графа — в отдельном (~/.config/brain-v42/graph-projector.env). Полная справка — все переменные, приватные секретные файлы, проверки перед запуском и контрольные точки развёртывания: docs/OPERATIONS.md.

Модель доверия в сети

Развёртывание предназначено для персональных агентов в доверенной локальной сети. MCP, PostgreSQL и Neo4j привязываются к loopback; метрики и автоматизация по умолчанию работают на loopback.

Топология эмбеддингов: продакшен/по умолчанию = локальный единый эндпоинт http://localhost:8003; deploy/dev-pc — устаревший путь отката/эталонный путь.

Реранкер использует единый эндпоинт эмбеддингов :8003/rerank. Считайте :8003 доступным из LAN, пока вы сами не подтвердите актуальную привязку, и никогда не открывайте его — или MCP-порт — в Интернет. Код репозитория сам по себе не доказывает реальное состояние межсетевого экрана.

Режим Dream

Ночной конвейер агентов (scripts/dream.sh: scan → clean → connect → synth → promote → reorg) плюс серверные задачи извлечения тикетов, курирования дорожных карт и очистки сессий. Каждая изменяющая фаза находится за killswitch, и все killswitch поставляются выключенными; dry-run — поставляемый по умолчанию режим. Каждая фаза выполняется с точным разрешённым списком MCP-инструментов. Подробности: docs/ARCHITECTURE.md и docs/OPERATIONS.md.

Состояние продакшена

Целевая миграция репозитория — миграция 045. Ни одна страница этого репозитория не доказывает актуальную голову схемы — измерьте это, а не читайте здесь:

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

Работающая сборка называет себя сама: GET /health возвращает version (установленный дистрибутив) и alembic_head (ревизию, поставляемую с ним), оба значения измеряются, никогда не записываются вручную.

Разработка

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/

• Стек: Python 3.12+, FastMCP 3.x, SQLAlchemy 2.0 async + asyncpg, Alembic, Pydantic 2, structlog.

• TDD обязателен — красный, зелёный, рефакторинг; тесты никогда не редактируются, чтобы заставить код проходить.

• Минимальный порог покрытия: 60% (CI блокирует ниже).

• Инструментарий разработки зафиксирован точно (pip install -e ".[dev]"), поэтому локально всегда совпадает с CI.

Структура проекта

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

Граф модулей верхнего уровня принудительно ацикличен в CI (scripts/check_module_layering.py): любой модуль всё ещё можно выделить в отдельный сервис, не таская за собой цикл.

CI/CD

Этапы: lint → test → security → build. Защитные контрольные точки: pip-audit, bandit, gitleaks, проверки закрепления образов контейнеров. Docker-образы собираются и публикуются в main; стадии деплоя нет — развёртывание на хосте всегда выполняется вручную, как внешний этап. Релизы управляются тегами: сборочная линия релиза собирает wheel + sdist, проверяет, что wheel содержит миграции, и прикрепляет оба артефакта к релизу на GitHub.

Версионирование

• Поставляемая версия — 0.2.0, и она намеренно остаётся 0.x: 1.0.0 обещала бы стабильный интерфейс и путь назад, а у этого проекта пока нет ни того, ни другого.

• Без потерь даунгрейд не обещается ни в какой версии. Две миграции отказываются от собственного downgrade: 037 вызывает SQL EXCEPTION, как только может быть потерян захват сессии, а 039 вызывает исключение, пока оператор не передаст явное согласие -x.

• Поэтому откат схемы — это процедура оператора с инструкцией, а не гарантия версионирования — вместо этого восстанавливайтесь из снимка.

Лицензия

Исходный код: Apache-2.0.

Веса моделей не покрываются этой лицензией, и это не формальность. Продакшн-модель эмбеддингов, Qodo/Qodo-Embed-1-1.5B, опубликована под QodoAI-Open-RAIL-M — лицензией с ограничениями на использование, а не пермиссивной. Никакие веса не хранятся и не распространяются этим репозиторием: каждая модель загружается с вышестоящего хоста во время сборки оператором, который принимает условия каждой модели напрямую от её издателя. См. NOTICE перед распространением чего-либо.