CortexBrain Documentation

Complete guide to installing, configuring, and using CortexBrain — the enterprise AI memory system that gets smarter every time someone corrects it.

CortexBrain system architecture infographic showing the four memory substrates and query pipeline

Demo CortexBrain: AI That Remembers 2:03

Podcast Curing AI Amnesia with CortexBrain 15:44

CortexBrain gives your organization a persistent, self-correcting AI brain. Unlike standard RAG systems that start fresh every session, CortexBrain remembers corrections, tracks confidence, and provides a full audit trail for every answer.

What makes CortexBrain different

Capability	Standard RAG	CortexBrain
Memory	Stateless — lost every session	Persistent across all sessions & users
Corrections	Vanish when session ends	Permanent + versioned with audit trail
Confidence	None	4-level scoring (High / Medium / Low / Conflicted)
Context cost	O(n) — stuffs everything	O(1) — spreading activation selects only relevant nodes
Audit trail	None	Full: who changed what, when, and why
Self-improvement	No	Continuous learning from corrections & fallback answers

System Requirements

Component	Minimum	Recommended
Python	3.12+	3.12
Node.js (for dashboard)	18+	20 LTS
Docker & Docker Compose	v2.0+	Latest
RAM	4 GB	8 GB+
Disk	10 GB free	20 GB+ (scales with data)
OS	Linux (Ubuntu 22.04+), macOS 13+, Windows via WSL2

Required services (managed by Docker)

Service	Version	Purpose
Neo4j	5 Community	Semantic Memory (knowledge graph)
Redis	7 Alpine	Active Memory (activation scores) + Celery broker
PostgreSQL	16 Alpine	Meta Memory (audit logs, metadata, organizations)

Required API keys

Key	Where to get it	Used for
`LLM_API_KEY`	Your LLM provider (Gemini, OpenAI, Anthropic)	Query answering, entity extraction
`GEMINI_API_KEY`	Google AI Studio	Image generation (optional)

Installation

Clone the repository

bash
git clone https://github.com/iabhisekbosepm/cortexbrain.git
cd cortexbrain

Install Python dependencies

bash
# Create a virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate

# Install CortexBrain with all dependencies
pip install -e ".[dev]"

Configure environment

bash
cp .env.example .env

# Edit .env and add your API keys
nano .env

At minimum, set LLM_API_KEY and LLM_MODEL. See Environment Variables for all options.

Start backing services

bash
# Starts Neo4j, Redis, and PostgreSQL
docker compose up -d

# Verify all containers are running
docker compose ps

Start the API server

bash
uvicorn cortexbrain.main:app --reload --port 8000

The API is now live at http://localhost:8000.

Start background workers (required for decay, consolidation, batch ingestion)

bash
# In a new terminal — task worker
celery -A cortexbrain.workers.celery_app worker --loglevel=info

# In another terminal — scheduled tasks (decay, salience, consolidation)
celery -A cortexbrain.workers.celery_app beat --loglevel=info

Verify the installation

bash
curl -s http://localhost:8000/api/v1/health | python3 -m json.tool

You should see all services reporting "status": "ok".

Hybrid mode (recommended): Run infrastructure (Neo4j, Redis, PostgreSQL) in Docker, and run the Python app locally. This avoids Docker build issues and gives you hot-reload during development.

Configuration

CortexBrain uses a .env file for all configuration. Cognee reads its own env vars automatically; CortexBrain adds a settings layer on top via CortexBrainSettings.

Minimal .env example

.env
# LLM Configuration
LLM_MODEL=gemini/gemini-2.0-flash
LLM_API_KEY=your-api-key-here

# Image Generation (optional)
GEMINI_API_KEY=your-gemini-key

# Database Connections (defaults work with docker compose)
GRAPH_DATABASE_URL=bolt://localhost:7687
GRAPH_DATABASE_PASSWORD=cortexbrain_dev
REDIS_URL=redis://localhost:6379/0
POSTGRES_URL=postgresql+asyncpg://cortexbrain:cortexbrain_dev@localhost:5432/cortexbrain

# Celery (uses Redis)
CELERY_BROKER_URL=redis://localhost:6379/1
CELERY_RESULT_BACKEND=redis://localhost:6379/2

See full environment variable reference for tuning activation thresholds, decay rates, and token budgets.

