FlowState

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

License: MIT Python 3.10+ MCP Compatible Works with Cursor Works with Claude

---

😩 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.