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.

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.

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

Output: Prepend to BRAINLESS_DIR/my_global_vibe_brain.md

vibe_scan_legacy — Reverse-engineer a forgotten codebase

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

Made with love by Vibe Coders, for Vibe Coders.

Stop losing your brain. Go BrainLess.

BrainLess — 繁體中文說明

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

問題所在

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

• 你切換了 IDE

• 你換了帳號登入

• 免費額度的對話次數重置

砰。 所有脈絡消失了。

解法：BrainLess

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

所有輸出永遠只有「一個檔案」：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 — 儲存當前脈絡

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

vibe_scan_legacy — 通靈舊專案

輸出：寫入 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

由 Vibe Coder 為 Vibe Coder 打造

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