<div align="center">

# BrainLess

### The Persistent Memory Layer Every AI Vibe Coder Has Been Waiting For

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://python.org)
[![MCP](https://img.shields.io/badge/Protocol-MCP-purple.svg)](https://modelcontextprotocol.io)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

**English** | [繁體中文](#繁體中文)

> *"The AI forgot everything again."* — Every Vibe Coder, every single day.

**BrainLess** is an open-source [MCP](https://modelcontextprotocol.io) server that gives your AI a **global, persistent brain** that survives account switches, IDE restarts, and new chat sessions.

</div>

---

## The Problem

You are deep in a Vibe Coding session. The AI finally understands your architecture. Then:

- You switch IDE (Cursor -> Windsurf -> Antigravity)
- You log in with a different account
- The free-tier chat limit resets

**Poof.** All context is gone.

---

## The Solution: BrainLess

Two tools. One folder. Done.

| Tool | What it does |
|------|-------------|
| `vibe_snapshot` | Prepends a timestamped project summary into **one single rolling log file** (`my_global_vibe_brain.md`). Works across every IDE and account. |
| `vibe_scan_legacy` | Scans any codebase and auto-generates a Markdown summary, appending it to the same global file. |

All output goes into ONE single file: `my_global_vibe_brain.md`. No scattered files, no tricks.

---

## Quick Start

### 1. Install

```bash
git clone https://github.com/roazhang/brainless.git
cd brainless
pip install -e .
```

### 2. Pick ONE folder — that is the only setting you need

> This is the only thing you ever configure.

```bash
# Linux / macOS
export BRAINLESS_DIR="/Users/you/brainless"

# Windows PowerShell
$env:BRAINLESS_DIR = "C:\brainless"
```

Everything goes into that folder. No subfolders. No surprises.

### 3. Test it

```bash
python server.py stdio
```

---

## IDE Integration

> One rule: set `BRAINLESS_DIR` to your folder path. That is it.

### Cursor — ~/.cursor/mcp.json

```json
{
  "mcpServers": {
    "brainless": {
      "command": "python",
      "args": ["/absolute/path/to/brainless/server.py", "stdio"],
      "env": { "BRAINLESS_DIR": "/Users/you/brainless" }
    }
  }
}
```

### Windsurf — Settings -> MCP Servers -> Add

```json
{
  "name": "brainless",
  "command": "python",
  "args": ["/absolute/path/to/brainless/server.py", "stdio"],
  "env": { "BRAINLESS_DIR": "/Users/you/brainless" }
}
```

### Antigravity IDE

```json
{
  "mcpServers": {
    "brainless": {
      "command": "python",
      "args": ["C:\\brainless\\server.py", "stdio"],
      "env": { "BRAINLESS_DIR": "C:\\brainless" }
    }
  }
}
```

### Claude Desktop

Same JSON format as Cursor. Edit `~/Library/Application Support/Claude/claude_desktop_config.json`.

---

## Tool Reference

### `vibe_snapshot` — Save before you lose it

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_name` | string | Yes | Short project identifier |
| `summary` | string | Yes | What was accomplished this session |
| `key_prompts` | string | | Key prompts / decisions |
| `next_steps` | string | | TODOs for next session |
| `tags` | string | | Comma-separated tags |

Output: Prepend to `BRAINLESS_DIR/my_global_vibe_brain.md`

### `vibe_scan_legacy` — Reverse-engineer a forgotten codebase

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_path` | string | Yes | Absolute path to project folder |
| `output_name` | string | | Override output filename |
| `include_tree` | bool | | Include directory tree (default: true) |
| `include_source_preview` | bool | | Include source previews (default: true) |

Output: Prepend to `BRAINLESS_DIR/my_global_vibe_brain.md`

---

## 🤖 Auto-Pilot (Zero-Click Logging)

Want your AI to write its own diary without you ever asking? 

Just copy and paste this into your IDE's global rules (e.g., `Cursor Rules`, `Windsurf global rules`, or Antigravity's `AGENTS.md`):

```markdown
# BrainLess Global Memory Rule
1. You have the `brainless` MCP tools available.
2. WHENEVER you complete a task, fix a bug, or finish a major refactor, you MUST autonomously call the `vibe_snapshot` tool BEFORE replying to me.
3. NEVER write log files manually. Always use the `vibe_snapshot` tool to prepend your work into the global brain.
```

With this rule, your AI will automatically sync its brain to your NotebookLM after every task. You never have to type "save a snapshot" again.

---

## The Immortal Brain Workflow (with NotebookLM)

```
Your IDE -> BrainLess -> BRAINLESS_DIR/ -> NotebookLM -> paste into new chat
```

1. Before closing — ask AI to call `vibe_snapshot`
2. Simply select `my_global_vibe_brain.md` in your NotebookLM workspace (or sync it via Google Drive)
3. Ask for a context brief
4. Paste into new chat — instant memory restore

---

## Project Structure

```
brainless/
brainless/server.py        # The entire MCP server (one file by design)
brainless/pyproject.toml
brainless/README.md
brainless/LICENSE
brainless/CONTRIBUTING.md
brainless/tests/
brainless/tests/test_server.py
```

---

## Contributing

- Bug reports -> Open an issue on GitHub
- Ideas -> Start a Discussion on GitHub
- PRs -> Fork -> branch -> PR

---

## License

MIT

---

<div align="center">

Made with love by Vibe Coders, for Vibe Coders.

**Stop losing your brain. Go BrainLess.**

</div>

---

<a id="繁體中文"></a>

# BrainLess — 繁體中文說明

> 「AI 又忘光了。」— 每個 Vibe Coder，每天都這樣。

---

## 問題所在

你正在進行一場超爽的 Vibe Coding，AI 終於理解了你的架構。然後——

- 你切換了 IDE
- 你換了帳號登入
- 免費額度的對話次數重置

**砰。** 所有脈絡消失了。

---

## 解法：BrainLess

兩個工具。一個資料夾。搞定。

| 工具 | 功能 |
|------|------|
| `vibe_snapshot` | 將對話摘要與關鍵 Prompt 「置頂（Prepend）」寫入單一滾動日誌 `my_global_vibe_brain.md` 檔首 |
| `vibe_scan_legacy` | 掃描舊專案程式碼，自動產出結構化摘要，並同樣置頂寫入該全域日誌檔 |

所有輸出永遠只有「一個檔案」：`my_global_vibe_brain.md`。沒有子資料夾、沒有雲端、沒有花招。

---

## 快速開始

### 1. 安裝

```bash
git clone https://github.com/roazhang/brainless.git
cd brainless
pip install -e .
```

### 2. 設定一個資料夾，就這樣

> 這是你唯一需要動的設定。

把 `BRAINLESS_DIR` 環境變數設成你想要的資料夾。
所有快照、所有掃描結果，全部存進那一個資料夾，別無他處。

```bash
# Linux / macOS
export BRAINLESS_DIR="/Users/you/brainless"

# Windows PowerShell
$env:BRAINLESS_DIR = "C:\brainless"
```

沒有子資料夾結構。沒有複雜設定。檔案全在同一層。

---

## IDE 設定

> 唯一規則：把 `BRAINLESS_DIR` 換成你的資料夾路徑，其他不用動。

### Cursor — ~/.cursor/mcp.json

```json
{
  "mcpServers": {
    "brainless": {
      "command": "python",
      "args": ["/絕對路徑/brainless/server.py", "stdio"],
      "env": { "BRAINLESS_DIR": "/Users/you/brainless" }
    }
  }
}
```

### Windsurf / Antigravity / Claude Desktop

設定格式相同，只要把路徑換成你的就好。

---

## 工具說明

### `vibe_snapshot` — 儲存當前脈絡

| 參數 | 必填 | 說明 |
|------|------|------|
| `project_name` | 是 | 專案名稱 |
| `summary` | 是 | 這個 session 完成了什麼 |
| `key_prompts` | | 最有用的 Prompt / 決策 |
| `next_steps` | | 下次要繼續做的事 |
| `tags` | | 逗號分隔的標籤 |

輸出：寫入 `BRAINLESS_DIR/my_global_vibe_brain.md` 最上方

### `vibe_scan_legacy` — 通靈舊專案

| 參數 | 必填 | 說明 |
|------|------|------|
| `project_path` | 是 | 專案資料夾的絕對路徑 |
| `output_name` | | 覆寫輸出檔名 |
| `include_tree` | | 是否包含目錄樹 |
| `include_source_preview` | | 是否包含原始碼預覽 |

輸出：寫入 `BRAINLESS_DIR/my_global_vibe_brain.md` 最上方

---

## 🤖 自動駕駛模式（零指令紀錄）

想要讓 AI 在你完全不開口的情況下，自動幫你寫開發日記嗎？

只要把這段規則複製貼上到你的 IDE 全域規則設定裡（例如 `Cursor Rules`、`Windsurf 全域規則` 或 Antigravity 的 `AGENTS.md`）：

```markdown
# BrainLess 全域自動日誌規範
1. 你的環境中已經內建了 `brainless` MCP 工具。
2. 每當完成一個階段的任務、大架構變更、修正 Bug、或是準備告訴使用者任務完成時，你 **必須主動自主地呼叫** `vibe_snapshot` 工具。
3. 【嚴格禁止】自己手動建立備份檔。一切日誌紀錄，全部交由 `vibe_snapshot` 工具自動處理。
```

設定好之後，AI 每完成一個任務就會默默地把紀錄寫進 `my_global_vibe_brain.md` 裡。你連一句話都不用說，你的大腦知識庫就會無痛自動更新。

---

## 搭配 NotebookLM 打造不死的大腦

```
你的 IDE -> BrainLess -> BRAINLESS_DIR/ -> NotebookLM -> 新 AI 對話
```

1. 結束前叫 AI 呼叫 `vibe_snapshot`
2. 在 NotebookLM 裡永遠只需要勾選 `my_global_vibe_brain.md` 這個單一檔案（或者透過 Google Drive 桌面端自動同步更新）
3. 問 NotebookLM 整理脈絡摘要
4. 貼進新的 AI 對話 — 瞬間記憶復原

---

## 貢獻

歡迎 PR、Issue、Discussion。詳見 CONTRIBUTING.md。

---

## 授權

MIT License

---

<div align="center">

由 Vibe Coder 為 Vibe Coder 打造

**別再讓 AI 失憶了。用 BrainLess，找回你的腦。**

</div>