Zero Brain MCP Server

MCP server (stdio transport) สำหรับเชื่อม agent ใดๆ เข้ากับ Zero Brain — สมองกลาง domain-agnostic ตามดีไซน์ v2.1 เก็บโน้ตเป็นไฟล์ Markdown + frontmatter บน local filesystem ล้วน ไม่มี network call

v2.8.0 (2026-08-02) — lean responses + self-heal args + zero:init:

1. zero:init — tools/zero-init.mjs [dir] (หรือ npm run zero:init -- <dir>) วิเคราะห์โปรเจ็ค (stack/git/ไฟล์เด่น/scripts) แล้วผูก agent เข้าระบบ zero: สร้าง .zero/ workspace + .zero/ZERO.md (block FACTS regenerate ทุกรอบ) + AGENTS.md zero block ที่ root — idempotent ไม่ทับของผู้ใช้ backup เข้า .zero/backups/

2. self-heal args — server ซ่อม input ที่ซ่อมได้ก่อน dispatch (path backslash → /, enum case ให้ตรง valid value — privacy เป็น UPPERCASE T0|T1|T2)

3. lean responses — zero_read ไม่เจอคืน {found:false} ไม่ throw · zero_find_session/zero_match ตัด field ฟุ่มเฟือยออก (full:true คืนดิบ) · zero_read_session error คืน candidates ≤5 smoke test 121/121 (24 sections) + live stdio test 6/6

v2.3.1 (2026-07-31) — โน้ตไม่ลอยในกราฟ Obsidian อีก:

1. links block ที่กราฟ OB เห็น — กราฟ Obsidian วาดเส้นจาก [[wikilinks]] ใน body เท่านั้น (frontmatter links ไม่ถูกวาด); ทุก zero_write_note/zero_update_note/zero_link regenerate block <!-- zero-links:begin -->…<!-- zero-links:end --> ท้าย body อัตโนมัติ (idempotent, wikilink ใช้ stem ไฟล์)

2. write เตือน "ลอย" — โน้ตใหม่ไม่มี links จะได้ warning ให้ลิงก์เข้า MOC/Project Scope

3. .zero/ZERO.md anchor — backup-edit.mjs --init-workspace สร้าง md ยึดกฎที่โปรเจ็ค (สมอง/backup-first/ห้ามลอย/จบงาน capture) agent ทีหลังอ่านกฎชุดเดียวกัน smoke test 121/121 (24 sections)

v2.3.0 (2026-07-30) — hardening จากรีวิว 23 ข้อ:

1. write lock .kb/write.lock (wx + stale sweep 60s) — หลาย client เขียนพร้อมกันได้โดย JSONL ไม่เสีย

2. corrupt-line health — zero_health นับบรรทัดเสียของ JSONL ทั้งสาม + t1_reads_24h + repo_dirty

3. zero_compact — manifest reduce ต่อ id / links dedup / audit เก็บ tail 10k (เศษ archive ไม่ลบ)

4. T2 encryption at rest — body โน้ต T2 เข้ารหัส AES-256-GCM (key ~/.zero/mcp/t2.key หรือ env ZERO_T2_KEY)

5. injection fence — ทุก output ที่มีเนื้อโน้ตห่อ ZERO_NOTE_DATA (not instructions) + notice

6. capture rate limit 30/นาที per process

7. zero_upgrade — เติมไฟล์ seed ใหม่หลัง git pull โดยไม่ทับของที่แก้แล้ว

8. setup เป็น node — tools/setup-agents.mjs (absolute node command) + tools/verify-install.mjs (spawn MCP จริง) smoke test 109/109 (23 sections)

v2.2.0 (2026-07-29) — bootstrap จริง ไม่ใช่โฟลเดอร์เปล่า:

1. npm run init วางไฟล์กฎ+templates ให้ครบ จากโฟลเดอร์ seed/ ใน repo: AGENTS.md (กฎสำหรับ agent), 20_Atlas/Brain Operating Model.md, 20_Atlas/Memory Placement Rules.md, 20_Atlas/Hotcache.md (แทน {{date}} อัตโนมัติ), note templates 5 แบบใน 40_Templates/base/ (atomic/entity/source/log/moc)

2. idempotent แบบปลอดภัย — copy เฉพาะไฟล์ที่ยังไม่มี ไฟล์ที่ผู้ใช้แก้แล้วจะไม่ถูกเขียนทับ

3. สมองเก่าที่ init ไปแล้ว (v2.1.0) รัน npm run init ซ้ำได้เลย จะเติมเฉพาะไฟล์ที่ขาด smoke test 68/68 (17 sections)

