BrainCore

BrainCore

Evidence-first enterprise memory lifecycle for AI infrastructure.

BrainCore extracts, preserves, scores, audits, and retrieves operational knowledge from incidents, coding sessions, chat messages, and monitoring data, building a lifecycle-controlled knowledge graph that AI agents can query through CLI and MCP surfaces.

Production launch measurements, April 2026: 26,966 facts · P50 71.6 ms · P95 85.2 ms with vector stream disabled · fact-evidence coverage 98.52%

What It Does · Features · Quick Start · What Ships · Architecture · Benchmarks · MCP Integration · Configuration

What It Does

BrainCore processes operational artifacts and automatically:

1. Archives incidents, sessions, and artifacts with integrity checksums
2. Extracts structured facts using deterministic parsing plus LLM semantic analysis
3. Consolidates recurring patterns into actionable memories and playbooks
4. Publishes knowledge as searchable, queryable data

All knowledge is stored in PostgreSQL with pgvector, enabling four core retrieval streams (SQL + full-text + vector + temporal) plus optional graph-path retrieval with Reciprocal Rank Fusion.

Quality Standard

BrainCore is maintained as a public, client-visible engineering artifact. Every public change is expected to be reviewed at the level of production software:

• Documentation, tests, migrations, and benchmark evidence must agree in

the same change set.

• Public numeric claims must be backed by benchmarks/claims-to-evidence.yaml

or a committed benchmark artifact.

• Lifecycle admin changes preserve native truth. Suppression and retirement are

recall overlays, not destructive edits to fact, memory, procedure, event, or working-memory rows.

• Routine work should land through pull requests with required GitHub Actions

checks, not direct pushes to main.

• If CI fails, the follow-up should make the root cause and verification clear

instead of papering over the failure.

• Private hosts, home paths, tokens, and deployment-only details must stay out

of tracked public files.

Features

• Source ingestion: incident notes plus deterministic parsers for Claude Code, Codex, Codex shared memory, Discord, Telegram, Grafana, personal memory, assistant memory exports, Asana task exports, Git commits, and curated project documentation
• Hybrid retrieval: Structured SQL + FTS + vector similarity + temporal expansion, with optional graph path search, fused with RRF (k=60)
• Trust classes: deterministic, corroborated_llm, single_source_llm, human_curated
• Enterprise memory lifecycle overlay: Suppress or retire recall targets without destroying native evidence, with append-only feedback, score, and audit trails
• Context recall audit: Records retrieved, injected, and omitted memory packages for evaluation and controlled rollout
• Project scoping: Facts, memories, and episodes auto-tagged to projects via service mapping
• Quality gate: SHA256 fingerprint dedup, secret redaction, and assertion-class validation
• Local-first LLM: Uses vLLM (OpenAI-compatible); Claude CLI fallback requires explicit operator opt-in
• Risk review queue: semantic truncation, prompt-injection heuristics, redaction hits, and high-risk fact kinds are queued for human review
• Parallel nightly pipeline: Automated archive-extract-consolidate-publish cycle with parallel extractors and health gating
• Eval framework: Gold-set benchmark with precision, recall, and fact-evidence coverage metrics
• MCP-ready retrieval and admin layer: Python retrieval library plus a minimal FastMCP example server for downstream read tools and trusted lifecycle administration
• Deferred web app: The browser/admin dashboard is the next upgrade path; this release is CLI/MCP-first

Quick Start

The fastest supported way to try BrainCore on a fresh clone is:

1. Install Bun and Python dependencies.
2. Start PostgreSQL with pgvector.
3. Apply the schema migrations with bun src/cli.ts migrate.
4. Run the retrieval smoke benchmark to prove the repo wiring works.
5. Start the example MCP server or query the retrieval library directly.

Requirements

• Bun 1.1+
• Python 3.11+
• PostgreSQL 15+ (tested on 16)
• Docker or a local PostgreSQL instance with pgvector enabled

1. Install dependencies

bun install
python -m venv .venv
source .venv/bin/activate
pip install 'psycopg[binary]>=3.1' psycopg-pool pyyaml numpy requests pgvector pydantic 'mcp[cli]>=1.0'

2. Start PostgreSQL with pgvector

docker compose -f examples/docker-compose.yml up -d
sleep 5
cp .env.example .env
$EDITOR .env
# Optional: set BRAINCORE_EMBED_AUTH_TOKEN if your /embed endpoint requires auth.
set -a && . ./.env && set +a

3. Apply migrations

The supported launch path is bun src/cli.ts migrate.

bun src/cli.ts migrate

The migration runner connects with BRAINCORE_POSTGRES_DSN directly. It does not require the psql binary on the application host. Applied migrations are recorded in preserve.schema_migration; existing deployments with a complete schema are baselined into the ledger instead of re-running data rewrites.

