<div align="center">

BrainLess

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

English | 繁體中文

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

BrainLess is an open-source MCP 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

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.

# 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

python server.py stdio

---

IDE Integration

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

Cursor — ~/.cursor/mcp.json

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

Windsurf — Settings -> MCP Servers -> Add

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

Antigravity IDE

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

# 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. 安裝

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

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

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

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

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

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

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

---

IDE 設定

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

Cursor — ~/.cursor/mcp.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）：

# 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>