理脈 limai

Rika and Ritsu's shared nervous system — an independent organ extracted from the character based on first principles.

First-Principles Derivation

Discarded: the character's LLM task prompts (personality not carried over), the JS eval trigger in memory (security). Retained essence: weighted random scheduling idea → heartbeat backoff; STALE_READ guard; SSRF protection; bounded reads.

Related MCP server: exobrain-mcp

Startup

npm install
npm run start          # ① stdio → Claude Desktop / Cursor 等本地客戶端
npm run serve:http     # ② HTTP MCP → GPT 客戶端 / 區網 / 遠端
npm run tick           # ③ 手動跑一次心跳（驗證感知層）

CLI Designed for AI Agents

limai shot                       # → {"file":...,"width":1920,"height":1080,"bytes":...}
limai win                        # → {"foreground":...,"windows":[{process,title},…]}
limai clip [--json]              # 剪貼簿原文走 stdout（利於管線）
limai tick                       # 心跳一次，生命徵象 JSON
limai web search <q>             # → [{title,url,snippet},…]
limai web fetch <url>            # 正文走 stdout、中繼 stderr；--json 得全包裝
limai fs ls|read|write|edit|find|grep …
limai mem … / limai todo …       # 同前

Agent contract:

• Outputs JSON by default, error codes prefixed into stderr messages (STALE_READ: …), non-zero exit code indicates failure

• fs edit follows the same strict contract as MCP: must fs read first; observation state persists in fs-state.json, so the "read session → edit session" flow still holds across calls, and external changes are always intercepted (--force can bypass)

• A successful fs write also establishes an observation and can be followed by edit (same as o-pi's "immediately after successful write" rule)

Architecturally, MCP is just one interface above the core modules: the same vision/web/filesys/memory/todo/heartbeat set serves both CLI subcommands and MCP tool calls, and both interfaces share the same data and the same security contract.`

First run automatically creates ~/.limai/ (config.json・memory.json・todo.json・vitals.*・screenshots/) and prints the token.

Client Integration

Local (stdio)

// claude_desktop_config.json
{ "mcpServers": { "limai": { "command": "node", "args": ["F:\\fount開發項目\\理脈\\src\\cli.mjs", "serve", "--stdio"] } } }

LAN / Same-Machine GPT Clients (Cherry Studio, LobeChat, OpenWebUI…)

node src/cli.mjs serve --http                # 預設 127.0.0.1:8931
# 對區網開放：--host 0.0.0.0 --token <強密碼>

{ "type": "http", "url": "http://192.168.x.x:8931/mcp",
  "headers": { "Authorization": "Bearer <token>" } }

Cloud ChatGPT (Connectors / Developer Mode)

ChatGPT can't reach your localhost — it needs public HTTPS: a one-line tunnel:

cloudflared tunnel --url http://127.0.0.1:8931
# → https://xxxx.trycloudflare.com

Fill the connector URL with https://xxxx.trycloudflare.com/mcp?token=<token> (GPT-type clients mostly can't customize headers, so query-based token passing is supported). Long-term options: Tailscale Funnel (no port opening) or Caddy reverse proxy on your own domain.

Security Boundary

• Files: locked to allowedRoots in config.json; .git permanently blocked; fs_edit must fs_read first (STALE_READ version guard); old text must be unique

• Network: rejects localhost/private/link-local (SSRF), per-hop redirect re-check, 2MB cap, 30-second timeout

• Auth: Bearer/query-token throughout HTTP; binds to 127.0.0.1 by default

• Privacy: heartbeat only records window titles + clipboard hashes (stores a 60-character preview on change); pixel screenshots only on explicit screen_capture calls

Heartbeat Semantics (Inherited from Rika)

One beat every 15 minutes (adjustable via heartbeat.intervalMin). Each beat collects: foreground window・window list (top 8)・idle seconds・clipboard changes・open todo count. On failure the interval ×2 (cap 8×), reset on success. Logs append to vitals.ndjson.

Upstream Sync (o-pi)

• 2026-08-23 check: that day's upstream commits were internal refactoring (file-tools/web-tools/filesystem/lsp simplification); the behavior contracts of the six tools plus two web tools are unchanged; duckduckgo-html-provider remains the zero-key fallback path — Limai's extraction is still faithful.

• New capability: read supports PDF page images (d762209): Limai has aligned its implementation — fs_read adds a pages parameter (N / N-M / N-), returning MCP image content blocks of page PNGs; CLI uses fs read <pdf> --pages "1-5". Primary path: PDF.js (pdfjs-dist legacy) + @napi-rs/canvas for cross-platform rendering; on Windows, auto-falls back to the built-in WinRT Windows.Data.Pdf when dependencies can't load. Default cap of 20 pages per call, including total page count and resume position.

• skill URI / bash tools / approval gate are Pi-host-specific and outside the extraction scope.

• Second check same day (d795f92 new approval UI): only touches src/approval/* and the TUI; file-tools/web-tools have zero changes. Grep contract alignment completed accordingly: invalid regex degrades to an exact literal — on a hit → returns literal_fallback warning; zero hits → INVALID_REGEX, no faking empty results. Tested and passing.

License & Attribution

This project is released under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later); full terms in LICENSE.

Code source attribution:

• File tools (src/core/filesys.mjs: ls/read/write/edit/find/grep) and web tools (src/core/web.mjs: web_search/web_fetch) have behavior contracts and design derived from Orion-zhen/o-pi (Pi Agent's file-tools and web-tools design docs, AGPL-3.0 licensed). Limai is an independent zero-dependency Node.js implementation of their essence, not code copying, open-sourced back under the same AGPL terms.

• The extraction blueprint for capability primitives such as heartbeat/todo/memory/vision comes from the "Rika" character's capability design in the steve02081504/fount ecosystem (MIT licensed). Only its architectural ideas were referenced (idle polling backoff, weighted tasks, name × keyword × content memory); no code was copied.

• MCP protocol implementation is based on the official @modelcontextprotocol/sdk.

• PDF rendering depends on pdf.js (Apache-2.0) and @napi-rs/canvas (MIT).