First Run — Quick Start

Once installation is complete, test the full pipeline end-to-end:

bash — end-to-end test
# 1. Health check
curl -s localhost:8000/api/v1/health | python3 -m json.tool

# 2. Ingest your first document
curl -s -X POST localhost:8000/api/v1/ingest \
  -H "Authorization: Bearer dev-test-key" \
  -F "files=@README.md" \
  -F "dataset_name=getting-started" \
  | python3 -m json.tool

# 3. Ask a question
curl -s -X POST localhost:8000/api/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dev-test-key" \
  -d '{"query":"What is CortexBrain?","user_id":"me"}' \
  | python3 -m json.tool

# 4. You'll get an answer with confidence score and sources!

Ingesting Knowledge

CortexBrain learns from your organization's documents. Upload files, paste text, or batch-process entire directories. All content is processed through Cognee's ECL (Extract, Cognify, Load) pipeline, which extracts entities and relationships into a knowledge graph.

File Upload (Synchronous)

Upload PDF, Markdown, or plain text files. The system processes them immediately and returns when complete.

bash
# Upload a single file
curl -s -X POST http://localhost:8000/api/v1/ingest \
  -H "Authorization: Bearer dev-test-key" \
  -F "files=@docs/runbook.md" \
  -F "dataset_name=internal-docs" \
  -F "source_type=document" \
  | python3 -m json.tool

# Upload multiple files at once
curl -s -X POST http://localhost:8000/api/v1/ingest \
  -H "Authorization: Bearer dev-test-key" \
  -F "files=@docs/architecture.md" \
  -F "files=@docs/runbook.md" \
  -F "dataset_name=internal-docs" \
  | python3 -m json.tool

Dataset naming: Use hyphens or underscores in dataset names. Spaces and dots are not supported. Examples: internal-docs, runbook_v2, onboarding.

Direct Text Ingestion

Ingest text directly via API — ideal for Slack bots, CLI tools, or MCP integrations.

bash
curl -s -X POST http://localhost:8000/api/v1/ingest/text \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dev-test-key" \
  -d '{
    "text": "The auth service runs on port 3000. Updated after Q1 migration.",
    "dataset_name": "team-knowledge",
    "source_type": "manual"
  }' | python3 -m json.tool

Batch Processing (Async)

For large document sets, use batch ingestion. Files are queued and processed in the background via Celery.

bash
# Submit files for background processing
curl -s -X POST http://localhost:8000/api/v1/ingest/batch \
  -H "Authorization: Bearer dev-test-key" \
  -F "files=@docs/runbook-v1.md" \
  -F "files=@docs/runbook-v2.md" \
  -F "files=@docs/incident-report.pdf" \
  -F "dataset_name=project-docs" \
  | python3 -m json.tool

# Response: {"status":"queued","task_id":"abc123-..."}

# Poll for completion
curl -s http://localhost:8000/api/v1/ingest/batch/{task_id} \
  -H "Authorization: Bearer dev-test-key" \
  | python3 -m json.tool

Requires Celery worker: Batch ingestion won't process unless a Celery worker is running. Start one with celery -A cortexbrain.workers.celery_app worker --loglevel=info.

Querying the Knowledge Base

Queries run through a 10-step pipeline: entity extraction → graph lookup → spreading activation → confidence gating → LLM generation. You get an answer with confidence score, source attribution, and token usage.

Basic Query

bash
curl -s -X POST http://localhost:8000/api/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dev-test-key" \
  -d '{
    "query": "What port does the auth service run on?",
    "user_id": "priya"
  }' | python3 -m json.tool

Response structure

json
{
  "answer": "The auth service runs on port 3000...",
  "confidence": "high",
  "confidence_score": 0.92,
  "sources": [
    { "node_id": "...", "source_name": "Auth Service Config", "confidence": 0.95 }
  ],
  "tokens_used": { "input": 320, "output": 85 },
  "fallback": false
}

Session Continuity

Pass a session_id to maintain activation context across multiple queries. Previously activated nodes retain partial activation, making follow-up queries faster and more relevant.

bash
# First query — seeds activation for "metacognition" nodes
curl -s -X POST http://localhost:8000/api/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dev-test-key" \
  -d '{"query":"What is the metacognition layer?","user_id":"priya","session_id":"my-session"}' \
  | python3 -m json.tool