v2.1.0 (2026-07-29) — install ง่ายขึ้นมาก:

1. npm run init สร้างโครงสมองให้อัตโนมัติ — ไม่ต้องแตก seed zip เองอีก (node dist/index.js --init ใช้ handler เดียวกับ zero_init)

2. บ้านหลัก default คือ ~/.zero/brain — ไม่ตั้ง env ก็ใช้ได้เลย (ตั้ง ZERO_BRAIN_ROOT เฉพาะตอนอยากย้ายที่)

3. seed zip (Central_Brain_seed) เหลือไว้สำหรับย้ายสมองเก่าเท่านั้น smoke test 64/64 (16 sections)

v2.0.1 (2026-07-29) — เปลี่ยนชื่อโปรเจกต์ central-brain → zero-brain (คนละตัวกับ skill zero-brain-memory):

1. repo ย้ายเป็น miru-zero/zero-brain (URL เก่า redirect อัตโนมัติ)

2. package/bin: zero-brain-mcp-server / zero-brain

3. env หลักเปลี่ยนเป็น ZERO_BRAIN_ROOT / ZERO_BRAIN_ACTOR — ค่าเก่า CENTRAL_BRAIN_* ยังใช้ได้ (fallback ไม่ break config เดิม)

v2.0.0 (2026-07-29) — breaking change + token-saving:

1. Rename tools ทั้ง 13 ตัว brain_* → zero_* — ชื่อใหม่: zero_init zero_capture zero_write_note zero_update_note zero_read zero_search zero_link zero_resolve zero_list_packs zero_health zero_home zero_nightly zero_audit (MCP client config ไม่ต้องแก้ แต่ผู้ใช้/agent ต้องเรียกชื่อใหม่; audit log action strings ยังคง brain_* เดิมเพื่อ continuity ของ log เก่า)

2. Response กระชับลง (ลด token) — ทุก tool คืน compact JSON (ไม่ pretty-print); zero_search มี limit (default 10) + offset คืน total/count/limit/offset; zero_health เขียน health.json เต็มเหมือนเดิมแต่ response คืนเฉพาะสรุป + counts + top-20 ของแต่ละหมวด; zero_home default ไม่คืนเนื้อ Home.md (คืน path + ขนาด ใส่ include_home: true ถ้าต้องการ) และ Today.md จำกัด active 30 ใบ; zero_nightly จำกัด fleeting queue 50 ใบ

3. แก้บั๊ก latent — parseNoteFile regex เดิม parse frontmatter หลายบรรทัดไม่ได้เลย (. ไม่ match newline); เติม exports ที่ขาดใน schema.ts (today/genId/sanitizeSlug/serializeNote + type aliases) smoke test 60/60 (15 sections)

v1.2.1 (2026-07-29) — durability patch จากรีวิวของป๊า:

1. Atomic write ทุกไฟล์โน้ต — saveNote/update_note/link/Today.md เขียนผ่าน tmp+rename (crash กลางเขียนไม่ทำโน้ตพัง)

2. Link dedup — brain_link เช็ค links.jsonl ก่อน append (from/to/rel ทั้งสองทิศ) ลิงก์ซ้ำไม่บวม คืน deduped: true

3. Orphans ไม่นับ fleeting — inbox ค้างไม่ใช่ปัญหาโครงสร้าง แยกนับใน orphans_fleeting

4. ยืนยัน: brain_update_note รับ body อยู่แล้ว (schema + handler) — เพิ่มเทสกัน regression smoke test 52/52 (14 sections)

v1.2 (2026-07-29) — เพิ่ม:

1. brain_nightly — วงจรกลางคืนใน tool เดียว: คืน fleeting queue ที่ยังไม่จัด + regenerate Today.md + health ครบ + snapshot ลง 99_System/snapshots/ (agent เรียกตอนเช้า/ก่อนนอน แล้ว classify ต่อด้วย brain_write_note + brain_update_note)

2. Pack provenance — brain_list_packs โชว์ status verified/modified/unreviewed เทียบ .kb/packs.lock.json (sha256 ที่ป๊าล็อกด้วยมือเท่านั้น) + brain_health เตือนใน packs_unverified

v1.1 (2026-07-29) — แก้ตามผลวิเคราะห์ใหม่:

