io.github.photoxpedia/bolor-brain-mcp

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.

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

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:

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

3. Use

/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)

Memory (4)

Utility (1)

Skills (6)

Persistence

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

~/.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:

{
  "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

pytest tests/ -v
# 376 tests

Project Structure

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