Skip to main content
Glama

🧠 FlowState MCP

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.


Related MCP server: myBrAIn

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

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that provides persistent, cross-session memory and team knowledge sharing for AI development workflows. It enables project DNA scanning, semantic search, context budgeting, and git-aware indexing to prevent AI context loss between sessions.
    11 npm
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    MCP server that provides persistent memory and contextual awareness to language models, enabling project onboarding, recall of architectural rules, and code consistency across sessions.
    32
    MIT