Bolor Brain MCP

Pure intelligence for Claude Code. Reasoning, memory, and learning -- nothing else.

What Is This?

Bolor Brain is an MCP server that gives Claude Code a brain: structured reasoning, persistent memory, and learning from experience.

Code

User --> Claude Code (Gateway + Executor)
              |
         +----+----+
    Bolor Brain   NSAF
      (MCP)       (MCP)
      THINK       EVOLVE

Claude Code = Gateway + tool execution + sessions + permissions
Bolor Brain = Reasoning engines + memory + learning + persistence
NSAF = Strategy evolution + self-improvement (separate MCP server)

Bolor Brain does NOT execute anything. No file ops, no scheduling, no autonomous loop. Claude Code already does all of that. Bolor Brain only thinks.

Quick Start

1. Install

bash

git clone https://github.com/photoxpedia/bolor-brain-mcp.git
cd bolor-brain-mcp
pip install -e .

2. Configure Claude Code

Add to ~/.claude/mcp-config.json:

config.json

{
  "mcpServers": {
    "bolor-brain": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "cwd": "/path/to/bolor-brain-mcp"
    }
  }
}

3. Use

Code

/reason Why is Python popular for data science?
/debug API returns 500 errors under load
/decide PostgreSQL or MongoDB for our app?
/learn-from We fixed the memory leak by increasing connection pool

MCP Tools (11)

Reasoning (6)

Tool	What It Does
`reason_hybrid`	Auto-selects best reasoning approach for any query
`reason_symbolic`	Forward/backward chaining with facts and rules
`reason_knowledge_graph`	Graph traversal, path finding, relationship exploration
`reason_case_based`	Find similar past problems and their solutions
`reason_hypothesis`	Generate and test hypotheses from observations
`reason_analogical`	Cross-domain pattern transfer (atom ~ solar system)

Memory (4)

Tool	What It Does
`remember`	Store a case, fact, node, or edge
`recall`	Retrieve matching cases or facts
`learn`	Store problem/solution/outcome (shortcut for remember)
`forget`	Delete a case or fact by ID

Utility (1)

Tool	What It Does
`brain_stats`	Cases, facts, nodes, edges count

Skills (6)

Skill	When To Use
`/reason`	Deep analysis of any complex problem
`/debug`	Systematic bug hunting with hypothesis testing
`/decide`	Evidence-based technical decisions
`/learn-from`	Store experiences for future use
`/nsaf`	NSAF evolution integration (requires NSAF MCP)
`/orchestrate`	Meta-orchestration combining Bolor Brain + NSAF

Persistence

Brain state persists to ~/.bolor-brain/ as JSON:

Code

~/.bolor-brain/
  cases.json       # Problem -> solution -> outcome
  facts.json       # Symbolic reasoning facts
  knowledge.json   # Knowledge graph (nodes + edges)

Knowledge compounds over time. Solve a bug once, recall the solution instantly next time.

With NSAF

Add NSAF to get evolution capabilities:

config.json

{
  "mcpServers": {
    "bolor-brain": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "cwd": "/path/to/bolor-brain-mcp"
    },
    "nsaf": {
      "command": "python3",
      "args": ["nsaf_mcp_server.py"],
      "cwd": "/path/to/nsaf",
      "env": { "PYTHONPATH": "/path/to/nsaf" }
    }
  }
}

Together: Bolor Brain reasons about WHAT to do. NSAF evolves HOW to do it better. Claude Code executes.

See skills/nsaf.md and skills/orchestrate.md for combined workflows.

Testing

bash

pytest tests/ -v
# 376 tests

Project Structure

Code

mcp_server.py                    # MCP server (11 tools)
persistence.py                   # JSON persistence to ~/.bolor-brain/
modules/
  config.py                      # Configuration
  reasoning_engines/
    symbolic_reasoner.py          # Forward/backward chaining
    knowledge_graph.py            # Graph-based knowledge
    case_based_reasoner.py        # 4R cycle (retrieve, reuse, revise, retain)
    hypothesis_engine.py          # Hypothesis generation and testing
    analogical_reasoner.py        # Cross-domain pattern transfer
    hybrid_reasoner.py            # Orchestrates all 5 engines
skills/                          # Claude Code skills
  reason.md, debug.md, decide.md, learn-from.md, nsaf.md, orchestrate.md
tests/                           # 376 tests
AGENT_GUARDRAILS.md              # Production safety guidelines

Author

Bolorerdene Bundgaa

Website: bolor.me
Email: bolor@ariunbolor.org

License

MIT -- see LICENSE