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)

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:

~/.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: [email protected]

License

MIT -- see LICENSE