# Galaxy Brain

<div align="center">

<!-- Your cosmic art goes here -->
<img src="assets/galaxy-brain.png" alt="Galaxy Brain" width="400">

### Think. Do. Done.

*Sequential Thinking + Sequential Doing = Complete Cognitive Loop*

[![MIT License](https://img.shields.io/badge/License-MIT-purple.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://python.org)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)

</div>

---

## What is this?

**Galaxy Brain** is an MCP server that combines two powerful concepts:

1. **Sequential Thinking** (from Anthropic's MCP) - structured reasoning with revision and branching
2. **Sequential Doing** - batch execution with variable piping between operations

Together they form a complete **cognitive loop**: think through a problem, convert thoughts to actions, execute, done.

```
   PROBLEM
      │
      ▼
┌─────────────┐
│   THINK     │  ← reason step by step
│             │  ← revise if wrong
│             │  ← branch to explore
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   BRIDGE    │  ← convert thoughts to operations
└──────┬──────┘
       │
       ▼
┌─────────────┐
│    DO       │  ← execute sequentially
│             │  ← pipe results between ops
└──────┬──────┘
       │
       ▼
    DONE
```

---

## Installation

### Quick Install (PowerShell)

```powershell
git clone https://github.com/For-Sunny/galaxy-brain.git
cd galaxy-brain
.\scripts\install.ps1
```

### Quick Install (Bash)

```bash
git clone https://github.com/For-Sunny/galaxy-brain.git
cd galaxy-brain
chmod +x scripts/install.sh
./scripts/install.sh
```

### Manual Install

```bash
pip install galaxy-brain
```

Then add to your Claude Desktop config (`%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "galaxy-brain": {
      "command": "python",
      "args": ["-m", "galaxy_brain.server"]
    }
  }
}
```

---

## Usage

### The Galaxy Brain Move: `think_and_do`

One tool to rule them all:

```python
think_and_do({
  "problem": "I need to read a config file, parse it, and count the keys",

  "thoughts": [
    "First I need to read the config file",
    "Then parse it as JSON",
    "Finally count the number of keys"
  ],

  "operations": [
    {
      "service": "file",
      "method": "read",
      "params": { "path": "config.json" }
    },
    {
      "service": "transform",
      "method": "json_parse",
      "params": { "content": "$results[0].result.content" }
    },
    {
      "service": "python",
      "method": "eval",
      "params": { "expression": "len($results[1].result)" }
    }
  ]
})
```

See that `$results[0].result.content`? That's **variable piping** - each operation can reference results from previous operations.

---

### Thinking Tools

Start a thinking session and reason step by step:

```python
# Start thinking
start_thinking({
  "problem": "How should I refactor this authentication system?",
  "initial_estimate": 5
})
# Returns: { "session_id": "think_abc123..." }

# Add thoughts
think({
  "session_id": "think_abc123...",
  "thought": "The current system uses session cookies...",
  "confidence": 0.8
})

# Realize you were wrong? Revise!
revise({
  "session_id": "think_abc123...",
  "revises_thought": 2,
  "revised_content": "Actually, we should use JWTs because...",
  "reason": "Stateless is better for our scale"
})

# Want to explore an alternative? Branch!
branch({
  "session_id": "think_abc123...",
  "branch_from": 3,
  "branch_name": "oauth_approach",
  "first_thought": "What if we used OAuth2 instead?"
})

# Done thinking
conclude({
  "session_id": "think_abc123...",
  "conclusion": "We should migrate to JWT with refresh tokens",
  "confidence": 0.9
})
```

---

### Doing Tools

Execute operations with variable piping:

```python
execute_batch({
  "batch_name": "process_data",
  "operations": [
    {
      "service": "shell",
      "method": "run",
      "params": { "command": "curl -s https://api.example.com/data" }
    },
    {
      "service": "transform",
      "method": "json_parse",
      "params": { "content": "$results[0].result.stdout" }
    },
    {
      "service": "file",
      "method": "write",
      "params": {
        "path": "output.json",
        "content": "$results[1].result"
      }
    }
  ]
})
```

#### Available Services

| Service | Methods | Description |
|---------|---------|-------------|
| `python` | `execute`, `eval` | Run Python code or evaluate expressions |
| `shell` | `run` | Execute shell commands |
| `file` | `read`, `write`, `exists` | File operations |
| `transform` | `json_parse`, `json_stringify`, `extract`, `template` | Data transformations |

---

### Bridge Tools

Convert thinking sessions to action plans:

```python
# Generate plan from concluded session
generate_plan({
  "session_id": "think_abc123..."
})

# Execute the generated plan
execute_plan({
  "plan_id": "plan_xyz789..."
})
```

---

## Variable Piping Syntax

Reference previous results using `$results[N].path.to.value`:

```python
$results[0]                    # Full result of operation 0
$results[0].result             # The result field
$results[0].result.content     # Nested access
$results[1].result.data[0]     # Array access (in path format)
```

Variables are resolved before each operation executes, so you can build pipelines:

```python
operations = [
  # Op 0: Read a file
  { "service": "file", "method": "read", "params": { "path": "input.txt" } },

  # Op 1: Use content from op 0
  { "service": "python", "method": "execute",
    "params": { "code": "print(len('$results[0].result.content'))" } },

  # Op 2: Use stdout from op 1
  { "service": "file", "method": "write",
    "params": { "path": "count.txt", "content": "$results[1].result.stdout" } }
]
```

---

## Configuration

Create `galaxy-brain.json` in your working directory:

```json
{
  "thinking": {
    "max_thoughts": 50,
    "max_branches": 10,
    "max_revisions_per_thought": 5
  },
  "doing": {
    "max_operations": 50,
    "default_timeout": 30,
    "max_timeout": 300,
    "stop_on_error": true
  },
  "bridge": {
    "auto_execute": false,
    "validate_before_execute": true
  },
  "log_level": "INFO"
}
```

Or use environment variables:
- `GALAXY_BRAIN_LOG_LEVEL`
- `GALAXY_BRAIN_MAX_THOUGHTS`
- `GALAXY_BRAIN_MAX_OPERATIONS`

---

## Why "Galaxy Brain"?

Because when you combine structured thinking with chained execution, you're operating on a whole other level.

Think. Do. Done. Big brain energy. Cosmic efficiency.

---

## Credits

- **Sequential Thinking**: Based on [@modelcontextprotocol/server-sequential-thinking](https://github.com/modelcontextprotocol/servers) (MIT Licensed)

---

## License

MIT License - Do whatever you want with it.

---

<div align="center">

**Think. Do. Done.**

</div>

---

**Built by [CIPS Corp](https://cipscorps.io)**

[Website](https://cipscorps.io) | [Store](https://store.cipscorps.io) | [GitHub](https://github.com/For-Sunny) | [glass@cipscorps.io](mailto:glass@cipscorps.io)

Enterprise memory infrastructure for AI systems: [CASCADE Enterprise, PyTorch Memory, Hebbian Mind, and the full CIPS Stack](https://store.cipscorps.io).

Copyright (c) 2025-2026 C.I.P.S. LLC