# 🌊 FlowMCP (formerly FlowMCP)

**Cross-model AI memory persistence.** *Your AI remembers everything, everywhere.*

FlowMCP is an MCP (Model Context Protocol) server that gives every AI tool you use — Claude, ChatGPT, Cursor, and more — access to the same persistent memory. Explain your project once, and every AI model knows the context.

---

## 🛠️ Choose Your setup

### 🔌 Option 1: Open-Source / Local Mode (Zero Limits)
Perfect for local development. Everything runs on your computer with offline access and **no usage capping**.

#### 1. Start Postgres & FlowMCP
```bash
docker compose up -d
```
*This handles database tables seeding automatically.*

#### 2. Install & Build
```bash
npm install
npm run build
```

#### 3. Setup Environment
```bash
cp .env.example .env
```
The defaults support local Docker correctly. No changes required.

---

### ☁️ Option 2: Hosted Node Mode (Supabase + Stripe)
For scaling to multiple users, team group spaces, and payment unlocks.

1. Create a **Supabase** project and run `sql/supabase-full-migration.sql` inside your SQL Query Editor.
2. Update your `.env` with:
   ```bash
   DATABASE_URL="your-supabase-connection-string"
   TRANSPORT=http
   PORT=3001
   ```
3. (Optional) Add `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` for upgrades handles.

---

## 🔌 Connecting to AI Tools

### 🦊 Claude Desktop
Edit `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "flowmcp": {
      "command": "node",
      "args": ["/absolute/path/to/flowmcp-mcp-server/dist/index.js"]
    }
  }
}
```

### 💻 Cursor
Create `.cursor/mcp.json` (or add via Cursor Settings Settings → Features → MCP):
* **Name:** `FlowMCP`
* **Type:** `command`
* **Command:** `node /absolute/path/to/flowmcp-mcp-server/dist/index.js`

---

## 🧭 Main Commands

| Command | Mode | Target Audience |
| :--- | :--- | :--- |
| `npm start` | **Stdio Mode** | Standard offline triggers (Claude / Cursor) |
| `TRANSPORT=http npm start` | **HTTP Mode** | Remote Web App triggers (ChatGPT integrations) |
| `npm run dev` | **Watch Mode** | Live rebuilding updates |

---

## 🗃️ Architecture

```text
AI Tool Interface (Claude / ChatGPT / Cursor)
       │
       │ MCP Protocol (stdio / HTTP)
       ▼
┌──────────────────────────┐
│       FlowMCP Server     │
│  • memory_store          │
│  • memory_recall         │
│  • Auto-assign scopes    │
└──────────┬───────────────┘
           │
           ▼
┌──────────────────────────┐
│      PostgreSQL DB       │
│  • Full-text Search      │
│  • Relevance Scoring     │
└──────────────────────────┘
```

## 🤝 Collaborative Seating
FlowMCP supports **Group Spaces**. 
* **Personal Space**: Automatically triggers on setup for solo memories.
* **Group Spaces**: Allows shared triggers if deployed in Hosted mode with the Next.js Dashboard companion connected.

---
*Created with 🌊 Flow Labs frameworks.*