FlowState MCP

🧠 FlowState MCP

Never lose your work context again. AI-powered session memory that picks up exactly where you left off.

    

---

😩 The Problem Every Developer Knows

You're in flow. Writing good code. Making decisions. Solving hard problems.

Then life happens.

You close your laptop for dinner. Sleep. A meeting pulls you away. You come back and...

"What was I doing? Why did I write it this way? Where was I supposed to go next?"

You spend 20–40 minutes just reconstructing context that was already in your head. That's not work — that's tax.

The average developer loses 30+ minutes of productivity every single day to context reconstruction.

FlowState eliminates that tax entirely.

---

✨ How It Works

As you work, you log context naturally through your AI assistant:

You: "Log that I decided to use Redis for session caching because Postgres was too slow under load"
You: "I'm blocked — the Redis connection times out in Docker but works locally"
You: "Checkpoint — I'm stopping for dinner, I was building the session middleware"

When you come back:

You: "Resume my work"

FlowState hands you a complete brain dump — exactly where you left off, every decision you made, every blocker you hit, every idea that occurred to you. You're back in flow state in 10 seconds.

---

🛠️ Tools

| Tool | What you say | What happens | |------|-------------|--------------| | checkpoint | "Checkpoint — stopping for the day" | Saves your full work context | | resume | "Resume my work" | Returns complete context brain dump | | log_decision | "Log that I chose Postgres over Mongo because..." | Decision captured with reasoning | | log_blocker | "Log blocker — Redis timeout in Docker" | Blocker tracked with workaround | | resolve_blocker | "Mark blocker abc123 as resolved" | Clears it from future resumes | | log_idea | "Log idea — add rate limiting to auth" | Idea saved, won't be forgotten | | daily_standup | "Generate my standup" | Auto-writes your standup from logs | | weekly_summary | "Give me a weekly summary" | Full week review in seconds | | search_context | "What did I decide about Redis?" | Searches all your saved context | | session_history | "Show my recent sessions" | Timeline of your work sessions |

---

🚀 Quick Start

Install

pip install flowstate-mcp

Add to your MCP client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "flowstate": {
      "command": "uvx",
      "args": ["flowstate-mcp"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "flowstate": {
      "command": "uvx",
      "args": ["flowstate-mcp"]
    }
  }
}

Restart your client. Start using it. That's it — no API keys, no account, no cloud.

---

💬 Real Example

Before leaving: `` You: Checkpoint — I'm stopping for the night. Project: payment-service Doing: implementing Stripe webhook handler Current task: handling the payment_intent.succeeded event Next steps: finish the idempotency check in webhook_handler.py line 84, then write tests for the refund flow Files: webhook_handler.py, tests/test_webhooks.py Branch: feature/stripe-webhooks ``

Next morning: ``` You: Resume payment-service

FlowState:

🧠 FlowState Resume — payment-service

_Checkpoint saved 9h ago_

🎯 What You Were Doing

Implementing Stripe webhook handler

🔨 Where You Left Off

Handling the payment_intent.succeeded event

📂 Files You Were Touching

• webhook_handler.py
• tests/test_webhooks.py

🌿 Branch

feature/stripe-webhooks

➡️ Your Next Steps

Finish the idempotency check in webhook_handler.py line 84, then write tests for the refund flow

⚖️ Decisions You Made

• Use Stripe idempotency keys — Why: prevents duplicate charges on retry

🚧 Blockers

• [🔴 Open] Webhook signature verification fails in test environment

Workaround: Temporarily disabled in test config

💡 Ideas

• 🔴 Add webhook event logging to DB for audit trail

--- You've got this. Pick up right where you left off. 🚀 ```

---

📋 Daily Standup — Auto-Generated

You: Generate my standup for today

## 📋 Daily Standup — February 23, 2025

### ✅ Yesterday
- [payment-service] Implementing Stripe webhook handler
- [auth-api] Refactored JWT middleware

### 🔨 Today
- Finish idempotency check, write refund flow tests

### 🚧 Blockers
- [payment-service] Webhook signature fails in test env
  → Workaround: disabled in test config

### ⚖️ Key Decisions
- Use Stripe idempotency keys (prevents duplicate charges on retry)

Copy. Paste. Done. Your standup writes itself.

---

🗂️ Where Data Lives

All context is stored 100% locally in ~/.flowstate/. No cloud. No account. No telemetry. Your work context stays on your machine.

~/.flowstate/
├── sessions.json    # Work checkpoints
├── decisions.json   # Technical decisions + reasoning
├── blockers.json    # Issues and blockers
└── ideas.json       # Captured ideas

---

🌍 Works With Any MCP Client

• ✅ Claude Desktop
• ✅ Cursor
• ✅ Windsurf
• ✅ Cline (VS Code)
• ✅ Continue.dev
• ✅ Zed
• ✅ Any MCP-compatible tool

---

🗺️ Roadmap

• [ ] Git integration — auto-detect branch and changed files
• [ ] Team mode — share context across teammates (opt-in)
• [ ] VS Code extension with status bar widget
• [ ] Pomodoro integration — auto-checkpoint on timer
• [ ] Export to Notion / Obsidian
• [ ] Context handoff between AI sessions (beat the context window)

---

🛠️ Development

git clone https://github.com/attaelahi/flowstate-mcp
cd flowstate-mcp
uv venv && source .venv/bin/activate
uv pip install -e .

# Test
python tests/test_server.py

# Run with MCP Inspector
npx @modelcontextprotocol/inspector python -m flowstate_mcp.server

---

🤝 Contributing

PRs and ideas welcome. If FlowState saves you time, a ⭐ star helps others find it.

---

📄 License

MIT © Atta Elahi

---

💭 The Philosophy

Flow state is the most valuable thing a developer has. Context loss is its biggest enemy. FlowState doesn't change how you work — it just remembers everything so you don't have to.