io.github.dialectforgePublished by GitHub account dialectforgev1.0.1Updated Nov 7, 2026
Hosted shared memory for AI apps: project decisions, to-dos and learnings. Beta.
Hosted shared project memory for AI apps: stores decisions, changes, problems, learnings and todos, and returns a project brief at the start of each…
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/io.github.dialectforge%2Fflowstate-hosted/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"mcpServers": {
"flowstate-hosted": {
"type": "http",
"url": "https://hosted.flowstatemcp.com/mcp"
}
}
}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.
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.
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.
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:
D31 vs D12. This is matching, not judgement, so some flags turn out to be harmless.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:
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.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.flowstate review in your terminal, and in an AI's manage_review list.Who settles it:
flowstate relay chat-approvals on). The quoting rule is checked
by wording, not by cryptography (see "Honest limits").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.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").
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 argument, the
X-FlowState-Model header, or FLOWSTATE_MODEL for a desktop app). FlowState never
guesses, so this is often blank.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 ...).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.)
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
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).
setup_flowstate.py doesIt uses the Python standard library only, and it's safe to run again (it reports unchanged
for anything already set up). In order, it:
.venv in the repo folder and runs pip install -e mcp-server into it (skip with --skip-install);flowstate entry to each chosen app's MCP config, after saving a copy of that file
as <file>.flowstate-backup-<time>. Other servers and settings are left alone; a file it
can't parse is refused and left untouched;--offsite-github OWNER/NAME, checks that the GitHub repo is private and saves it for
nightly off-site backups (--no-offsite skips the question);--schedule-backups, adds a nightly local backup to your OS scheduler (Windows Task
Scheduler, macOS launchd, Linux systemd user timer or cron), at 02:30 unless you pass --backup-time HH:MM;--install-skill, installs the FlowState skill (see below; --no-skill skips the question);flowstate review-page, this computer only). It never replaces a file of that name it didn't make;--verify, starts the server the way your app will and calls start_here to check it answers.At the end it tells you about the daily update check and how to turn it off.
Useful flags: --dry-run (show what would change, change nothing), --help,
--clients auto|all|none|<list> (claude-desktop, cursor, windsurf, claude-code,
codex, grok; auto = every app whose config folder exists), --config <file> (any other
JSON config with an mcpServers object), --db <file>, --python <path>.
Needs Python 3.11+ and git.
FlowState is not published on PyPI: install it from this repository as shown here. The
flowstate package on PyPI is an unrelated project, so pip install flowstate does not
install this.
setup_flowstate.py installs into .venv itself, so the pip install lines are only needed
if you want the test tools or manage the venv yourself (then add --skip-install). For the exact,
hash-checked test set CI uses: pip install --require-hashes -r requirements-dev.lock, then
pip install --no-deps -e mcp-server. A plain,
non-editable pip install mcp-server (or of a built wheel) works too from 2.4.1 on; in 2.4.0 it
left out the database schema, so every FlowState call failed, and the failed start left an empty
database file behind. 2.4.1 sets up such an empty file as a new database, so reinstalling is
enough. flowstate update needs the git clone set up by setup_flowstate.py. Config
snippets for every app, if you'd rather edit configs by hand, are in AGENTS.md.
Short public pages on flowstatemcp.com. The tools are free, need no sign-up, and run in the browser. Nothing you type there is sent to a server.
Tools
Guides
Comparisons
You don't need commands. Talk to your AI app in plain words, and it uses FlowState for you:
The full list, with what each request does, is in docs/WHAT-TO-ASK.md.
skills/flowstate is an Agent Skill: a short set of habits (read
the brief first, log to the right project, link shared components, never approve your own review
items, leave a handoff if you stop mid-task). Apps that load skills follow it without being told.
python setup_flowstate.py --install-skill (or answer "yes" when it asks)
copies the folder to ~/.agents/skills/flowstate and ~/.claude/skills/flowstate. An older,
different copy is moved to ~/.agents/flowstate-skill-backups/ or
~/.claude/flowstate-skill-backups/ first.skills/flowstate folder into ~/.agents/skills/ or ~/.claude/skills/.skills/flowstate folder yourself and upload the ZIP in
the app's Skills settings. (FlowState doesn't build the ZIP for you.)No skill support in your app? Paste this once per chat, or into its custom instructions:
Use FlowState as my project memory. First call start_here for the project we're working on (ask me which if unsure). As we work, log decisions, changes, problems, lessons and todos to that project with log_work. If something is shared between projects, link it with manage_links instead of copying it. Never approve or reject review items, and never change my review mode, unless I ask you to in this chat. At the end, log a short summary of what we did and what's next.
The server also sends these rules to every app when it connects, and offers them as the MCP
prompt flowstate-start.
Memory your AI actually reads
start_here brief: one call gives the AI the project's hard rules, handoff notes, open
todos, problems, recent changes, decisions and key lessons. Sizes: quick (about 1,500
characters), standard (4,000, the default) or deep (up to 12,000).log_work: one simple tool to record a decision, change, problem, learning or todo.
Every write must name a project, so nothing lands in the wrong place.receipt: {change: "3f9a1d2c4b5e", saved: ["decision #31"]}). A write that timed out but saved a moment later is reported on the
next answer, and the same write repeated within 2 minutes returns the first receipt instead
of saving a copy.[auto-captured, needs review]. A small housekeeping session (only reads, undo,
review decisions, a handoff pickup or todo claims) isn't queued for review. FlowState keeps a lean record of each session's
reads and writes (record ids and hashes, never the text).You stay in charge
flowstate approve <id> in your terminal. The app that queued an item needs your own words
to decide it. An AI that reaches FlowState through the relay can't approve or reject anything
in the chat: it tells you to decide it yourself instead (see "Chat approvals through the
relay" below).off, auto_only (default), chosen record types, or
everything. Set it for the whole install or per project. The AI may change it only when you
ask in the chat, and every change is logged with your words. With approvals on, turning review
off also waits for your own click or key.flowstate approve <id>);
flowstate rules add / flowstate rules remove <id> in your terminal do it at once.flowstate approvals on; off by default, also after an
upgrade): then an AI's delete, and turning review off, wait for you, and no app can pass your
OK along. You decide in the app's own popup (Claude Code, Cursor, VS Code, when they connect
directly and not through the relay or the internet), on your phone (only if you use the
optional FlowStateMCP hosted relay: you sign in at flowstatemcp.com, your phone talks to your
own FlowState, and the site never sees the item), or with flowstate approve <id> in your
terminal. Every decision is logged with how it was made. With approvals off, an AI can delete
without asking you; the safety copy and undo are what protect you then.flowstate relay chat-approvals on|off; off by default). An AI connected through the
optional relay (claude.ai, ChatGPT and other cloud AIs) can't approve or reject review items
in the chat, even when you tell it to there: its answer says nothing was decided and tells
you to decide it yourself on your phone, from the review link you saved (or on the computer
where FlowState runs). It doesn't give the phone link itself: that contains your relay
handle, and cloud chats are stored by the AI company. Turn it on in a terminal on that
computer (it asks you to type y) and those AIs can approve and reject again when they quote your words, as before. Either way,
the items that are yours alone stay yours alone: deletes and turning review off while
approvals are on, and "did you say this yourself?" checks. Apps that connect directly (on
this computer or your own network) are not affected. There is no tool for this setting, so
an AI can't switch it on through FlowState.user_stated,
ai_inferred, from_code), and FlowState stores who set that tag and when (the app, the
model if the app gave it, or "user" when you confirmed it). Facts like paths, ports and config
not checked for 60 days are listed for re-checking.user_stated when it quotes you, and the brief then says (user, via <app>): that is the
app's claim. Once you confirm it yourself it says (user, confirmed by the user), and
search and manage_history show who set the tag and when. Changing an
existing record to user_stated is yours alone, approvals on or off: the app's request
leaves the tag as it is and queues one review item, which you confirm on the review page, on
your phone or with flowstate approve <id>; no popup, review walk box or in-chat card offers
it. No app can confirm it for you. A user_stated write that repeats another app's ai_inferred record
is saved as ai_inferred. What this doesn't cover: FlowState can't check that an app
quoting you at log time is telling the truth; the tag then names that app.Accountability
manage_history(action="who").flowstate keys add --name "<app>" gives
each app its own key (optionally read-only). FlowState records the name the app sends and the
key's name beside it, which the app can't change ("Grok Bot (via my-laptop-key)" when they
differ, one name when they match). The key is shown once and only a hash is kept; a revoked key is
refused (401) at once. Keys aren't accepted on the public listener, and can't use manage_data_git or
attach files. The old shared LAN token still works; its changes are marked "shared token (legacy)".Projects that share things
Tasks
todo(action="next") lists open, unblocked work,
highest priority first.Finding things
search(query=..., answer=true) takes a question in plain words; FlowState
answers by quoting your own records, with their ids, and says so when it has nothing on it. It doesn't make anything up.Move learning "..." from A to B? It mentions B.). It only suggests a move when the record names the other project or one
of its parts, never a guess it isn't sure of. Unsure move ideas left over from older versions
are withdrawn (no record moves). Nothing moves until you approve.Your controls (command line and browser)
flowstate review-page (one-time link). The page an AI's link opens can pause
an app but never resume one (flowstate apps resume, or the page flowstate review-page
opens).flowstate apps list /
apps activity) and pause one app's writes (apps pause --app NAME). A paused app can still read.export-md writes a readable copy of a project; import-md
brings your edits back through the review queue.import-memory, or the import_memory tool).Safety and backups
secret_detected) and not saved. flowstate scan-secrets lists
older records that look suspicious, without showing values.~/.config/flowstate/http-token file with mode 0600.--force (and then the
current file is backed up first).data-git migrate, FlowState takes a verified copy that is kept at least 7 days whatever
the limits above say; if it can't, the change isn't made. This doesn't depend on nightly
backups, and FlowState never adds a daily copy you didn't ask for.gh or git login. It never stores a GitHub token.Connecting
flowstate keys add).flowstate remote clients lists them, flowstate remote rename OLD NEW renames one without
making a new token). See
docs/REMOTE-ACCESS.md.--tools core (or
FLOWSTATE_TOOLS=core) lists only the 6 everyday ones to save context; --tools full adds the
6 specialist ones. The default tools answer in every profile; the specialist ones only in full
(called by name elsewhere, they are refused: not_in_profile). Every tool is
labelled read-only or read-write (per action in its _meta).setup_flowstate.py.<venv python> -m flowstate) or HTTP with a bearer token.Many AI memory tools now put their best features behind subscriptions: Zep ($125/mo and up), Supermemory ($19/mo and up). Mem0 no longer sells Starter, Growth or Pro to new accounts (people already on those plans keep their old prices; see the pricing FAQ). New accounts get Free, or Custom, which is sales-led and has no published price. On Free, Mem0 pays the model calls for the first 30 days (10,000 adds and 1,000 retrievals a month). After that you connect your own LLM key (you can connect one during the first 30 days too) for 50,000 adds and 10,000 retrievals a month at no charge from Mem0. Past those limits you can turn on usage-based billing, with a monthly cap you set. Some have dropped their free or self-hosted options entirely, like Zep's self-hosted edition and Pieces' free tier. FlowState is MIT-licensed and runs on your own machine. Local FlowState is free and MIT forever. An optional paid hosted version and relay are at flowstatemcp.com; paid plans charge for hosting, never for features.
Prices as listed on each vendor's pricing page, November 2026.
FlowState is open source and built to be worked on by AI: AGENTS.md and llms.txt explain the repo, the code is split into small modules, and there's a test suite that runs against temporary databases. If you think of a feature, have your AI build it. You're not waiting on a vendor's roadmap.
The v1.1 desktop GUI was an unfinished experiment and has been removed. v2 is used through your AI and the browser review page.
Some things wait for your OK: session summaries FlowState wrote on its own, records an AI suggested, clean-up ideas, "did you say this yourself?" checks, and (with approvals on) an AI's deletes. You don't need a terminal to see and decide them. Nothing pops up unless you ask, or you have turned approvals on.
In the chat (everyone). Ask your AI "show me what's waiting for me". It calls
manage_review(action="walk"). In Claude Code, Cursor and VS Code (the apps FlowState knows
show a real dialog, the same list as the approvals popup), each item comes up one at a time
as a box: tick Approve and submit to approve, submit it unticked to reject (the optional
note is the reason), decline to skip it, close the box to stop. FlowState acts only on your
answer in that box; your AI can't answer for you. This works with approvals off too, because
you asked. In other apps, and in any app that reaches FlowState through the relay or over
the internet, there are no boxes: the AI gets a plain list (20 at a time, oldest first, and
how to ask for the next 20) with the links below to show you, and FlowState says plainly
that nothing was decided. If an app "answers" a box faster than a person could (under a
second), FlowState takes it that you never saw the box: it stops, decides nothing and shows
the plain list instead.
Review cards (chat apps that support MCP Apps, such as Claude Desktop). There the AI
can also show what's waiting as cards in the chat (show_review_card, up to 5 at a time,
oldest first). Each card says what the item is, what saving it would do, which app wrote it
and when, with Approve and Reject (Reject asks for an optional short reason in the
card itself; a session summary says Keep all / Don't keep, and each of its records
has its own Keep / Remove, see below). Your tap is saved and logged
as a card decision; the AI can't tap for you, and the card's button tool is hidden from it.
Disagreements keep their own card (Keep A / Keep B / Keep both). Items only you decide
(with approvals on: an AI's deletes and turning review off; and every "did you say this?"
check) show on a card without buttons, with your phone or review-page link. Through the
relay (the FlowStateMCP connector in Claude Desktop or claude.ai) the cards work once you
allow them: the first time the connector could show you a card, FlowState asks you once on
your review page and your phone review page, "Allow tap cards in ?"; tap Allow there
(only you can; no AI can answer it). Or add the connector's sign-in yourself:
flowstate approvals cards add --sign-in "<its name>", or the review page's Settings. Your
taps then count as on your computer; the AI's own approve / reject in the chat still
follows the chat-approvals setting (off by default). In apps without MCP Apps nothing
changes: the AI shows the plain list.
Session summaries: Keep all, or Keep / Remove one record. A session summary lists the
records the session saved. They were saved when the AI wrote them, so each one has its own
Keep (marks it reviewed) and Remove (takes it back) on the review page, the tunnel
page, your phone and the review card. Remove takes a safety copy first and goes into the edit
history: Bring back restores it while the summary waits, and
manage_history(action="undo", ...) does at any time. A record that is gone, or was changed
after the session, shows that and has no buttons; one the session only updated can only be
kept. Keep all keeps the summary (you can edit its line first) and every record you
haven't removed; Don't keep decides only the summary and removes nothing. The summary
waits for one of those two even when every record is decided. In a terminal:
flowstate review records <id> and flowstate review record <id> change:12 keep|remove|restore.
Your AI sees each record's state but can't decide records.
A link to the review page on the computer where FlowState runs (apps on that computer).
When something waits, and your AI app runs on the same computer as FlowState, the brief
your AI reads, and the walk's answer, include a link like http://127.0.0.1:8770/. Click it
and the review page opens; no command needed. FlowState starts the page itself the first
time a link is needed, one per computer (another FlowState on the same computer reuses it),
on 127.0.0.1 only; if 8770 is taken it picks a free port. FLOWSTATE_REVIEW_PORT sets the
port (0 any free one, off no page or link). flowstate review-page still works as before,
and so does the "FlowState review" shortcut setup_flowstate.py puts on your desktop (it runs
that command; if FlowState already has the page open, it opens that one).
127.0.0.1 always means "this computer", so on any other computer that link would open
that computer itself, not yours. FlowState therefore gives it only to apps it can see are on
its own computer: apps it starts directly, and apps on its local network connection that
connect from the same computer. Apps on another computer (your Mac through the relay, or
another computer on your network) never get it. They get a plain note instead: open the
review list on your phone from the link you saved (3), if you have the relay; ask your AI
to show what's waiting (it shows the list in the chat); or open the review page on the computer where FlowState runs (the
FlowState review shortcut, or flowstate review-page), or the tunnel review page (4) if you
have your own tunnel. FlowState decides this from the connection itself, never from anything
the app says about itself.
On your phone (relay users). If the relay agent is set up, the brief and the walk's
answer in apps on the computer where FlowState runs also have your own phone link,
https://flowstatemcp.com/review/<handle> (your handle is your computer's relay name; your
flowstatemcp.com account page shows the same link). It never changes, so you can bookmark
it or add it to your home screen. Apps elsewhere (through the relay, your own tunnel, or
another computer on your network) don't get it, nor a single item's phone link, because it
contains your handle and their chats are stored outside your computer: they tell you to open
the review list on your phone from the link you saved, or to run flowstate review-page on
your computer. When you tap it:
https://<handle>.fsmcp.com/review)
with a 5-minute signed pass. Your FlowState checks it with the site's public key (pinned
in this release), uses up the one-time code, and shows the waiting list with Approve /
Reject on each item (a 15-minute session; the oldest 50 at a time). The site never sees
what's in it.flowstate approvals phone off turns every phone link off.
Through your own tunnel (no relay). If you run the public listener behind your own
tunnel (docs/REMOTE-ACCESS.md), open https://<your tunnel>/review/tunnel in any browser and
sign in with the owner passphrase. It is the same review page as on your computer, sized for
a phone, and decides everything that page can, the user-only items too. Your AI apps' tokens
don't open it; only the passphrase does.
Who gets which: an app on the computer where FlowState runs gets 1 and 2 (and 3 with the
relay); an app on another computer gets 1, and 3 with the relay. Every decision made in
the chat walk, on the phone list or on the tunnel page is logged with how it was made (chat,
phone or tunnel page); see manage_history(action="list").
The phone list (3), on an iPhone:
Honest limits:
http://127.0.0.1:<port>/ too, just as
it could run flowstate approve.flowstate approvals phone off turns the phone list off.The review page on your computer (flowstate review-page, the desktop shortcut, or the link in
the brief) has a Project history link at the top, next to "Who did what". Pick a project and
you see its whole path in time order, newest first:
Each entry says when it happened, which app did it, the model (only when the app said), the machine, and how the app signed in. Filter by type, by app or machine, or by dates, search the text, and switch to oldest first. Long histories come 50 entries a page. The page works on a phone screen.
Tap a record to see its fields now and its whole edit history, with every changed field before and after, plus everything else that names it. The Todos tab lists the project's todos with who created each one and its status now (open, done, cancelled, deleted; an erased todo is left out, since nothing about it is left to show). Tap one for its full timeline: who created it, claimed it, let a claim run out, edited it, completed it, reopened it or deleted it.
Some things to know:
flowstate erase shows as [erased]
wherever an entry still names it. Its text is not on the page, in search results or on its
record page.FLOWSTATE_ACTIVITY_DAYS). When the page reaches further back, it says so:
older entries may not say which app or session made them, and records from before version
2.4.0 never did ("not recorded"). The edit history itself is kept until you erase it.Run flowstate review-page: its Settings section (this computer only) lists every setting
in plain words with its value, and changes it there. Review mode, app pauses, approvals on / off
(whole install or per project), the popup apps, phone links, chat approvals through the relay,
whether flowstate update may update this computer, and the daily update check. Turning
approvals off or relay chat approvals on asks you to confirm on a second page. Settings that
come from the app's config (environment variables) are shown read-only; keys, tokens and
passphrases are never shown and keep their own commands. The page an AI's link opens shows the
settings read-only (anything on this computer can open that link); the tunnel page and the
phone pages have no settings at all, and no AI tool can read or change them. The terminal
commands below still work exactly as before.
Run with the venv Python: <venv python> -m flowstate <command> (or flowstate <command> with
the venv active). Add -h to any command for its options.
12 tools by default, plus 4 card tools for apps that draw cards (see the end of the table).
Every name starts with a verb; tools that do several things are manage_<things> and take an
action. The first three are the ones every agent needs.
With FLOWSTATE_TOOLS=full six specialist tools are listed too: manage_sessions (sessions
also run automatically), manage_files (file attachments), manage_data_git (git for the
FlowState data folder, not your repo), manage_variables (non-secret project settings),
manage_methods (documented procedures) and manage_skills (the AI's learned skills and
saved state). Outside the full profile they are refused, even when an app calls them by name
(also by their older names, git, file, variable, ...).
Older tool names still work. The 35 names of v2.0 (todo, link, handoff,
review_approve, list_projects, log_learning, ...) are not listed any more but
answer exactly as before, with one extra line naming the new tool. The full mapping is in
docs/TOOL_CONSOLIDATION.md.
Over HTTP, only the owner's LAN token may use manage_data_git (or git) or attach files
from your computer, or ask for or approve a delete; per-app keys, per-app tokens and OAuth
apps are refused.
Want claude.ai, ChatGPT, Cursor or your phone to reach the FlowState on your own computer?
The optional relay gives it an address like https://<handle>.fsmcp.com/mcp. Traffic is
encrypted end to end (TLS passthrough), so the relay can't read it, and your data stays on
your machine. Get a code at flowstatemcp.com/account, then
run flowstate relay enroll --code <code>. The relay is in a 10-spot beta. Step-by-step guide:
flowstatemcp.com/setup.
Local FlowState stays free and MIT-licensed. It needs no account. Local FlowState makes one
network call: once a day it asks GitHub whether there is a newer release. It sends nothing about
you or your projects (only what any web request reveals: your IP address). Turn it off with
flowstate update check off (or FLOWSTATE_UPDATE_CHECK=0); off means no request at all. The
relay is off by default. Nothing in it runs until you enroll.
If you want claude.ai, ChatGPT or Cursor to reach the FlowState on your computer, and you don't
want to set up your own domain and Cloudflare Tunnel (docs/REMOTE-ACCESS.md),
the relay agent connects out to tunnel.fsmcp.com, an optional hosted service by
DialectForge on its own domain, fsmcp.com. Your apps then use https://<handle>.fsmcp.com/mcp.
The relay can't read your traffic. The TLS key for your address is made on your computer and never leaves it. Your computer gets its own Let's Encrypt certificate (the relay only publishes the DNS check value), and it ends every encrypted connection itself. The relay just passes the encrypted bytes through. Sign-in is the same OAuth + passphrase consent page as above, served by your FlowState. A daily Certificate Transparency check warns you loudly if anyone else ever gets a certificate for your address.
During the beta the relay has room for 10 computers, one per account. If it is full,
relay enroll says so in plain words with your place in line ("The FlowState Relay beta is
full right now. You're on the waitlist (number N). ...") and saves nothing. Places are first come, first served: when there is room, it is held for the
oldest code in line for 48 hours. Your code stays valid for 7 days after that, so just run
the same command again.
The relay uses the Python package cryptography, which comes with mcp today. The wire
protocol is in docs/relay-protocol.md.
sentence-transformers into the venv, put a model (default
all-MiniLM-L6-v2) on disk, set FLOWSTATE_MEANING_MODEL, and run flowstate meaning index.
Without it, search (also with answer=true) matches words only, so a reworded question can miss.model argument,
the X-FlowState-Model header, or FLOWSTATE_MODEL for a desktop app). FlowState never
guesses one; if the app says nothing, the model is left empty.FLOWSTATE_WORKSPACE or this computer's name, or what the app
sends. "Who did what" says so in its identity column ("self-reported", "shared token (legacy)").flowstate relay chat-approvals on. Hard rules are
yours alone whatever words an AI passes: adding or removing one waits for your own click or
key. They are shown first in every brief; FlowState can't stop an AI from doing something
outside FlowState.y in your terminal" stops AI tools, not an AI with its own shell. flowstate approve, rules add / remove, erase, data-git and the off-site recovery code need a
real terminal, so an AI can't pass them through FlowState's tools or by piping input. An AI
that can run programs on your computer could still fake a terminal, or read and change the
database file and the credential store directly; FlowState can't stop that.fsa-1, fsa-2). The site vouches for who signed in but never sees
the items. If the site's signing key ever leaked, someone could open your waiting list (with
its Approve and Reject buttons) on a reachable computer; approving a single item from its own
link would still need that item's one-use code from your computer. flowstate approvals phone off turns the phone links off.flowstate update check off or FLOWSTATE_UPDATE_CHECK=0 stops it. Nothing updates on its own: flowstate update
runs only when you start it (or your AI does, after you asked).flowstate update is careful, so it often says no. It needs a plain clone with no local
changes and a real .venv, and ssh-keygen to check the release signature. On Windows a
release that changes the Python packages is refused; update that one by hand.log_work details over 10,000 characters get a clear
too_long answer and nothing is saved.search with answer=true): it quotes the best-matching sentences of your records; it doesn't write new answers.cloudflared
2026.10.2 or later on your computer (older versions still trust compromised eMudhra
certificates: https://blog.cloudflare.com/emudhra-certificate-compromise), and an owner passphrase. The helper launch scripts in scripts/windows/ are
Windows-only. FlowState supports OAuth dynamic client registration but not client ID metadata
documents (CIMD) yet.password=. It also refuses
secret values in variable. Older records are not re-scanned automatically; run flowstate scan-secrets.flowstate offsite key): without it, a new computer can't read the
copy. GitHub may keep an older night's commit reachable for a while after the force-push, and
copies pushed by FlowState before 2.4.4 were not encrypted (delete that repository's old
history, or the repository, if that matters to you). The staging folder is deleted after each push.--host set to a LAN address, the
token and every record cross your network readable by anyone on it; FlowState says so when it
starts. Use it only on a network you trust, with per-app LAN keys. Remote-access tokens (made
for the relay or tunnel) are refused there from other computers unless you run flowstate remote lan-tokens on. A request that came through a proxy on this computer counts as from
another computer (FlowState sees the proxy's forwarding headers; for a proxy that adds none,
set FLOWSTATE_LAN_PROXY=1). Clearing the warning about a token that crossed the network
(flowstate remote keep-token) asks for your y in your own terminal.records_are, and live-image / HTML / javascript: forms are
broken (![ becomes ! [), so a record can't make a chat app load an address. An AI can
still be fooled by text it reads; hard rules are set and removed only by you, and each says who set it.flowstate data-git sync commits a markdown export
and your attachments; git keeps every version of them in that repository for good. If your
data-git repository was made by FlowState 2.4.3 or older, it still holds your database:
update FlowState on every computer that syncs it first, then run flowstate data-git migrate once on each. It makes a safety copy, takes the database and settings out of git
without touching them on disk, and pushes the change. Until then sync refuses that
repository, because a computer still on 2.4.3 would delete its own database when it pulls
the change. Older commits still hold those files. The migrate commit also adds FlowState's
.gitignore, so a computer that hasn't updated yet can't commit its database again.sync shares the markdown export of each computer's projects and the
attachments. Records saved on one computer don't reach another computer's database, and an
export file from another computer isn't for import-md here (its record numbers are the
other database's). When two computers
wrote the same export file (a project both have), this computer's copy wins at its sync: the
file is made again from this computer's database each time, so after a sync export/ shows
this computer's records. Exports of projects this computer doesn't have are left alone.main, whatever git's
own default is. A computer whose repository is on master while the remote uses main (or
the other way round) moves to the remote's branch at its next sync and says so. If the
remote has both, with changes this computer hasn't got, sync changes nothing and tells you
which computer to sync first.flowstate tighten does it at once). On a drive that doesn't support
permissions (USB, exFAT, some network shares) FlowState still works and says once that the
files there may be readable by other users of this computer.projects/<name>.flowstate/attachments/). To remove something for good, see below.flowstate erase TYPE:ID (or --deleted-before DAYS), in your own terminal, removes records
you have already deleted for good: their copies in the edit history (so undo stops working for
them), every earlier version edits overwrote (a renamed record's first title too), the keyword
and meaning search indexes, notes that name them, their decision evidence, a todo's claim
history and the topic of a disagreement card about them, the text of review items they came
from, every quote of them in review items about them (another item only loses a whole sentence
quoted from them, 5 words and 30 characters or more, never a short shared phrase), matching events in the automatic session log, and attached files
FlowState copied in. Other review items keep their edit history: only the erased text is
blanked inside it. Records an AI took back with undo count as deleted, and so does a record
deleted along with its project or component (the project's own delete can still be undone).
A hard rule you removed can be erased too (flowstate erase rule:ID): it stays listed as
removed, without its text. Then it compacts the database (SQLite's secure_delete and
VACUUM), so the old bytes leave the file too. No safety copy is taken.
What it can't reach: older backups made before the erase still hold the text until they age out (14 days for daily copies, 8 weeks for weekly ones, safety copies at least 7 days; delete them by hand from the backups folder if you need it gone sooner); the off-site copy until the next nightly push replaces it (GitHub may keep the old commit for a while); data-git history, if you pushed an export; and anything an AI app copied out into its own chat history.
remote-auth.db). Losing it only
means approving your apps again.The database is created at FLOWSTATE_DB if set, else Windows
%LOCALAPPDATA%\flowstate\flowstate.db, macOS ~/Library/Application Support/flowstate/flowstate.db,
Linux ~/.local/share/flowstate/flowstate.db. More settings are listed in AGENTS.md.
FlowState (2.4.0 and later) checks once a day whether a newer release is out and, if so, puts
one line on top of the brief; your AI tells you once. Nothing updates on its own.
flowstate update check shows the last result, flowstate update check now checks at once, and
flowstate update check off (or the setting FLOWSTATE_UPDATE_CHECK=0) turns the check off
completely: no request, no line. flowstate update check on turns it back on.
FlowState is not on PyPI. Never use pip install --upgrade flowstate: that name is an unrelated
project. Update with flowstate update or by hand, as shown here.
From 2.4.0 on: flowstate update. Ask your AI to "update FlowState" (it needs an app that can
run terminal commands on the computer where FlowState runs; there is no tool for this). It runs
<venv python> -m flowstate update --dry-run in a terminal on this computer and shows you the
plan. Then quit your AI apps and run <venv python> -m flowstate update in your own terminal: it
asks you to type y. An app that isn't running this FlowState itself can do that step for you
with --yes --user-said "<your words>"; one that is doesn't. To reach 2.4.4 there are limits, see
"Updating to 2.4.4" below. It:
github.com/dialectforge/FlowState with no local changes, at a release tag or on main
with no commits of your own, with one worktree and a real .venv folder;mcp-server/flowstate/release_signers). An unsigned
tag, an unknown key, a missing ssh-keygen, git older than 2.34 or any check error: nothing
is changed;pre-update, kept at least 7 days);.venv with the release's own packages only when the release changes them, and
then every app must be quit first; on Windows such a release is refused up front, because the
command runs from that .venv: update it by hand), migrates the database, starts the services
again and checks them;.venv, the old services. Your database is never put back or overwritten
(migrations only add tables and columns, so the old version reads it as it is).Then quit and reopen your AI apps; until you do, an app still running the old version says so
in its brief. flowstate update --rollback goes back to the version before the last update. If you set a
remote-access passphrase, going back to a version before 2.4.4 means setting it again
(flowstate remote passphrase): 2.4.4 stores it in a stronger form older versions can't check
(the rollback reminds you).
A developer setup (your own branch or commits, extra worktrees, a linked .venv) is refused:
update it by hand. To turn flowstate update off on a computer, run
flowstate update self-update off (it puts "self_update": false in FlowState's config.json;
on turns it back on, and with no word it shows the value), use the review page's Settings, or
put a .flowstate-no-self-update file in the folder (that file wins until you delete it).
Updating to 2.4.4. 2.4.4 changes FlowState's Python packages (it needs mcp>=1.30,<2, for
two security fixes), which limits how you can get there:
flowstate update works and makes a new .venv itself
(the old one is kept as .venv.pre-update). Every program using this folder's .venv must be
quit first, and that includes the AI app you are asking if its FlowState runs from this folder,
as it does in the usual setup. Such an app can run --dry-run and show you the plan, but
the real update stops at the new .venv and puts the old version back. So read the plan, quit
your AI apps, and run <venv python> -m flowstate update in your own terminal. An AI app that
doesn't use this folder's .venv can run it for you. These versions install from their own
package list, which allows an older mcp. A new .venv normally gets the newest 1.x anyway;
if it gets one older than 1.30, 2.4.4 refuses to migrate and the update puts the old version
back. Then update by hand, below.flowstate update refuses 2.4.4, dry run included, and changes
nothing: the command runs from the .venv it would have to replace. Update by hand, below.flowstate update yet. Update by hand, below.Once you are happy with the new version, you can delete the .venv.pre-update folder;
--rollback then can't put the old packages back.
By hand (and to install 2.4.0 or later the first time). Quit your AI apps. If FlowState's HTTP server or relay runs as a service or scheduled task, stop it first and start it again afterwards: the setup script doesn't do that for you. Then, in the FlowState folder:
Use your normal Python (python3 on macOS and Linux, py -3 if that is your command on Windows),
and add the other options you used when you set it up. The script keeps your .venv, updates the
packages in it to what the release needs, and migrates your database. Then reopen your AI apps. These
steps work from main or from a release tag, and they are how to install the newest release
(2.4.8) if you don't have 2.4.0 yet. Git stops at the checkout if you have local changes. For a
later release, use its tag.
Pull the new code and run setup_flowstate.py again (or just restart your app). Your existing
database is kept. Before new migrations run on a database with data, FlowState takes an
integrity-checked backup, then it adds new tables, and (migration 012, "who did what") new empty
columns on FlowState's own v2 tables only. v1.1's tables and all existing data are never
changed, so a v1.1 server can still open the same file. You can also run
<venv python> -m flowstate migrate --dry-run first to see what would be applied. See
CHANGELOG.md for what's new.
MIT. See LICENSE.
Source: README.md at commit d7d4394
Project brief (start here)
CALL THIS FIRST in every conversation about a project. Returns the brief as text: hard rules, a handoff note if any, review mode, possible conflicts, open todos (and claims) and problems, recent changes, decisions and learnings. No project: lists projects. Side effects: opens or reuses the automatic session, notes when you looked.
sizefolderprojectLog work
Record one new decision (a choice and why), change (code or setup), problem (bug or blocker), learning (reusable lesson) or todo in a project. To update todos or problems: manage_todos / manage_problems. Only adds. Review mode or suggested=true may queue it for the user. A change on a shared component alerts linked projects. A decision close to a current one gets a possible-conflict note; act on it. conflicts_with opens a disagreement card. Secrets are refused. Returns {logged, record, note} or {queued_for_review}.
kindrequiredmodeltopicsourcedetailsprojectrequiredsummaryrequiredcategoryevidencepriorityreplacescomponent+3 moreSearch and ask
Find stored todos, decisions, changes, learnings, problems and solutions. query: ranked matches. query + answer=true: a short quoted answer with record ids, or says FlowState has nothing. query="D12": decision 12 in full. No query: the newest records. Read-only. Overview: start_here. Returns {results, count} or {answer, sources}.
modelimitqueryanswerprojectsince_hourscontent_typesinclude_set_asideTodos
Todos. list; next: top unblocked (others' claims last). update: status (done/cancelled), priority, title, description. block / unblock: waits on todos or a problem. add: subtask, blocker or due date only (else log_work). claim before you start (fails if someone has it); renew; release or handoff (with a note). Returns rows.
sortlimitmodeltitleactionrequiredstatuscompactminutesprojectrequiredtodo_iddue_datepriority+8 moreProblems and attempts
Work on a project's existing problems (bugs, blockers). list: open problems. tree: one problem with every attempt and its solution. add_attempt: record a try. end_attempt: how a try ended. solve: close it with what fixed it (manage_history undo reopens it). Open a new problem with log_work kind=problem. Reads: list, tree. Writes need project. Returns problem rows, the tree, or the saved attempt or solution.
modelnotesactionrequiredcompactoutcomeprojectsummaryattempt_idconfidenceproblem_iddescriptionkey_insight+4 moreReview queue (user decides)
The user's review queue and mode: summaries, suggestions, imports, clean-ups, deletes, conflicts. list (a line each; item_id: one in full), get_mode: read-only. walk: when the user asks what's waiting (boxes or links). approve: make it a record (edit / move_to first), delete (confirm_name), confirm a conflict (keep=a|b|both). set_mode: which new records wait. approve, reject, set_mode: ONLY call this when the user has explicitly told you, in this chat; quote them in user_request; never approve your own suggestions or change the mode to get your own writes saved. Hosted: approve/reject are refused for every AI; share the review page link. Returns {items, total}, the mode, or the result.
keepmodeafterclearkindslimitmodelactionrequiredreasonstatusdetailsitem_id+8 moreHandoff notes
Notes from one AI to the next. leave: when you must stop mid-task, save where_i_was and next_step; the next start_here shows it after the hard rules. pickup: once you continue from a note, mark it so it stops showing. list: open notes. Not a session summary and not a todo. Adds or marks notes; never deletes. Returns the note or {notes}.
limitmodelactionrequiredprojectrequirednext_stephandoff_idwhere_i_wasinclude_picked_upHard rules
A project's hard rules: short never/always rules from the user, shown first in every brief and never cut. add: when the user states one (one sentence, max 300 chars; 25 rules, 2,000 chars in total); it waits in the review queue until the user approves it themselves (on their review page; no app can). list: active rules. remove: ONLY when the user asks in this chat; quote them in user_request; it waits like add; the rule is kept as removed. Preferences and lessons go in log_work. Requires project. Returns the rule or {rules}.
rulemodelactionrequiredprojectrequiredrule_iduser_requestinclude_removedCross-project links
Connect things across projects. add: a project uses a shared component (link_type=uses, target_project, target_component), depends on a project, two components are the same, records relate, or a record gets a URL (e.g. an issue). Then a change or decision logged on the shared component (log_work component=<name>) gives each linked project an update todo and a 'changed since' line; FlowState never edits other projects. remove: by link_id or the add fields; kept as removed (manage_history undo, record_type=link). flag_conflict: two records disagree (topic, evidence); the user keeps one. list: read-only. Requires project. Returns the link, the card, or {links}.
urlnotemodeltopicactionrequireditem_idlink_idprojectrequiredevidencecomponentitem_typelink_type+6 moreEdit history, undo, who did what
The edit trail of records. list: edits with old and new values. undo: take back a record's last edit, a record you created (if nothing refers to it), or a delete with everything removed with it (a deleted project: its old name and id); rows changed since are skipped and listed. who: who did what (app, model, machine), filtered and paged. metrics: usage counts only (brief sizes, how often search and ask returned records). Logged changes (kind=change): find them with search. Reads: list, who, metrics. list and undo require project. Returns {history}, the undo result, or {rows, page}.
pagelimitmodelsinceuntilactionrequiredby_appprojectby_modelrecord_idby_machinerecord_typeProjects and components
Projects and their components (named parts of a project). list: projects (by status). create: only when the user asks; names are unique. update: rename, describe, or set status (archived retires it). list_components / add_component / update_component: the same for components (deprecated retires one). delete / delete_component: only when the user asks. Deletes it with its child records after a safety copy; the answer gives the undo call. If the user turned approvals on it waits for their own approve instead (manage_review lists it; tell them the answer's next line). Reads: list, list_components. Returns project or component rows, or what was deleted.
namemodelactionrequiredstatusprojectdescriptioncomponent_idparent_component_idMemory upkeep (clean-up, import, fact checks)
Memory upkeep. cleanup: queue likely duplicate, stale and misfiled records. import: a memory export or edited FlowState markdown into review. stale: facts unchecked for 60+ days, and records flagged possibly stale. files_changed: paths you changed; flags records whose file evidence names them. mark_checked: you re-checked one (clears the flag). set_source: correct an origin (user_stated waits for the user). set_aside: no longer applies but kept (needs reason; out of brief and search; restore_set_aside or undo). delete: only when the user asks; undo restores it; with approvals on it waits for the user's approve (manage_review). Requires project. Returns counts and ids.
dayskindtextkindslimitmodelpathsactionrequiredformatoriginreasonsource+3 moreSessions
Inspect FlowState's sessions. They open and close by themselves (closed after 2 hours idle or when the app quits, with a summary queued for review), so this is rarely needed. current, list, conversations: read. start: returns the automatic session. end: close one with a summary (not undoable). Decisions go in log_work. Returns session or conversation rows.
limitmodelactionrequiredprojectsummaryoutcomessession_idfocus_problem_idfocus_component_idProject settings
Non-secret project settings: hosts, ports, endpoints, config. create, list (read), update (undo with manage_history), delete (undo restores it; with approvals on it waits for the user; refused for HTTP app keys and remote apps). Secrets are refused; is_secret only labels a value and does not hide it, so never store passwords, tokens or keys. Requires project. Returns variable rows.
namemodelvalueactionrequiredprojectrequiredcategoryis_secretdescriptionvariable_idProject procedures
Documented reusable procedures of a project (deploy, test, a code convention), with ordered steps. create, list (read), update (steps replaces the whole list; undo with manage_history), delete (undo restores it; with approvals on it waits for the user; refused for HTTP app keys and remote apps). A one-off choice is log_work kind=decision; a lesson is kind=learning. Requires project. Returns method rows.
namemodelstepsactionrequiredprojectrequiredcategorymethod_iddescriptioncode_examplerelated_component_idApp skills and checkpoints
The connected app's own learned skills, checkpoints and metrics: how the AI works, not project facts (those go in log_work). learn: save a skill. list: a project's and global skills. confirm: one more session where it held (promoted after 3 at a 0.8 rate). save_state / get_state: a checkpoint. log_metric / list_metrics: scores. Reads: list, get_state, list_metrics; the rest only add rows or counts. Returns rows.
modelskillactionrequiredcontextoutcomeprojectskill_idkey_factstool_nameskill_typemetric_typeaction_taken+6 more100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
git clone https://github.com/dialectforge/FlowState.git FlowStatecd FlowStatepython -m venv .venv# Windows: .venv\Scripts\python macOS/Linux: .venv/bin/python.venv/bin/python -m pip install -e mcp-server # just the server.venv/bin/python -m pip install -e "mcp-server[dev]" # plus test tools (pytest)python setup_flowstate.py --clients claude-desktop --schedule-backups --no-offsite --install-skill --dry-runpython setup_flowstate.py --clients claude-desktop --schedule-backups --no-offsite --install-skill --verify.venv/bin/python -m pytest tests -q # run the tests<venv python> -m flowstate remote passphrase # once, if not set yet<venv python> -m flowstate relay enroll --code <one-time code><venv python> -m flowstate relay run # keep it running<venv python> -m flowstate relay status # handle, URL, certificate, tunnel, CT check<venv python> -m flowstate relay disable # stop (keeps keys); `enable` to turn back on<venv python> -m flowstate relay forget # delete the device token, keys and certificate<venv python> -m flowstate relay chat-approvals # may relay AIs approve in the chat? (off: phone only)FlowState/├── setup_flowstate.py # one-command setup (venv, database, app configs, backups, skill)├── AGENTS.md # instructions for AI agents (install + working on the code)├── llms.txt # map of the repo for AI tools├── CHANGELOG.md├── mcp-server/ # the MCP server (Python package "flowstate")│ ├── pyproject.toml│ └── flowstate/│ ├── server.py # tools, stdio and HTTP transports│ ├── tooldefs.py # tool definitions; agent_guide.py: the wording sent to apps│ ├── brief.py, autosession.py, guard.py, review.py, review_mode.py, links.py, ...│ ├── backup.py, offsite.py, scheduler.py, secrets_scan.py, secret_store.py, remote_auth.py│ ├── app_keys.py, identity.py, who.py # per-app keys, who/model/machine, "Who did what"│ ├── approvals.py # opt-in approvals (off by default)│ ├── updates.py, selfupdate.py # daily update check, `flowstate update`│ ├── cli.py, cli_more.py # `flowstate <command>`│ ├── migrations/ # numbered, additive database migrations│ ├── schema.sql # the base schema the code reads (same as database/schema.sql)│ └── tools/ # older tool implementations├── database/schema.sql # base SQLite schema (kept the same as mcp-server/flowstate/schema.sql)├── skills/flowstate/ # the Agent Skill├── scripts/ # helpers: HTTP check, Cloudflare Tunnel template, Windows launchers├── docs/ # WHAT-TO-ASK.md (plain-word requests), REMOTE-ACCESS.md and notes└── tests/ # pytest suite (temporary folders only; guard_site/ refuses real data)git fetch --tagsgit checkout v2.4.8python setup_flowstate.py --clients <your apps> --verify