If the PostgreSQL client is installed, you can sanity-check the open-source schema shape like this:

psql "$BRAINCORE_POSTGRES_DSN" \
  -c "SELECT count(*) FROM pg_tables WHERE schemaname='preserve';"

Expected result on a fresh clone: 50-table preserve schema.

4. Run the smoke benchmark

export BRAINCORE_TEST_DSN="$BRAINCORE_POSTGRES_DSN"
python benchmarks/run_retrieval.py
python benchmarks/run_grounding.py

This auto-loads benchmarks/seed_smoke.sql if preserve.fact is empty and writes:

• benchmarks/results/2026-04-09-retrieval.json
• benchmarks/results/2026-04-09-grounding.json

Those files are smoke-regression artifacts. They prove the pipeline is wired correctly. They are not the same thing as the live-deployment benchmark artifacts used for the public metrics.

5. Query BrainCore directly

From Python:

import os
from psycopg_pool import ConnectionPool
from mcp.memory_search import memory_search

pool = ConnectionPool(conninfo=os.environ["BRAINCORE_POSTGRES_DSN"])
result = memory_search(pool, query="docker restart loop", limit=5)
print(result["results"][0]["title"])

Or start the example MCP server:

python -m examples.mcp_server.server

See [examples/mcp_server/README.md](examples/mcp_server/README.md) for Claude Desktop and Inspector configuration.

Why It Exists

Most operational knowledge dies in one of four places:

• The incident note that never gets revisited.
• The chat thread that solved the problem but was never normalized.
• The coding session that found the root cause but never made it into a

runbook.

• The monitoring alert that contained the first signal but not the final

explanation.

Traditional RAG setups index documents. BrainCore tries to preserve knowledge and control its lifecycle without erasing evidence. That changes the design:

• Artifacts are archived before they are interpreted.
• Facts carry provenance and temporal validity windows.
• Weak facts can still be searchable without being allowed to promote

into durable memory.

• Consolidation produces patterns and playbooks rather than just

embeddings over raw text.

• Lifecycle status can suppress or retire bad recall targets while the

underlying evidence remains available for audit and rollback.

The result is a system that can answer questions like "what changed, when, why, and how confident are we?" rather than only "which chunk of text had similar words?"

What Ships In This Repo

| Path | What it is | Why it matters | |---|---|---| | src/ | Bun CLI and write path | Owns archive, extract, consolidate, publish, health, maintenance, project lifecycle, and enterprise memory lifecycle administration | | mcp/ | Python retrieval and lifecycle library | Owns read-side hybrid retrieval, lifecycle overlay filtering, trusted admin writes, and typed request/response models | | sql/ | Schema migrations | Defines the open-source preserve schema and launch hardening fixes | | benchmarks/ | Smoke + production benchmark artifacts | Gives you reproducible proof and a claim-binding gate | | examples/mcp_server/ | Reference stdio MCP server | Shows how to expose the reference retrieval tool surface through FastMCP without pretending the repo ships a hardened remote MCP appliance | | cron/ | Nightly automation | Encodes the archive → extract → consolidate → publish cadence | | scripts/pre-push-gate.sh | Sanitization gate | Blocks hostnames, private paths, secrets, and private project leakage | | tests/ and src/__tests__/ | Launch smoke tests | Verifies imports, migrations, and open-source schema shape |

What does not ship:

• A hosted control plane
• A general-purpose agent framework
• A browser/admin dashboard; the web app is the next upgrade path after this

CLI/MCP lifecycle release

• The larger downstream operational vault MCP deployment
• A Docker image or GHCR publish flow

Architecture

BrainCore uses the observatory metaphor as a teaching scaffold, not as a branding costume.

• An artifact is the photographic plate. BrainCore preserves it first so

later extractors can re-read it without losing the original evidence.

• Deterministic extraction is the first look through the eyepiece: the

obvious signals you can recover without model inference.

• Semantic extraction is the fainter second pass: useful, but never

allowed to erase the direct observation.

• Trust classes are magnitudes. The brighter the source, the more

aggressively BrainCore can promote it into durable memory.

• The four core retrieval streams are the four axes of the fix.

BrainCore aligns them with RRF so SQL, text, vector, and time each contribute without any one stream pretending to be the whole sky. Graph-path retrieval is an opt-in fifth signal for deployments that have populated and reviewed memory edges.

Benchmark Methodology

BrainCore keeps smoke-regression and production-corpus measurements separate on purpose.

Production proof

