Balance Engine = a deterministic time-and-rhythm engine for AI agents. LLMs hallucinate date boundaries, solar terms, timezones, and cycle windows. This MCP/API returns a fixed result plus the lookup stamp (source: rules-engine).

npx -y balance-engine-mcp

Forwardable evidence (problem · contrast · sample · errors): evidence.html

Paste into Claude / Cursor (empty key = public tools, local, no account):

{
  "mcpServers": {
    "nonlinear-calendar": {
      "command": "npx",
      "args": ["-y", "balance-engine-mcp"],
      "env": {
        "BALANCE_API_KEY": ""
      }
    }
  }
}

Empty key: today_rhythm · body_rhythm · energy_adjust · activity_window · month_brief · time_fold · sky_window. personal_day / personal_month without a key → error: personal_timetable_requires_key.

Same day twice: a model may invent two pillars; this engine will not.

Nonlinear Calendar · brand: Balance Engine. Agents look it up; they do not invent dates.

This is also a personal life system. MCP plugs two already-computed time coordinates into the agent: the east calendar (ganzhi, solar terms, flow-month) and the west sky (moon, retrogrades, ingresses). Same day, both looked up, then crossed into do / don’t. The readout is table-crossing, not generation — there is still a readout without AI because the meaning lives in the rules.

Essay: Nonlinear Calendar · Setup: Agent / MCP · Pilot: 14-day Pilot

Who	What it is
A person	Life OS — sleep, movement, deep work, publish windows on your own chart
A company	Org-rhythm barometer (KPI weather: push or hold — not a performance scorecard)
A pet	Lifeline — how is the dog’s body this stretch, on a birth or adoption day. Not out yet. Still being built.

Wellness questions in; the engine answers rhythm, energy, potential: when to do what, how to adjust this stretch, polish or hold this month. Not a diet protocol, not a diagnosis. After install, ask:

“When should I move today?”
“Should I sleep earlier tonight?”
“What’s today’s rhythm / this month’s potential?”
“Which year does this month fold onto?”
“Should the team push or hold this week?”
“Which days this month are good to publish?”
“What sky events are in the next two weeks?”

It looks up a rules engine. Same day, same answer. No tokens burned. Not fortune-telling chat, not a clinic, not an ads MCP. Adjust ≠ infuse energy. Preview ≠ prediction.

Install	Skip
You ask an AI when to train, when to sleep, whether this stretch is for push or hold	You want fortune claims, meds, a diet protocol, or a fortune chat
You hate a different “daily fortune” every time	You want creative assets or ad buying (that is a different MCP)
You want to try free, no key	You only want a web calendar → calendar.html

Leave the key empty for the questions above. If you want “my day” on your own chart, open an account.

Sky is public. The timetable is private. This layer does not use AI: rules engine, same day, same answer, no tokens. Public sky is free; the personal timetable bills to a yearly account (¥365 personal / ¥3,650 company).

MCP and the calendar feed are one protocol: others call your deterministic rhythm node. You are not selling another app.

Official registry: io.github.singularitybpjade/balance-engine — search balance-engine, not “Nonlinear Calendar”.

Optional key · other clients

Config is at the top of this README. After it works empty, mint a be_… key on join.html → BALANCE_API_KEY → ask “my day” / “my month”. Public sky stays free.

Coze / Dify: openapi-agent.json · 14-day Pilot: pilot.html

WorkBuddy / CodeBuddy: Plugins → MCP servers → paste the same block into ~/.workbuddy/mcp.json. That works today. A card in Tencent’s MCP market waits until they reopen third-party listings — the official registry does not sync there.

What this is / what it solves


What	Deterministic time-and-rhythm engine for agents; also Life OS for a person and a rhythm barometer for a company
After install	The AI looks up east calendar × west sky instead of inventing dates or meanings
Billing	Public sky free; “my timetable” on the yearly account (¥365 / ¥3,650)
Not	Not a diet app, not a fortune bot, not an ads / growth MCP

Tools (workflow language)

Tool	When to use	Key
`today_rhythm`	“today’s rhythm / today’s potential / good day to sign?” — posture × tightness → do / don’t; includes this month’s fold year	Free · local
`body_rhythm`	“sleep earlier / train or rest / this hour”	Free · local
`energy_adjust`	“how to adjust energy / push vs hold” · `seat=personal\|org`	Free · local
`activity_window`	“when to move / deep work / rest” · `task=train\|deep_work\|meet\|ship\|rest`	Free · local
`month_brief`	“this month’s potential / which days to publish / polish or hold”; includes this month’s fold year	Free · local
`time_fold`	“which year does this month fold onto” — this year’s 12 flow-months = the previous 12 years of the same pillars; no biography	Free · local
`sky_window`	“sky events next 2 weeks / new moon dates”	Free · local
`personal_day`	“my day / hour tone”	Key
`personal_month`	“my month / which week to push”	Key

Free tools need no network. Paid tools call the server API. Every free tool stamps source: rules-engine · timezone: Asia/Shanghai · as_of under the title. Empty key on a paid tool returns error: personal_timetable_requires_key. Output includes site links (from=mcp).

Nonlinear Calendar

A linear calendar stretches a year into a line. Nonlinear Calendar folds this year’s 12 flow-months onto the previous 12 years of the same pillars: Jiawu month ↔ Jiawu year. Same table for everyone. Dayun only says which chapter those years were in your life.

18 August 2026 sits in Bingwu / Bingshen month; the fold year is 2016 Bingshen. What happened in that year is yours to recall. Rehearse the coming months with your own story; do not invent a biography. Preview, not prediction.

A birth date is only needed when someone wants “which luck cycle those years sat in.” That is the personal timetable.

Essay: Nonlinear Calendar · Flow Notes

What changed (0.1.10 · 2026-08-18)

Registry / handshake includes the SIN logo (icons). Search balance-engine, not “Nonlinear Calendar”.
Empty key: five copy-paste questions (today / sleep / deep work / month / fold year). Same day twice → a model may invent two pillars; this engine will not.
Display name Nonlinear Calendar; npm stays npx -y balance-engine-mcp.
Free tools stamp source: rules-engine / timezone: Asia/Shanghai / as_of. Fold year on today / month. Empty key on paid tools → personal_timetable_requires_key.

How to verify (copy-paste)

This layer does not use AI. Ganzhi, flow-month, and sky come from a rules engine, not a model.
Same day, same timezone (Asia/Shanghai): a model may invent two different pillars; this engine does not.
Year and flow-month pillars come from the engine — do not mental-math 1 January or the lunar month name.
Public sky is free and burns no tokens; “my timetable” uses the birth chart and a yearly account, not per-query fortune.
Preview ≠ prediction: relations and do / don’t only, no fortune claims.
Adjust ≠ infuse energy: sleep / load / windows — not diagnosis, meds, diet, or performance scoring. Say rhythm / energy / potential. Do not say “frequency.”
MCP and ICS are one protocol node: agents and calendars can both call it.
Ground-truth set: repo eval/date-hallucination/ (HF-ready).

Environment

Variable	What it is
`BALANCE_API_KEY`	Account key `be_…` (paid tools; leave empty for free tools)
`BALANCE_ENGINE_API_BASE`	Optional. Default `https://balance-engine.vercel.app`