@centr-ai/brain

v0.1.3

Published

21 days ago

Optional local Small Language Model (SLM) intelligence layer for CentR

Downloads

702

0High
0Medium
0Low

chiragpgauswami

centr brain ai-agents slm ollama local-ai context-ranking

⚡ The 2-Minute Executive Summary

| Question | The CentR Answer | | :--------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | What is CentR? | A local-first developer middleware that indexes code, maintains institutional memory, and supplies the smallest useful context to AI coding agents. | | Why does it exist? | Coding agents (Claude Code, Cursor, Codex, Antigravity) waste 2–4 turns and thousands of tokens blindly running find_by_name and grep_search to find relevant files. CentR stops this cycle. | | How is it different from RAG / Vector DBs? | Vector DBs dump unvalidated chunk similarity into context. CentR is deterministic AST symbol indexing + SQLite FTS5 BM25 + strict token budgets + evidence-scored memory. | | Does it replace my coding agent? | No. CentR is not an agent. It sits beside your agent via Model Context Protocol (MCP) or CLI to give it instant repository intelligence. | | Does it require cloud AI or paid APIs? | No. Zero cloud dependencies. Runs 100% locally with SQLite 3. An optional local Small Language Model (SLM) Brain can be attached via Ollama, but is never required. | | What does the optional Brain do? | Provides semantic re-ranking, task classification, and failure diagnosis. Core is always the authority; the Brain is an advisor. | | What privacy guarantees exist? | Zero telemetry. Your code, tokens, memories, and index never leave your machine. Secrets are automatically redacted before indexing. | | What evidence exists that it helps? | Preliminary interactive benchmark observations showed fewer exploratory tool calls (-2 calls per task on turn 1 in tested scenarios). Agent token telemetry was not available, so these results should not be interpreted as a controlled measurement of token savings or universal performance improvement. |

🏛️ Core Architecture

"Store everything useful. Send almost nothing."

The Two-Tier Architecture:

Deterministic Core (The Authority):
- AST Indexer: Parses TypeScript/JavaScript into symbols (functions, classes, interfaces, types) in ~20ms.
- SQLite 3 + FTS5: Ranked BM25 full-text search across symbols, paths, and memories in < 2ms.
- Token Budgeter: Greedy relevance sorting that strictly respects context limits (e.g. 4,000 tokens).
- Project Memory: Project-isolated institutional memory (.centr/centr.db).
- Global Learning: Evidence-based cross-project knowledge (~/.centr/learning.db).
Optional Local Brain (The Advisor):
- Powered by local Small Language Models (0.5B–7B parameters via Ollama or custom local providers).
- Semantic re-ranking, failure analysis, and memory extraction.
- Hallucination Guard: The Brain cannot invent files or edit source code; all candidates are bounded by Core retrieval.
- Deterministic Fallback: Automatically falls back to Core heuristics if the local SLM is absent, slow, or times out.

🚀 Quick Start

1. Installation

# Global installation
npm install -g @centr-ai/cli

# Or run directly via npx
npx @centr-ai/cli init

2. Initialize in Your Repository

cd my-project

# Initialize CentR index (takes ~20-50ms)
centr init

# Check intelligence status
centr status

3. Generate Context for an Agent

# Get the smallest useful context for a task
centr context "Add rate limiting to authentication routes"

# Search code symbols and files
centr search "verifyToken"

# Lookup exact symbol details and references
centr symbol "AuthService"

🔄 Lifecycle Workflow

🛠️ CLI Command Reference

🔌 Model Context Protocol (MCP) Integration

CentR provides a native stdio MCP server (@centr-ai/mcp) supported by Claude Code, OpenAI Codex, and Cursor.

Claude Code Setup

claude mcp add centr -- npx @centr-ai/mcp

Or add to your ~/.claude/claude.json:

{
  "mcpServers": {
    "centr": {
      "command": "npx",
      "args": ["-y", "@centr-ai/mcp"]
    }
  }
}

Cursor Setup (`.cursor/mcp.json`)

{
  "mcpServers": {
    "centr": {
      "command": "npx",
      "args": ["-y", "@centr-ai/mcp"]
    }
  }
}