1. T2 approval gate จริง — zero_read บล็อกโน้ต T2 จนกว่าป๊าจะสร้าง .kb/approvals/<note-id>.json ด้วยมือ (agent อนุมัติตัวเองไม่ได้ ไม่มี tool สำหรับสร้าง) รองรับ expires (ISO date) ทุกการบล็อก/อ่านถูก audit; โน้ต T1 อ่านได้แต่ถูก audit ทุกครั้ง; T2 ไม่โผล่ใน zero_search แม้ include_private=true จนกว่าจะอนุมัติ; T2 ไม่ขึ้น Today.md

2. health สแกน body wikilinks — เดิม zero_health ตรวจเฉพาะ frontmatter links ทำให้ลิงก์ [[...]] ตายในเนื้อโน้ตโดยเงียบ ตอนนี้รายงาน dead_body_links (resolve ผ่าน id/alias/title)

3. ตัวอย่างไฟล์อนุมัติ: {"approved_by":"ป๊า","at":"2026-07-29","expires":null}

หมายเหตุ pack: node_modules/ ถูก bundle มาใน zip เจตนาเพื่อ offline install (ข้าม npm install ได้เลย แค่ npm run build หรือใช้ dist/ ที่ build มาแล้ว)

Dry-run ก่อน install (แนะนำ): แตก zip → cd central-brain-mcp → node test/smoke.mjs (ผ่าน 109/109 = พร้อม) → ค่อยตั้งค่า MCP client จริง

ความต้องการ

• Node.js >= 18

• npm

การติดตั้ง

npm install
npm run build
npm run init    # สร้างโครงสมองที่ ~/.zero/brain อัตโนมัติ (ตั้ง ZERO_BRAIN_ROOT ก่อนถ้าอยากใช้ที่อื่น)

