# 🧠 FlowState MCP

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org)
[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)
[![Works with Cursor](https://img.shields.io/badge/works%20with-Cursor-black)](https://cursor.com)
[![Works with Claude](https://img.shields.io/badge/works%20with-Claude-orange)](https://claude.ai)

---

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

```bash
pip install flowstate-mcp
```

### Add to your MCP client

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

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

**Cursor** (`.cursor/mcp.json`):

```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

```bash
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](https://github.com/attaelahi)

---

## 💭 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.