# Follow-up — benefits from existing activation scores
curl -s -X POST http://localhost:8000/api/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dev-test-key" \
  -d '{"query":"How does confidence gating work?","user_id":"priya","session_id":"my-session"}' \
  | python3 -m json.tool

Understanding Confidence Levels

Every response includes a confidence level that tells you how reliable the answer is:

Level	Score	What it means
HIGH	≥ 0.8	Answer is well-supported by multiple sources or human corrections. Safe to trust.
MEDIUM	0.5 – 0.8	Answer has some support but may need verification. Response includes a qualifier.
LOW	< 0.5	Limited data available. Treat with caution. System suggests verification.
CONFLICTED	Flagged	Multiple sources disagree. All conflicting versions are shown for you to resolve.

Submitting Corrections

This is CortexBrain's core differentiator. When you correct a fact, it persists forever — the old value is archived with a PREVIOUS_VERSION edge, the new value becomes active, and an audit record is created.

bash
curl -s -X POST http://localhost:8000/api/v1/correct \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dev-test-key" \
  -d '{
    "node_id": "00000000-0000-0000-0000-000000000001",
    "corrected_value": "The auth service runs on port 3000, not 8080",
    "user_id": "priya",
    "reason": "Updated after Q1 migration"
  }' | python3 -m json.tool

What happens when you correct

Locate: The node is found in the knowledge graph (or created if new).
Version: Current state is archived as a PREVIOUS_VERSION edge — nothing is lost.
Mutate: Node is updated with the correction. Confidence is set to 0.95. Node is flagged as volatile: true.
Meta-Update: Audit record is created in PostgreSQL. Original source confidence is adjusted.
Re-index: Corrected text is re-embedded in the vector store.

From this moment, every user who asks the same question gets the corrected answer.

Audit Trail

Every fact in CortexBrain has a complete version history. See who changed what, when, and why.

bash
# Get full version history for a node
curl -s http://localhost:8000/api/v1/nodes/{node_id}/history \
  -H "Authorization: Bearer dev-test-key" \
  | python3 -m json.tool

Response example

json
[
  { "version": 2, "value": "Port 3000",
    "changed_by": "user:priya",
    "reason": "Updated after Q1 migration",
    "timestamp": "2026-03-15T14:32:00Z" },
  { "version": 1, "value": "Port 8080",
    "changed_by": "system:ingestion",
    "timestamp": "2026-03-01T09:00:00Z" }
]

bash — inspect a node
# Get node details including confidence, salience, and access count
curl -s http://localhost:8000/api/v1/nodes/{node_id} \
  -H "Authorization: Bearer dev-test-key" \
  | python3 -m json.tool

MCP Integration

CortexBrain ships as an MCP (Model Context Protocol) server. This lets AI coding tools like Claude Code, Codex, Cursor, and Windsurf connect to your organization's persistent knowledge brain.

Setting up with Claude Code

Add CortexBrain to your project's .mcp.json:

.mcp.json
{
  "cortexbrain": {
    "command": "python3",
    "args": ["-m", "cortexbrain.mcp"]
  }
}

Every Claude Code session will now have access to your organization's knowledge via the 6 built-in MCP tools.

Other MCP Clients

You can also run the MCP server standalone and connect any MCP-compatible client:

bash
# Start the MCP server (communicates via stdio)
python3 -m cortexbrain.mcp

Available MCP Tools

Tool	What it does	Example usage
`cortexbrain_query`	Search the knowledge base with confidence scoring	"What port does auth run on?"
`cortexbrain_remember`	Store new information persistently	"Remember: we migrated to port 3000"
`cortexbrain_correct`	Submit a versioned correction to a knowledge node	Fix wrong values in the graph
`cortexbrain_search_sources`	Browse available datasets and their content	List what knowledge sources exist
`cortexbrain_consolidate`	Trigger a memory consolidation cycle	Promote, archive, merge, compress nodes
`cortexbrain_health`	Check the health of all backing services	Verify Redis, Neo4j, PostgreSQL are up

REST API Reference

Base URL: http://localhost:8000/api/v1
Authentication: Authorization: Bearer <token>

Core Endpoints

