FlowState
Local MCP server that gives AI apps shared project memory stored in SQLite.
Tested on macOS and Linux
Use it
macOS arm64
You need first
- Runtimes:
python>=3.11 - System packages:
git
git clone FlowState repo
git clone https://github.com/dialectforge/FlowState.git FlowState && ls FlowState/mcp-servercreate venv and pip install -e mcp-server
cd FlowState && /opt/homebrew/bin/python3 -m venv .venv && .venv/bin/python -m pip install -e mcp-server
Add it to your agent
claude mcp add flowstate -- env 'FLOWSTATE_DB=<FLOWSTATE_DB>' '<install-folder>/FlowState/.venv/bin/python' -m flowstateJSON for Claude Desktop, Cursor and other clients
{
"mcpServers": {
"flowstate": {
"command": "env",
"args": [
"FLOWSTATE_DB=<FLOWSTATE_DB>",
"<install-folder>/FlowState/.venv/bin/python",
"-m",
"flowstate"
]
}
}
}Replace <FLOWSTATE_DB> with your own path. Replace <install-folder> with the folder you ran the install steps in.
Add .venv/bin/python -m flowstate from the FlowState folder as an MCP server in your AI app, then call the start_here tool.
Linux x86_64
You need first
- Runtimes:
python>=3.11 - System packages:
git
Clone FlowState repo
git clone https://github.com/dialectforge/FlowState.git FlowStateCreate venv and pip install -e mcp-server
cd FlowState && python3 -m venv .venv && .venv/bin/python -m pip install -e mcp-server
Where the README and reality differ
- README: manage_todos action="create" in README example
What worked: Valid actions are add, list, next etc. - create returns validation error and list with wrong project name gives KeyError
Check that it works
FlowState/.venv/bin/python -m flowstate --help 2>&1The output should contain “usage: flowstate”.
Add it to your agent
claude mcp add flowstate -- '<install-folder>/FlowState/.venv/bin/python' -m flowstateJSON for Claude Desktop, Cursor and other clients
{
"mcpServers": {
"flowstate": {
"command": "<install-folder>/FlowState/.venv/bin/python",
"args": [
"-m",
"flowstate"
]
}
}
}Replace <install-folder> with the folder you ran the install steps in.
Add .venv/bin/python -m flowstate from the FlowState folder as an MCP server in your AI app, then call the start_here tool.
What it does
- Share project memory across AI appsTested
How to use it
- Create a project with the
manage_projectstool using actioncreateand a name. - Add a todo with the
manage_todostool using actionadd, the project name and a title. - Point other AI apps at the same server so they see the same project memory.
- Create a project with the
- Read a short project brief when you startTested
How to use it
- Call the
start_heretool with your project name to get a brief of the project.
- Call the
- Record decisions, changes, problems and todosTested
How to use it
- Call the
log_worktool with the project name, a kind such asdecision, and a summary.
- Call the
- Keep memory in a local SQLite fileNot tested
How far pickfit got
macOS arm64
- Installs
- Connects
- 3 of 4 features work
- Works offline
Linux x86_64
- Installs
- Connects
- 1 of 4 features work
- Works offline
Other systems
Windows: the project says it runs there; pickfit hasn’t tried it.
Good for
- recall what was being worked on in a project
- save a project decision
- list next todo in a project
- look up past decisions about a topic
- review items waiting for approval
How pickfit tested it
Each run starts from a clean machine and follows the steps above. How pickfit verifies
macOS arm64
An MCP client called one of its tools
- Replayed from scratch
- Works offline
- Checked on 1 Nov 2026
- Version 2.4.5
An MCP client handshake over stdio listed 12 tools, and a call to log_work returned a result.
Differences the test machine hit
- README: manage_projects with project param
In the test: create action requires name field, not project
Linux x86_64
An MCP client called one of its tools
- Replayed from scratch
- Works offline
- Checked on 1 Nov 2026
- Version 2.4.5
An MCP client handshake over stdio listed 12 tools, and a call to manage_projects returned a result.
Differences the test machine hit
- README: .venv/bin/python -m pip install -e mcp-server assumes .venv exists
In the test: Create venv first with python3 -m venv .venv - README: FLOWSTATE_WORKSPACE env var usage documented but default DB location not obvious
In the test: Default SQLite is at ~/.local/share/flowstate/flowstate.db not in workspace; workspace name must match exact project name for log_work/manage_todos