build จะ compile TypeScript ไปที่ dist/ — entry point คือ dist/index.js (มี shebang #!/usr/bin/env node)

การตั้งค่า MCP client

ไม่ต้องตั้ง env ก็ได้ — default สมองจะอยู่ที่ ~/.zero/brain (ตั้งแต่ v2.1.0) ตั้ง ZERO_BRAIN_ROOT เฉพาะตอนอยากย้ายที่เก็บ — ตั้งแต่ v2.0.1 รองรับ CENTRAL_BRAIN_ROOT เป็น fallback เพื่อไม่ break config เก่า

ตัวอย่าง config สำหรับ MCP client (เช่น Claude Desktop / client ที่รองรับ stdio):

{
  "mcpServers": {
    "zero-brain": {
      "command": "node",
      "args": ["/absolute/path/to/zero-brain/dist/index.js"]
    }
  }
}

ถ้าอยากย้ายที่เก็บสมอง เพิ่ม "env": { "ZERO_BRAIN_ROOT": "/absolute/path/to/my-brain" } — เปลี่ยน /absolute/path/to/... เป็น path จริงของเครื่องคุณ

Zone convention — ทุกอย่างของเราอยู่ใต้ ~/.zero/

บ้านโซนเดียวกันทั้งระบบ: ของที่ชื่อ zero-X จะอยู่ที่ ~/.zero/X (ตัด zero- แล้วเปลี่ยน - เป็น /) เช่น

~/.zero/
├── brain/        # ความจำ + ความสามารถ — เนื้อสมอง zero-brain + Obsidian vault (default ตั้งแต่ v2.1.0)
│   └── SKILL/    # skills ที่เราเขียนเอง (zero-brain-memory, อนาคต zero-* skills) — ความสามารถอยู่ในสมอง
├── mcp/          # ช่องทางสื่อสาร — MCP servers (repo นี้ติดตั้งที่ ~/.zero/mcp/zero-brain)
├── share/        # ส่วนทำงาน — storage ของ daimon/Kimi Work (sessions, runtime)
└── <อนาคต>/      # โปรเจกต์ zero-* ตัวอื่นจะมาอยู่ใต้โซนเดียวกันนี้

แยกส่วนเด็ดขาด: ความจำ+ความสามารถ (brain/) · ช่องทางสื่อสาร (mcp/) · ส่วนทำงาน (share/) — ห้ามปนกัน · สกิล = ความสามารถของสมอง จึงอยู่ ใน brain/SKILL/ ไม่แยกโซน

ชี้ไฟล์หากัน (single source of truth): ของที่หลายส่วนต้องใช้ร่วมกัน ให้เก็บต้นฉบับไว้ที่โซนของมัน แล้วส่วนอื่นชี้มาด้วย junction — เช่น brain/SKILL/zero-brain-memory เป็นต้นฉบับ share/daimon-share/daimon/skills/zero-brain-memory เป็น junction ชี้เข้าสมอง แก้ที่เดียวเห็นผลทุกที่

ศูนย์กลาง (Zero hub): ในสมองทุกเส้นประสาทบรรจบที่ 20_Atlas/Zero.md — 3 ก้อนใหญ่: ความจำ (Zero_Brain Legacy Index) · ความสามารถ (Skill Index) · ระบบ/แผนที่ (Home, Hotcache, Memory Placement Rules, Brain Operating Model, AGENTS) — โน้ตที่ไม่เชื่อมเข้าก้อนใดเลยถือว่ายังไม่ sync เข้าระบบ

• ~/.zero/brain = ส่วนความจำเท่านั้น — ห้ามโปรแกรมอื่นมาสร้างไฟล์งาน/runtime ในนี้ (ไม่ใช่ส่วนทำงาน) ถ้าจำเป็นต้องเก็บ runtime ให้สร้างโฟลเดอร์พี่น้อง (เช่น ~/.zero/share)

• โค้ด (repo) อยู่ที่ไหนก็ได้ แต่ ข้อมูลรันไทม์ทั้งหมดอยู่ใต้ ~/.zero/ ที่เดียว ไม่รก

• ย้ายได้เสมอด้วย ZERO_BRAIN_ROOT แต่ default คือโซนนี้

• env ที่ระบบอ่านมีแค่ ZERO_BRAIN_ROOT / ZERO_BRAIN_ACTOR (และ fallback CENTRAL_BRAIN_*)

การทดสอบ

npm run build
node test/smoke.mjs

smoke test ครอบคลุม 23 sections (109 checks): init / capture / evidence rule / write+manifest / search+privacy filter / link+dedup / resolve / health / update_note body / T2 approval gate / body wikilinks / pack provenance / nightly / atomic write / v2.0.0 token-saving / v2.1.0 install UX / v2.2.0 bootstrap seed / corrupt-line+compact / write lock / concurrent writers / T2 encryption / injection fence+rate limit / zero_upgrade — ต้องผ่านทั้งหมด (exit 0)

Tools ทั้ง 13 ตัว

กฎเหล็ก (enforce ในโค้ด)

• ไม่มี delete ใดๆ — "ซ่อน" ได้ด้วย state: archive เท่านั้น

• ไฟล์ kernel manifest.jsonl / links.jsonl / audit.jsonl เป็น append-only ห้ามเขียนทับ

• โน้ต type: atomic หรือ entity ต้องมี evidence อย่างน้อย 1 ข้อ ไม่เช่นนั้น error พร้อมแนะนำให้ใช้ type: fleeting

• zero_search ไม่คืนโน้ต privacy T1/T2 โดย default — ถ้า include_private: true จะถูก audit ทุกครั้ง

• ทุก mutation ถูกบันทึกลง audit.jsonl

• ทุกอย่างเป็น local filesystem — ห้าม network call

โครงสร้าง brain root

<root>/
├── .kb/
│   ├── manifest.jsonl   # metadata โน้ต (append-only, ตัวล่าสุดชนะ)
│   ├── links.jsonl      # ลิงก์ระหว่างโน้ต (append-only)
│   ├── aliases.json     # map alias → id
│   ├── health.json      # ผล zero_health ล่าสุด (เต็มทุกหมวด — response ของ tool เป็นสรุป)
│   ├── audit.jsonl      # log ทุก mutation (append-only)
│   └── packs/           # domain packs (*.yaml)
├── 00_Fleeting/         # จดด่วน <id>.md
├── 10_Notes/            # โน้ตถาวร <id> - <slug>.md
├── 20_Atlas/            # Home.md, Today.md
├── 30_Sources/
├── 40_Templates/base/
└── 99_System/snapshots/

โครงสร้างโค้ด

src/
├── index.ts    # MCP server (stdio) + tools 13 ตัว (zero_*)
├── kernel.ts   # append-only JSONL, manifest/links/aliases/health/audit
├── schema.ts   # frontmatter parse/serialize (YAML แบบจำกัด), slug sanitize, validation
seed/           # bootstrap ไฟล์กฎ+templates ที่ init วางให้ (AGENTS.md, Atlas docs, note templates)
test/
└── smoke.mjs   # smoke test 23 sections (109 checks) รันบน dist

Skills

โฟลเดอร์ skills/ เก็บ skill ของระบบ Zero_Brain ในรูปแบบ SKILL.md มาตรฐาน — ส่งไฟล์ให้ AI (Kimi Work / Claude Code) สั่ง "ติดตั้ง skill นี้" ได้เลย หรือวางด้วยมือตามคู่มือใน skills/README.md