Method	Endpoint	Description
POST	`/api/v1/query`	Query with activation-based context selection
POST	`/api/v1/correct`	Submit a versioned correction
POST	`/api/v1/ingest`	Upload files (synchronous)
POST	`/api/v1/ingest/batch`	Upload files (async via Celery)
POST	`/api/v1/ingest/text`	Ingest text directly
POST	`/api/v1/ingest/text/async`	Fire-and-forget text ingestion

Audit & Nodes

Method	Endpoint	Description
GET	`/api/v1/nodes/{node_id}`	Node detail (graph + metadata combined)
GET	`/api/v1/nodes/{node_id}/history`	Full version history
GET	`/api/v1/datasets`	List all datasets
GET	`/api/v1/datasets/{name}/data`	Browse data items in a dataset

Management

Method	Endpoint	Description
GET	`/api/v1/health`	Health check for all services
POST	`/api/v1/consolidation/run`	Trigger memory consolidation
GET	`/api/v1/consolidation/status/{id}`	Poll consolidation progress
GET	`/api/v1/consolidation/last-report`	Last consolidation summary
GET	`/api/v1/workers/status`	Celery worker dashboard
GET	`/api/v1/sessions/{id}/activations`	View activation scores for a session
POST	`/api/v1/debug/salience-recompute`	Manual salience recompute
GET	`/api/v1/debug/stats`	System-wide debug stats

Admin Dashboard

CortexBrain includes a full admin dashboard built with Next.js 16. It provides a visual interface for querying, ingestion, node inspection, and system monitoring.

Starting the dashboard

bash
cd frontend
npm install
npm run dev

# Dashboard is now at http://localhost:3000

Dashboard pages

Page	URL	What it does
Query	`/query`	Chat-like interface with confidence badges, inline corrections, source attribution, image display
Ingest	`/ingest`	Drag-and-drop file upload with sync/batch modes and pipeline visualization
Nodes	`/nodes`	Browse knowledge nodes, search by UUID, view top accessed/salient nodes
Node Detail	`/nodes/[id]`	Full node detail with version history timeline and correction dialog
Debug	`/debug`	System stats, activation viewer, salience recompute
Workers	`/workers`	Celery worker monitoring, active/queued tasks, beat schedule
Health	`/health`	Auto-refreshing service health (every 10s) with health history timeline
Settings	`/settings`	Configure API URL, API key, user ID. Test connection.

