Steward（管家账本）

The ledger behind the floating orb: every workspace reports what it did, the orb reads the report. An append-only event log plus four MCP tools — no chat transcripts, no models, no dependencies beyond the standard library.

悬浮球（管家）背后的账本：每个工作区干完活交一行回执，管家随时汇报。只增不改的事件表 + 四个 MCP 工具，纯标准库。

Platform support: macOS — supported (developed & verified on this machine) · Windows — unverified (paths are cross-platform in the codebase, but no real-machine testing yet).

中文说明 · License: AGPL-3.0-only

Why a ledger instead of a transcript

The orb has to answer "what is going on right now?" without holding every conversation in context. Events do that: who, what, outcome, file, at most three numbers. A transcript grows until the context window dies; a ledger stays bounded and stays answerable.

The injectable column is the gate: progress chatter is written down but never reaches the brief. Only events that answer a question get injected.

Related MCP server: factlog

Tools (MCP)

The contract

• Workspaces never write the ledger directly. They call report_done and hand back a receipt. One writer, one schema, no two code paths disagreeing about what an event means.

• Append-only. No updates, no deletes in the tool surface; history is the point.

• Bounded injection. metrics keeps the first three keys; injectable=false marks progress events that belong in the log but not in the brief.

Wire it up

# stdio MCP server, no third-party packages
python3 mcp_server.py

Storage: ~/Documents/ShadowRoom/_steward/ledger.db (SHADOWROOM_STEWARD_DB overrides it). Delete that file to reset the ledger; nothing else references it.

Development

python3 -c "import ast,sys; ast.parse(open('mcp_server.py').read())"
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python3 mcp_server.py