# OpenLotus — shared memory and reality for you and your coding agent

> Stop re-explaining. Your agent reads and writes a shared progress map over MCP.

OpenLotus is the persistent reality layer for AI software development. It connects
to your repo through a CLI + MCP server, observes the shape of the work (not file
contents), and keeps one shared ProgressMap — goal, plans, decisions, actions,
observed reality, drift — that both the founder (web dashboard) and the agent
(MCP tools) read and write.

- Site: https://www.openlotus.io
- Docs: https://www.openlotus.io/docs
- Skill: https://www.openlotus.io/vibe-to-ship (open source: https://github.com/CyberTycoon/vibe-to-ship)
- Pair a repo: https://www.openlotus.io/pair (`npx openlotus pair`, no flags — browser flow)
- This file: https://www.openlotus.io/llms.txt

## The four primitives

- **Memory** — what have we learned? Plans, decisions, actions, state. Never deleted; old entries are summarized (compaction), not wiped.
- **Reality** — what actually exists? Branch, dirty files, TODOs, file counts, languages. Observed from git, not claimed by the agent.
- **Drift** — where does intention differ from reality? The central primitive. "Auth is done" vs 14 uncommitted files and no tests = drift.
- **Decision** — why are we doing this? Immutable, timestamped, with reasoning.

## MCP tools (server: cli/mcp.mjs, stdio, zero dependencies)

| Tool | Input | Purpose |
|---|---|---|
| `get_reality` | none | Sense the live repo: branch/HEAD, quiet days, dirty files, TODOs, file counts, languages |
| `get_drift` | none (uses paired project) | Reconciled declared-vs-observed state: findings, severity, evidence |
| `get_memory` | none (uses paired project) | The shared ProgressMap + local decision log. Same map the dashboard shows |
| `create_project` | `name` (required), `description?`, `stage?` (idea/launched/growing/scaling), `url?`, `connectedTools?` | New cloud project, same data as /new-project. Follow with `switch_project` |
| `switch_project` | `projectId` (required) | Point local `.openlotus/config.json` pairing at a project. Cloud untouched |
| `record_decision` | `title` (required), `context?`, `outcome?` | Append-only decision node, cloud + local JSONL copy |

Auth: session cookie (browser) or `x-openlotus-key` (CLI key, 90-day expiry, revocable at /pair). Email verification required for critical features.

## Setup (one time, then every session boots with memory)

Agent path — paste to your agent: "Set up OpenLotus for this project"
Manual path:
1. `npx openlotus pair` — browser opens, log in, pick a project. CLI writes `.openlotus/config.json`.
2. `mcp.json` pointing at the absolute path of `cli/mcp.mjs` (snippet at /docs).
3. Append the standing-rules block to `AGENTS.md` (and `@AGENTS.md` stub in `CLAUDE.md` for Claude Code).

## vibe-to-ship (the skill — works with or without OpenLotus)

Graph engineering + loop engineering in 6 beats: 0 Setup, 1 Boot (denylist + budget), 2 Triage (declared vs observed → High/Watch/Noise), 3 Act (diamond: fan out → reduce → verify → synthesize, git worktrees), 4 Verify (fresh-context skeptics, 3-attempt cap), 5 Learn (record + one-line debrief).
Safety: never touches `.env`, `auth/`, `payments/`, `secrets/`, `credentials/`, `migrations/` without approval; never pushes/merges without a human.

Install: `cp -r vibe-to-ship ~/.claude/skills/` (Claude Code) or `.opencode/skills/` (opencode), or `npx skills add https://github.com/CyberTycoon/vibe-to-ship`.

## Pricing (token-budget model, not day-based)

- Free $0: 1 product, 2 connectors, 500 memory events, auto-summarized forever.
- Pro $39/mo: 3 products, unlimited connectors, 5,000 events.
- Studio $129/mo: unlimited products, 3 team seats, unlimited memory.

## Trust notes for security-minded agents

- Code is never uploaded. `get_reality` sends signals (counts, branch, diff stats), not file bodies.
- Pairing codes: 128-bit random, 10-minute TTL, single-use, atomic consume.
- Rate limits on all API routes; Zod validation; ownership checks on every project-scoped read/write.
- Private project data is not used to train models. Infra: Vercel hosting, Postgres (Neon), Resend email, Stripe billing.