| Scope | Metric | Value | Source | |---|---|---:|---| | Production corpus | facts | 26,966 | benchmarks/results/2026-04-09-retrieval-production.json | | Production corpus | P50 latency with vector stream disabled | 71.6 ms | benchmarks/results/2026-04-09-retrieval-production.json | | Production corpus | P95 latency with vector stream disabled | 85.2 ms | benchmarks/results/2026-04-09-retrieval-production.json | | Production corpus | fact-evidence coverage | 98.52% | benchmarks/results/2026-04-09-grounding-production.json |

These are the public headline numbers.

Smoke proof

| Scope | Metric | Value | Source | |---|---|---:|---| | Smoke fixture | facts | 9 | benchmarks/results/2026-04-09-retrieval.json | | Smoke fixture | canonical queries | 12 | benchmarks/results/2026-04-09-retrieval.json | | Smoke fixture | relevance at 10 | 41.67% | benchmarks/results/2026-04-09-retrieval.json | | Smoke fixture | grounding rate | 55.56% | benchmarks/results/2026-04-09-grounding.json |

These are regression signals, not headline claims.

Data flow

data sources
    |
    v
+-------------+     +------------------+     +------------------+
| archive      | --> | extract facts     | --> | quality gate      |
| checksum     |     | deterministic     |     | trust classes     |
| ttl state    |     | semantic fallback |     | evidence anchors  |
+-------------+     +------------------+     +------------------+
          |                         |                      |
          +-------------------------+----------------------+
                                    |
                                    v
                           +------------------+
                           | preserve schema   |
                           | facts, memories,  |
                           | entities, review  |
                           +------------------+
                                    |
                                    v
                           +------------------+
                           | hybrid retrieval  |
                           | SQL + FTS + vec   |
                           | + temporal (RRF)  |
                           +------------------+
                                    |
                                    v
                           +------------------+
                           | notes, tools,     |
                           | timelines, MCP    |
                           +------------------+

Trust classes

BrainCore uses four active trust classes in the shipped schema:

| Trust class | Typical source | Promotion behavior | |---|---|---| | deterministic | Parsed directly from logs, YAML, or strongly-typed files | Can promote into patterns and playbooks | | human_curated | Operator-approved corrections or summaries | Highest editorial confidence | | corroborated_llm | Model output confirmed by multiple evidence sources | Eligible for durable memory | | single_source_llm | Model output from one source only | Searchable, but not trusted enough to promote by itself |

Retired facts remain queryable for provenance but do not behave like active truth.

Real-World Example Queries

The read path is designed for operational questions, not for generic chat summaries.

| Query | Best entry point | Expected answer shape | |---|---|---| | "why did docker start flapping after the disk filled?" | memory_search(..., query=...) | facts + timeline evidence | | "what changed on this service last week?" | memory_search(..., as_of=..., scope=...) | active facts with temporal windows | | "show me prior incidents involving SSL renewal" | memory_search(..., type_filter='episode') | incidents and summaries | | "what playbook do we already have for pgvector indexing drift?" | memory_search(..., type_filter='memory') | patterns and playbooks | | "what was the state of nginx before the migration?" | memory_search(..., as_of='...') | point-in-time fact set | | "which facts support this memory?" | retrieval + provenance objects | evidence spans and supporting facts |

Example:

import os
from psycopg_pool import ConnectionPool
from mcp.memory_search import memory_search

pool = ConnectionPool(conninfo=os.environ["BRAINCORE_POSTGRES_DSN"])

result = memory_search(
    pool,
    query="ssl certificate renewal failure",
    type_filter="fact",
    limit=5,
)

for row in result["results"]:
    print(row["object_type"], row["title"], row["score"])

Knowledge Graph

The open-source repo ships a 50-table preserve schema. The tables are split by lifecycle rather than by document format.

| Table | Purpose | |---|---| | artifact | master record for archived source material | | segment | evidence spans, excerpts, embeddings, and scope | | extraction_run | audit trail for extraction attempts | | schema_migration | migration ledger for applied SQL files and baselined deployments | | entity | devices, services, projects, incidents, sessions, config items | | episode | time-bounded incidents or sessions | | event | discrete events inside an episode | | fact | the central truth table with confidence and validity windows | | fact_evidence | fact-to-segment support links | | memory | consolidated patterns, heuristics, playbooks, summaries | | memory_support | memory-to-fact and memory-to-episode support | | publish_note | publish-state tracking for promoted memory notes | | review_queue | human review and moderation workflow | | project_service_map | service-to-project scoping map | | eval_run | stored evaluation runs and aggregate metrics | | eval_case | gold-set cases used by the eval path | | `memory_e

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SynapseGrid-Labs
• Source: SynapseGrid-Labs/BrainCore
• License: MIT
• Homepage: https://synapsegridlabs.com/braincore/

Install and usage instructions live in the source repository linked above.