First-time setup: Visit /settings first to configure your API URL (http://localhost:8000) and test the connection. Credentials are stored in localStorage.

Background Workers

CortexBrain uses Celery with Redis as the message broker. Workers handle scheduled maintenance and async processing.

Task	Schedule	What it does
`decay_cycle_task`	Every 30 seconds	Decrements activation scores in Redis. Evicts nodes at 0. Keeps active context fresh.
`salience_recompute_task`	Every 1 hour	Recalculates salience scores for all nodes based on access frequency, recency, corrections, and edges.
`consolidation_task`	Every 7 days	Promotes validated knowledge, archives stale nodes, merges duplicates, compresses version chains.
`batch_ingestion_task`	On demand	Processes queued document batches through Cognee's ECL pipeline.
`text_ingestion_task`	On demand	Async text ingestion for fire-and-forget use cases.

Memory Consolidation

Consolidation is CortexBrain's self-maintenance system. It runs weekly (or on demand) and performs four operations:

Promote: Auto-learned knowledge (confidence 0.6) gets promoted to validated (0.75) if it has been accessed 3+ times or has 2+ high-confidence neighbors.
Archive: Bottom 10% salience nodes that haven't been accessed in 90+ days are marked as archived. They remain in the graph but are excluded from activation.
Merge: Duplicate entities (matching by normalized name + fuzzy match at threshold 0.85) are merged into a single node. All edges are re-pointed.
Compress: Version chains longer than 5 entries are compressed to keep only the first and last versions, marking intermediates as compressed.

bash — trigger manually
# Trigger consolidation
curl -s -X POST http://localhost:8000/api/v1/consolidation/run \
  -H "Authorization: Bearer dev-test-key" \
  | python3 -m json.tool

# Check last report
curl -s http://localhost:8000/api/v1/consolidation/last-report \
  -H "Authorization: Bearer dev-test-key" \
  | python3 -m json.tool

Health Monitoring

The health endpoint checks all 5 backing services in real-time:

bash
curl -s http://localhost:8000/api/v1/health | python3 -m json.tool

Service	What's checked	If it fails
Redis	PING command	Activation/decay stops; queries use graph-only fallback
Neo4j	Cypher query	Graph queries fail; vector-only fallback
PostgreSQL	SELECT 1	Audit logs and metadata unavailable
LanceDB	Collection list	Vector search unavailable; graph-only
LLM	Test prompt	Answers return from memory only (no LLM generation)

Architecture

CortexBrain extends Cognee open-source — it does not fork or reimplement. The four memory substrates model how the human brain stores and retrieves knowledge:

architecture
┌──────────────────────────────────────────────────────────────┐
│  M_a  Active Memory (Redis)                                  │
│       Spreading activation — relevant knowledge lights up,  │
│       irrelevant fades away. TTL 600s. Decay every 30s.     │
├──────────────────────────────────────────────────────────────┤
│  M_s  Semantic Memory (Neo4j)                                │
│       Knowledge graph — entities, relationships, versioned  │
│       corrections with PREVIOUS_VERSION edges.              │
├──────────────────────────────────────────────────────────────┤
│  M_r  Raw Memory (LanceDB via Cognee)                        │
│       Vector embeddings — fallback when the graph hasn't    │
│       connected the dots yet.                               │
├──────────────────────────────────────────────────────────────┤
│  M_meta  Meta Memory (PostgreSQL)                            │
│          Audit logs, confidence scores, salience, access    │
│          counts, organizations, API keys.                   │
└──────────────────────────────────────────────────────────────┘

Query Pipeline (10 steps)

flow
User Query
    ↓
1. Cognee search (vector + graph) → entity extraction
2. Neo4j text search (direct graph for corrected nodes)
3. Entity extraction from results (capped at 20, deduped)
4. Spreading activation (BFS through Neo4j graph)
5. Enrich with M_meta (confidence, salience, conflicted)
6. Confidence gate (weighted average by activation scores)
7. Access tracking (record access for each activated node)
8. Image check → if visual query, call Gemini for image
9. LLM generation (activated nodes as context + confidence prefix)
10. Continuous learning fallback (if KB fails → auto-learn)
    ↓
Response with answer, confidence, sources, token usage

Algorithms

Spreading Activation

When a query arrives, the system identifies relevant nodes and spreads activation through the knowledge graph using BFS:

formula
neighbor_activation = source_activation × edge_weight × 0.5 (dampening)

Initial seed score: 100.0
Threshold:          30   (configurable via ACTIVATION_THRESHOLD)
Max context:        2000 tokens (configurable via MAX_CONTEXT_TOKENS)
Traversal:          BFS, skips archived nodes
Fallback:           Vector search (M_r) if no graph matches

Salience Scoring

formula
Salience = (access_freq × 0.4) + (recency × 0.3) + (correction_count × 0.2) + (edge_count × 0.1)

Normalization caps: access=100, corrections=20, edges=50
Recency: exponential decay over 7-day window
New nodes: default salience 0.5 for 7-day grace period

Decay Cycle

formula
Every 30s: score -= DECAY_RATE (10)
Evict at 0 from Redis (Neo4j untouched — no data loss)
Idle session (>5 min): fully decayed, next query starts fresh

RAG Benchmarks

CortexBrain includes a built-in benchmark suite to measure retrieval accuracy and query speed. Run these after ingesting data to validate your RAG pipeline is performing well.

Prerequisites: The CortexBrain API must be running with ingested data. Benchmarks query the live /api/v1/query endpoint. Install httpx if not already available: pip install httpx.

Quick Start

bash
# Run accuracy evaluation (20 golden Q&A pairs)
python3 tests/benchmarks/eval_rag.py

# Run speed benchmark (8 queries x 3 iterations)
python3 tests/benchmarks/bench_speed.py

# Both save JSON results to tests/benchmarks/

Accuracy Evaluation

Measures how well CortexBrain retrieves relevant nodes and generates correct answers. Uses a golden dataset of Q&A pairs with expected sources and keywords.

Metrics

Metric	What It Measures	Formula
Recall@K	% of expected sources found in top K results	matched ÷ expected
Precision@K	% of top K results that are relevant	relevant_in_K ÷ K
MRR	How early the first relevant result appears	1 ÷ rank_of_first_match
Keyword Score	% of expected keywords present in the answer	found ÷ expected
Faithfulness	Does the answer only use info from context?	LLM-as-judge (0.0–1.0)

CLI Options

bash
# Full evaluation with all metrics
python3 tests/benchmarks/eval_rag.py

# Skip LLM-as-judge faithfulness scoring (faster, no extra LLM calls)
python3 tests/benchmarks/eval_rag.py --skip-faithfulness

# Filter by category
python3 tests/benchmarks/eval_rag.py --category algorithm

# Run specific queries only
python3 tests/benchmarks/eval_rag.py --ids q01,q05,q13

# Change top-K for retrieval metrics (default: 10)
python3 tests/benchmarks/eval_rag.py --k 5

# Use a custom golden dataset
python3 tests/benchmarks/eval_rag.py --dataset my_golden.jsonl

Pass/Fail Threshold

The benchmark fails (exit code 1) if average Recall@K < 30% or average keyword match < 30%. This catches major regressions after pipeline changes.

Output

Results are printed to the terminal and saved to tests/benchmarks/eval_results.json with per-query breakdowns, aggregate metrics, and confidence calibration analysis.

Speed Benchmark

Measures end-to-end query latency across varied query types. Reports p50, p95, and p99 percentiles.

Query Types Tested

Label	Query	Tests
`simple_entity`	Single entity lookup	Basic graph traversal speed
`multi_entity`	Multi-entity complex question	Spreading activation with many seeds
`specific_detail`	Precise factual question	Targeted retrieval speed
`broad_topic`	Open-ended exploration	Large context assembly + LLM generation
`correction_flow`	Questions about corrections	Version history traversal
`out_of_domain`	Unrelated question	Continuous learning fallback latency
`algorithm_detail`	Technical algorithm question	Deep graph traversal
`infrastructure`	Infrastructure question	Cross-domain retrieval

CLI Options

bash
# Default: 8 queries x 3 iterations
python3 tests/benchmarks/bench_speed.py

# More iterations for stable statistics
python3 tests/benchmarks/bench_speed.py --iterations 10

# Fewer queries for quick check
python3 tests/benchmarks/bench_speed.py --queries 3

# Custom p95 threshold in milliseconds
python3 tests/benchmarks/bench_speed.py --threshold 30000

# Include component-level benchmarks (health, simple, complex, OOD)
python3 tests/benchmarks/bench_speed.py --component

Pass/Fail Threshold

The benchmark fails (exit code 1) if p95 latency exceeds the threshold (default: 45,000ms). This includes full LLM generation time. Use --threshold to adjust.

Output

Results are printed as a table with p50/p95/p99/mean/stdev per query type, plus activation mode distribution and fallback rate. Saved to tests/benchmarks/speed_results.json.

Golden Dataset

The golden dataset at tests/benchmarks/golden_dataset.jsonl contains 20 Q&A pairs organized by category and difficulty. Each entry specifies expected source nodes and answer keywords.

Dataset Structure

jsonl
{
  "id": "q01",
  "query": "What is the spreading activation algorithm?",
  "expected_sources": ["spreading activation", "activation engine", "dampening"],
  "expected_answer_contains": ["BFS", "dampening", "0.5", "threshold"],
  "difficulty": "easy",
  "category": "architecture"
}

Category	Count	What It Tests
`architecture`	6	Memory substrates, activation, Cognee extension
`algorithm`	5	Salience, decay, confidence, token budget, fallback cascade
`feature`	3	Continuous learning, correction versioning, image generation
`api`	2	REST endpoints, correction endpoint
`infrastructure`	2	Celery tasks, vector database
`integration`	1	MCP server integration
`security`	1	Authentication mechanism

Adding Custom Q&A Pairs

Append new lines to golden_dataset.jsonl to expand coverage. Each line is a JSON object with these fields:

jsonl
// Required fields:
"id"          — Unique identifier (e.g., "q21")
"query"       — Natural language question
"expected_sources"   — Source node names to match (fuzzy)
"expected_answer_contains"  — Keywords expected in the answer

// Optional fields:
"difficulty"  — "easy" | "medium" | "hard" (default: "medium")
"category"    — Grouping label (default: "general")

Environment variables: Set CORTEXBRAIN_URL (default: http://localhost:8000) and CORTEXBRAIN_API_KEY (default: test-key) to point benchmarks at a different instance.

Troubleshooting

Common issues

Problem	Cause	Fix
Health check fails for Neo4j	Container not running	`docker compose up -d neo4j`
`python: command not found`	macOS uses `python3`	Use `python3` instead of `python`
Batch ingestion stuck at "queued"	No Celery worker running	Start worker: `celery -A cortexbrain.workers.celery_app worker`
Dataset name error	Spaces or dots in name	Use hyphens or underscores: `my-dataset`
Celery "future loop mismatch"	Using `new_event_loop()`	Tasks must use `asyncio.run()`
Ingestion times out via dashboard	Next.js proxy timeout	Set `experimental.proxyTimeout: 300000` in `next.config.ts`
Docker build fails (apt-get 403)	Network issue with deb.debian.org	Use hybrid mode: Docker for infra, run app locally
Query returns no sources	No data ingested yet	Ingest documents first via `/api/v1/ingest`
Low confidence on all answers	Insufficient data or missing corrections	Ingest more documents and submit corrections for key facts

Environment Variables

LLM & API

Variable	Default	Description
`LLM_MODEL`	`gemini/gemini-2.0-flash`	LLM model via litellm (supports OpenAI, Anthropic, Gemini, etc.)
`LLM_API_KEY`	—	API key for your LLM provider
`GEMINI_API_KEY`	—	Google Gemini key for image generation (optional)

Database Connections

Variable	Default	Description
`GRAPH_DATABASE_URL`	`bolt://localhost:7687`	Neo4j connection URL
`GRAPH_DATABASE_PASSWORD`	`cortexbrain_dev`	Neo4j password
`REDIS_URL`	`redis://localhost:6379/0`	Redis for active memory
`POSTGRES_URL`	`postgresql+asyncpg://...`	PostgreSQL for meta memory
`CELERY_BROKER_URL`	`redis://localhost:6379/1`	Celery message broker
`CELERY_RESULT_BACKEND`	`redis://localhost:6379/2`	Celery result storage

Activation & Decay Tuning

Variable	Default	Description
`ACTIVATION_THRESHOLD`	`30`	Minimum activation score to include a node in context. Lower = more context, higher = more selective.
`DAMPENING_FACTOR`	`0.5`	How much activation decays per hop in BFS. Lower = faster decay = tighter context.
`MAX_CONTEXT_TOKENS`	`2000`	Maximum tokens to include in the LLM prompt from activated nodes.
`DECAY_RATE`	`10`	Score decrement per decay cycle.
`DECAY_INTERVAL_SECONDS`	`30`	How often the decay cycle runs.

CortexBrain Documentation — Built by Abhisek Bose

← Back to website

CortexBrain Documentation

What makes CortexBrain different

System Requirements

Required services (managed by Docker)

Required API keys

Installation

Clone the repository

Install Python dependencies

Configure environment

Start backing services

Start the API server

Start background workers (required for decay, consolidation, batch ingestion)

Verify the installation

Configuration

Minimal .env example

First Run — Quick Start

Ingesting Knowledge

File Upload (Synchronous)

Direct Text Ingestion

Batch Processing (Async)

Querying the Knowledge Base

Basic Query

Response structure

Session Continuity

Understanding Confidence Levels

Submitting Corrections

What happens when you correct

Audit Trail

Response example

MCP Integration

Setting up with Claude Code

Other MCP Clients

Available MCP Tools

REST API Reference

Core Endpoints

Audit & Nodes

Management

Admin Dashboard

Starting the dashboard

Dashboard pages

Background Workers

Memory Consolidation

Health Monitoring

Architecture

Query Pipeline (10 steps)

Algorithms

Spreading Activation

Salience Scoring

Decay Cycle

RAG Benchmarks

Quick Start

Accuracy Evaluation

Metrics

CLI Options

Pass/Fail Threshold

Output

Speed Benchmark

Query Types Tested

CLI Options

Pass/Fail Threshold

Output

Golden Dataset

Dataset Structure

Categories

Adding Custom Q&A Pairs

Troubleshooting

Common issues

Environment Variables

LLM & API

Database Connections

Activation & Decay Tuning