FlowState Hosted

FlowState

A shared project memory for your AI apps. Free, open source, and stored on your own machine.

Don't want to run a server? Try FlowState Hosted.

The same shared memory, hosted for you at flowstatemcp.com/hosted.

Add one URL (https://hosted.flowstatemcp.com/mcp) to Claude, ChatGPT, Cursor or VS Code and sign in.

No install, no Python, no tunnel. Your data is encrypted at rest and backed up, and you can export or erase it any time.

Beta: 6 months free, then $6/mo for beta members ($12/mo regular). No card needed to start. 10 beta spots.

Prefer to keep everything on your own machine? Keep reading: local FlowState is free and MIT forever.

FlowState is a local MCP server. It gives every AI app you use the same memory of your projects: todos, changes, decisions, problems and lessons learned. Your AI reads a short brief when it starts work on a project and writes down what happens as it goes. The next chat (or the next app) picks up where the last one stopped.

Everything lives in one SQLite file on your computer. Your memory is not sent anywhere unless you turn on an optional feature that does so (an off-site backup to your own private GitHub repo, remote access through your own Cloudflare Tunnel, or the optional relay). FlowState itself makes one network call: once a day it asks GitHub whether a newer release is out. It sends nothing about you or your projects, and flowstate update check off turns it off (see "Upgrading").

If FlowState saves you some re-explaining, a star on GitHub helps others find it.

Many AIs, one memory, at the same time

Claude, ChatGPT, Cursor and Grok can all use FlowState at once, on your computer, across your network, or from your phone (through the optional relay or your own tunnel). When one AI logs a decision or a change, the others see it the next time they check. Hard rules and handoff notes reach every AI, and every change records which AI made it, so you always know who did what. Work across projects is linked too, so a change to something shared shows up in every project that uses it.

Several agents at once

When two agents start on the same project at the same time, both can see the same "next" todo and quietly do the same work. So an agent claims a todo before it starts (manage_todos(action="claim", todo_id=4), 15 minutes by default, up to 120) and releases it, or hands it off with a note, when it stops. Other agents see the claim in their brief (#4 Fix login (claimed by cursor on mac-mini, expires in 9m)), next skips it and lists it at the end, and a second claim is refused with the holder's name. Nothing is hidden or locked: a claim simply runs out if the agent goes away, and it is released when that app's session ends (quit, ended or idle; the same app reconnecting may take its claim back). Anyone (you included) can still update or finish a claimed todo; they just get a warning, and manage_history(action="who") shows it.

A decision that reads like a current one (and doesn't say it replaces it) is still saved, but flagged as a *possible* conflict (D31 vs D12 in the brief) for the agent and then you to settle in the review queue; FlowState matches words (and meaning, if the local model is installed), it doesn't judge. While such a pair is open, the brief's "Recent decisions" keeps the newer one, tagged (unsettled: may conflict with #12), and leaves the older one's text out, so an AI skimming the list doesn't follow it as settled. In its place (or on the newer line, if the older one is too old for the list) is a short pointer, #12 in dispute with #31, text left out: search(query="D12"), which shows the full text in one step. Once you keep both, dismiss it, or one replaces the other, the brief looks as before. When two entries clearly disagree, FlowState also queues a disagreement card: claim A and claim B, who wrote each, and up to two short evidence snippets. You keep the older, the newer, or both, or dismiss the card. The one you don't keep is marked superseded, not deleted. An agent flags a pair with log_work (conflicts_with, topic, evidence) or manage_links(action="flag_conflict"). The review page shows the card (side by side on a wide screen), and the tool reply includes the same card as plain text plus the review link. Chat apps that support MCP Apps can show the card in the chat (apps on your card list: Claude Desktop to start with; claude.ai or another app that signs in through your tunnel or the relay once you add its sign-in's name with flowstate approvals cards add --sign-in); each button press carries a one-use code only the card gets, so the AI can't press them itself. Everything else that waits for your OK (session summaries, suggestions, imports, clean-up ideas) gets its own in-chat review card in those apps too (see "Where to see what's waiting for you").

Each window of an app gets its own session, and the brief opens with one line about what the others did meanwhile (Since your last visit (Oct 19): Claude Desktop and Grok saved 3 decisions, 5 changes, 2 todos.), and nothing when nothing changed.

When two decisions clash

FlowState doesn't decide which of two decisions is right. It notices when they might clash, shows it to every AI, and leaves the choice to you.

How a clash gets flagged:

• On its own. When an AI logs a decision that reads like a current one (similar words, or similar meaning if the optional local model is installed) and doesn't say it replaces it, the decision is still saved and the pair is flagged as a possible conflict, for example D31 vs D12. This is matching, not judgement, so some flags turn out to be harmless.
• By an AI on purpose. An AI that sees two entries disagree can flag them with a short topic and up to two evidence snippets (log_work with conflicts_with, or manage_links(action="flag_conflict")). That makes a disagreement card: claim A and claim B side by side, who wrote each, and the evidence.

Where it shows:

• The AI's reply. The log_work answer says "Possible conflict with D12 ...", so the AI you are working with can mention it right away. A flagged disagreement comes back with the card as plain text and the review link.
• The brief. Every AI that opens the project sees Possible conflicts: D31 vs D12. While a pair is open, the newer decision is tagged as unsettled and the older one's text is left out of "Recent decisions", so no AI follows either one as settled.
• The review queue. Each flag waits for you there: on the review page on your computer, in flowstate review in your terminal, and in an AI's manage_review list.
• Your phone. With the relay set up and phone links on, your phone review list shows it too.
• In-chat tap cards. In apps on your card list that draw MCP Apps cards (Claude Desktop to start with), the AI can show the card in the chat and you tap your choice.

Who settles it:

• You pick the winner. For a possible conflict you say whether the two really clash or fit together. For a disagreement card you keep the older one, the newer one, or both, or dismiss the card. The one you don't keep is marked superseded, not deleted.
• An AI can't pick it for you. The buttons on an in-chat card carry a one-use code that only the card gets, so the AI can't press them. An AI may pass your choice on only when you said it in that chat, quoting your words, and the app that made a card can't settle it by quoting the card's own text. Through the relay an AI can't settle anything in the chat unless you turn that on (flowstate relay chat-approvals on). The quoting rule is checked by wording, not by cryptography (see "Honest limits").
• What an AI can do: say that its own new decision replaces an older one (log_work(..., replaces=12) or a "supersedes" link). That closes the flag, and the brief and the edit history show it. If that is later undone or the link is removed, FlowState asks you whether to reopen the conflicts it had closed.

Who, which model, which machine

Every change FlowState saves (records, edits, review decisions, links, handoffs, hard rules, todo claims) keeps who made it. You see it in "Who did what" on the review page, on the disagreement card, and through manage_history(action="who").

• App: the name the app reports about itself, for example "Cursor". When the app signed in with a per-app key, a remote token or an approved sign-in through your tunnel or the relay, the sign-in's name is shown beside it if it differs: Grok Bot (via work-key). The app chooses the first name; it can't choose the second. A desktop app that starts FlowState itself, or one on the shared LAN token, has no sign-in of its own, so its name is only what it says.
• Model: the AI model, only when the app reports it (the model argument, the X-FlowState-Model header, or FLOWSTATE_MODEL for a desktop app). FlowState never guesses, so this is often blank.
• Machine: where the change came from. On your own computer that is FLOWSTATE_WORKSPACE or the computer's name (or what the app sends); a per-app key can carry its own workspace; over the network it reads like lan (signed in as ...), relay (signed in as ...) or tunnel (signed in as ...).
• How it was identified: per-app key, remote token, OAuth sign-in, shared token or self-reported, so you can tell which names the app chose itself.

This is there so you can find a change and undo it. Most of it is what the app says about itself; only the sign-in's name is something the app can't pick.

Worked on my PC with Grok Build, then asked Claude and Grok on my iPhone. Both knew what I did last. (Click for the full-quality video.)

Why I built it

I built FlowState v1 in January 2026 as a gift to the vibe coder community, back when context was a serious bottleneck and every new AI chat started from scratch. This week I updated it, because the bottleneck moved. Now most of us work across several AI platforms at once, and keeping context between them is the new problem. FlowState stays free and local.

*John Martin, DialectForge*

---

Quick start: point your AI at this repo

Paste this into an AI app that can run commands on your computer (Claude Code, Cursor, Windsurf, Codex CLI, Grok Build, ...):

Set up FlowState for me from https://github.com/dialectforge/FlowState by following its AGENTS.md.

The AI reads AGENTS.md, asks you which apps to connect and whether you want nightly backups and the FlowState skill, shows you a dry run, then runs setup_flowstate.py. When it's done, fully quit and reopen the apps it connected.

Claude Desktop's chat can't run commands by itself. Set it up from one of the apps above ("...and connect it to Claude Desktop"), or run the script yourself (below).

What setup_flowstate.py does

It uses the Python standard library only, and it's safe to run again (it reports unchanged for anything already set up). In order, it:

1. checks for Python 3.11 or newer;
2. creates .venv in the repo folder and runs pip install -e mcp-server into it (skip with --skip-install);
3. creates the database if there isn't one, or keeps your existing one and adds only the new FlowState tables and columns (numbered migrations, with an integrity-checked backup first when the database already has data);
4. adds a