The manual for building with memory.
OpenLotus is a memory holder, visualizer, and utilizer for your AI agents. Your agent remembers what you decided, where reality drifted, and what to do next — without you re-explaining. This guide explains everything in plain language, with code you can copy.
No jargon, no theory — just how to use it today.
With the skill: say “set up OpenLotus” and it does the three files. Without it: copy the three blocks below — same result, one time. Pick one.
What is OpenLotus
A shared memory between you and your agent. Not a chatbot, not a dashboard — a place that holds the context.
The skill works great on its own — it organizes work so your agent can handle more at once. Paired with the OpenLotus memory, every plan it makes is anchored in your real project and every result lands where you can see it.
- Progress map — the shared tree
- Dashboard — your week, summarized
- Workspace — talk with the map loaded
Connecting your agent
You have two paths. Let the skill do it, or do it by hand.
Recommended: paste one sentence to your agent. It detects what’s missing (mcp.json? pairing? rules file?) and finishes the rest.
Works in Claude Code and OpenCode — the skill writes the two small files and tells you what it did.
You have access to OpenLotus MCP tools (get_reality, get_drift, get_memory, record_decision, create_project, switch_project). At session start: call get_memory and get_reality, then report drift (declared vs observed) as High / Watch / Noise before writing code. After meaningful work: call record_decision with title + why. Never claim tests pass without running them. Full primer: https://www.openlotus.io/llms.txt
For agents that fetch context themselves: openlotus.io/llms.txt
Want to do it yourself? The manual steps are one copy-paste each:
- mcp.json — tells your agent how to launch OpenLotus
- npx openlotus pair — links this repo to a project (browser)
- AGENTS.md / CLAUDE.md — one rule block so every session stays in sync
- Skill does it automatically if not set up
- Or three copy-pastes by hand
- Homepage “Connect your agent” + /dashboard/connectors both show the code
Pairing a project
Browser-based, no flags. Run one command, pick a project on the web.
Run npx openlotus pair — it opens your browser to /pair. Log in — or create an account if you don’t have one — then pick a project.
No --email --password flags. The browser handles auth; the CLI just waits for your pick.
- Auth URL opens in your browser
- Creates a new project if you need one
- Links this local repo to your choice
What is mcp.json?
A small config file that tells your agent how to start OpenLotus.
Think of it as a launcher. It says: “when you start, run this command to talk to OpenLotus.” You create it once. After that the agent has the tools in every session.
Where in the UI? The code is shown boldly on the homepage (“Connect your agent” section) and at the top of Dashboard → Connectors. The skill also creates it for you.
- One JSON snippet, one path to fix
- Makes 4 tools appear in every session
- Skill writes it if it’s missing
{
"mcpServers": {
"openlotus": {
"command": "node",
"args": ["…/cli/mcp.mjs"]
}
}
}Fix the absolute path to your clone, restart the client.
The vibe-to-ship skill
A 5-step routine your agent follows to ship without drift — built from real shipping expertise, packaged as graph engineering.
If a triage shows nothing actionable, the skill stops in ~5k tokens — it doesn’t burn credits running nothing.
Read the full skill guide →- Open-source, drop-in for Claude Code & OpenCode
- If setup missing, Beat 1 finishes pairing first
- Manual or agent-driven — your choice
What triage does & why
Triage is the honest check before your agent moves.
It compares what you said you’d do (the tree) to what actually happened (git, dirty files, TODOs) and outputs a High / Watch / Noise list.
Without triage, agents invent a plan. With it, they start from the last verified reality.
Run with: “Run vibe-to-ship triage” or let the Beat 1 auto-check run.
- Catches drift before acting
- Early exit when nothing actionable
- Reconciles declared vs observed
Hooks & safety net
Hooks enforce the loop even when the agent forgets.
Optional safety net: your agent automatically checks for drift when it starts, so it flags problems before it acts. No extra cost, works even if the agent ignored the earlier rules.
There’s also a built-in safety net without hooks: if the map drifts from git (e.g., 12 uncommitted files while the milestone claims done), the next get_drift flags it as risk. Drift is information, not failure.
- SessionStart: prints drift at boot
- Budget cap: switches to report-only at 80%
- Max 3 fix attempts, then escalate
Timestamps
Every action is stamped. No anonymous edits.
Milestones, decisions, risks, evidence, milestones — each carries createdAt. Snapshots carry capturedAt + syncCount. Reviews carry lastReviewAt.
You see them as relative times in the dashboard and absolute times when you expand a node.
- Milestones · decisions · evidence: createdAt
- Snapshots: capturedAt + syncCount
- Reviews: lastReviewAt, trajectory
Memory & compaction
Your recent history, fully detailed. Older history, summarized — never deleted.
How much stays detailed depends on your tier’s event budget — Free holds about 500 events, Pro about 5,000, Studio is unlimited — not on calendar days. A quiet week (dozens of events) costs almost nothing; a heavy week with thousands compacts sooner. Older entries become time-stamped summaries you can still read.
- Free: ~500 events full-detail, then summaries
- Pro: ~5k events; Studio unlimited
- Summaries never expire
10M vs 1k tokens → same 7-day SLA, different burn rate; compaction adapts.
Security
Your code never leaves your machine.
OpenLotus reads your work’s shape — what changed, what you decided, where things drift — not your files. get_reality sends counts and branch names, never file bodies. Tools are capability-scoped (e.g., github.read), never “all access.”
- Never reads file contents
- Per-tool capability checks
- Pairs are per-project, not per-org