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'

Optional: set BRAINCORE_EMBED_AUTH_TOKEN if your /embed endpoint requires auth.

set -a && . ./.env && set +a ```

Live deployment measurements

These values are measured against a live deployment. They are valid README claims because they come from committed production-corpus artifacts, not from the synthetic smoke fixture.

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.

Real-World Example Queries

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

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"])

Configuration

Core configuration lives in .env.example.

The CLI treats BRAINCORE_POSTGRES_DSN as required at runtime. The configuration module uses lazy evaluation so help screens and static imports do not force a live environment until a command actually reads the config.

CLI Commands

The CLI is intentionally narrow and explicit.

Run bun src/cli.ts --help for the exact runtime usage block.

MCP Integration

BrainCore does not claim to ship a full MCP appliance. It ships the retrieval library plus a small reference server in examples/mcp_server/.

That example exists to prove three things:

- The retrieval library can be exposed over stdio transport. - The repo-root mcp/ namespace collision can be handled safely. - Pool creation can stay lazy so CI and tool introspection do not need a live database at import time.

The example server exposes the reference stdio MCP tool surface listed in examples/mcp_server/README.md: search, timeline, before/after, causal-chain, procedure, visual metadata, and working-memory session tools. It is still a reference server, not a hardened remote MCP appliance. If your deployment wraps these tools in HTTP, SSE, WebSocket, or another network transport, add authentication, tenant policy, write-tool authorization, request limits, and privacy review before exposing it.

Start here:

• examples/mcp_server/server.py
• examples/mcp_server/README.md
• mcp/memory_search.py
• mcp/memory_models.py

The Nightly Pipeline

cron/nightly.sh is the automation backbone. It is intentionally failure-tolerant:

- flock prevents overlap between runs. - Archive and extraction steps can fail independently without tearing down the whole night. - Post-processing happens in a clear sequence: embeddings, project tagging, consolidate, publish. - Weekly and monthly maintenance are gated by date rather than hidden in separate jobs. - Telegram notifications are optional, not mandatory.

The pipeline is designed to prefer partial progress over all-or-nothing fragility.

Comparison

BrainCore is opinionated about operational knowledge rather than chat-history memory.

BrainCore is a better fit when you care about incidents, sessions, configuration drift, and queryable operational history more than about remembering a conversational preference.