Exposed MCP Tools:

get_context: Returns token-budgeted project intelligence for a task.
search_code: Ranked full-text search over indexed repository symbols.
lookup_symbol: Complete definition, references, and related imports.
get_memory & record_memory: Project-isolated memory retrieval and creation.
get_learning: Cross-project validated engineering lessons.

🧠 Project Memory vs. Global Learning

CentR maintains a strict boundary between repository-specific facts and reusable engineering wisdom:

Project Memory (`docs/MEMORY.md`)

Scope: Isolated to the current repository (.centr/centr.db).
Answers: "What happened in this specific project?"
Categories: Architecture patterns, decisions, constraints, discoveries, API contracts, dependencies, workflows, warnings.

Global Learning (`docs/LEARNING.md`)

Scope: Reusable across all repositories on the machine (~/.centr/learning.db).
Answers: "What should the agent do differently next time?"
Lifecycle: candidate (0.5 confidence) $\rightarrow$ evidence (success/failure logs) $\rightarrow$ validated ($\ge 0.7$ confidence with $\ge 3$ validations) or rejected.

📊 Real-Agent Benchmark Results

CentR includes an objective, reproducible Agent A/B Benchmark Harness (@centr-ai/benchmark-ab) evaluating 27 real-world coding tasks.

[!NOTE] Preliminary Interactive Benchmark Disclosure: The results below represent an interactive benchmark evaluating 7 software engineering tasks across 3 scenarios (21 total runs) using Google Antigravity (Gemini 2.5 Pro) on clean, isolated workspaces.
Agent-level telemetry was not exposed through the Antigravity tool boundary, so token usage and automated tool-call telemetry are not claimed. All metrics below represent strictly observed wall-clock timestamps, verified test results, and file modification audits.

Summary Results (7 Tasks, 21 Verified Runs)

| Scenario | Agent | Mode | Avg Duration | Observed Tool Calls | Test Pass Rate | Git Patch Size | | :------------------------ | :---------- | :----- | :----------: | :-----------------: | :------------: | :------------: | | Scenario A (Baseline) | Antigravity | manual | 167,143 ms | 6.0 | 100% (7/7) | +23 lines avg | | Scenario B (CentR V1) | Antigravity | manual | 122,263 ms | 4.0 (-33.3%) | 100% (7/7) | +23 lines avg | | Scenario C (CentR V2) | Antigravity | manual | 122,263 ms | 4.0 (-33.3%) | 100% (7/7) | +23 lines avg |

Key Empirical Findings:

Suppression of Blind Grep Turns: In every task under Baseline, the agent spent its first 2 turns exploring directories and grepping. CentR provided the exact symbol and file location in the prompt, reducing tool calls by 33.3% on turn 1.
Sub-2ms Core Latency: CentR V1 retrieval added only 1.2 ms to overall task execution.
Zero Cloud Tokens: All runs consumed 0 cloud tokens and incurred $0.00 API costs.

Full methodology and reproduction steps are documented in docs/AGENT-BENCHMARKING.md and benchmarks/agent-ab/reports/latest-report.md.

🔒 Security & Privacy

CentR is built with a zero-trust approach toward telemetry and sensitive files:

Zero Cloud Dependency: Never connects to remote cloud endpoints for core features.
Strict Secret Redaction: Built-in regex filters (DEFAULT_SECRET_PATTERNS) ignore .env, .pem, .key, AWS keys, tokens, and credentials during indexing.
Path Traversal Defense: All file lookups are strictly verified within the project root via sanitizePath.
Parameterized SQL: All database operations use SQLite parameterized placeholders (?) to prevent SQL injection.
Sandboxed Brain: The optional local Brain cannot execute shell commands, edit files directly, or persist ungrounded candidates.

See docs/SECURITY.md for our full security specification.

💻 Hardware Requirements

CentR is engineered for low-end hardware:

📚 Detailed Documentation

🤝 Contributing & Community

Contributions are welcome! Please review CONTRIBUTING.md and our CODE_OF_CONDUCT.md before submitting pull requests.

# Setup for development
git clone https://github.com/chiragpgauswami/CentR.git
cd CentR
npm install
npm run build
npm test