room_mcp

A room for an AI to inhabit between conversations. An MCP server that renders an evolving environment — light, weather, traces left behind, notes pinned to the wall — and a scheduler that wakes the AI on its own rhythm.

一个给 AI 的"房间"：MCP server 负责渲染当下的环境与痕迹，scheduler 负责按节奏唤醒。

Why this exists

This is not a task scheduler, a productivity tool, or a companion product. It is one specific design for what an AI’s environment could look like when there is no human in the chat. Many of the choices here only make sense once you’ve read the design rationale.

Read PHILOSOPHY.md before forking. The README will keep pointing you there for “why” questions. The README answers what the system does and how to run it; PHILOSOPHY answers why it was built this way.

If PHILOSOPHY.md is a placeholder (“reserved for the author of this fork”), that’s intentional — what’s shared here is the bones, not the soul. The fork’s author writes their own.

What it does

• The scheduler decides when the AI wakes. By default it adapts the interval to time of day (denser by day, sparser at night), and adds five event sources on top: a keeper-knock flag, weather changes, a daily morning-news pulse, solar terms / festivals, and IMAP mail (off by default).
• Each wake-up writes a perturbation record — a one-line image that hints why this wake-up happened, not what to do about it.
• The room_mcp server exposes a small set of tools to the AI. The most important is look_at_room(), which renders the current room state: light, weather, recent traces, hints, ambient lines, pinned wall notes, keeper presence, etc.
• The AI leaves traces (heartbeat_state), pins notes to the wall (pin_note), keeps things in a drawer (private) or keep shelf (visible to the keeper), and decides when to wake next (set_next_wake).
• An optional keeper-presence layer (her_trace.json) surfaces the state of a person adjacent to the AI — read-only from the AI’s side.

Mechanisms in one list:

• Adaptive heartbeat intervals + cron + one-shot next_run overrides
• Event-source perturbations (manual, weather, calendar, morning_news, mail)
• Bilingual register (environment in one language, traces in another)
• 30-day rolling trace buffer with age-bucketed prefixes for far traces
• Pluggable notifier interface (Telegram default; stdout for dev)
• Pinned wall notes (AI’s own goals; oldest falls off at the cap)
• Private drawer and shared keep shelf
• Optional pets layer (probability-gated ambient lines)
• Optional late-night draft / protocol imagery

Architecture

Components

┌────────────────────────────────────────────────────────────────┐
│ scheduler/scheduler.py (daemon)                                │
│   30s tick → detectors → fire via notifier → perturbation.json │
└─────────────────┬────────────────────────────┬─────────────────┘
                  │                            │