diff --git a/docs/public/cursor/gemini-setup.mdx b/docs/public/cursor/gemini-setup.mdx
new file mode 100644
index 00000000..5f756c00
--- /dev/null
+++ b/docs/public/cursor/gemini-setup.mdx
@@ -0,0 +1,191 @@
+---
+title: "Cursor + Gemini Setup"
+description: "Use Claude-Mem in Cursor with Google's free Gemini API"
+---
+
+# Cursor + Gemini Setup
+
+This guide walks you through setting up Claude-Mem in Cursor using Google's Gemini API. Gemini offers a generous free tier that handles typical individual usage.
+
+<Info>
+**Free Tier:** 1,500 requests per day with `gemini-2.5-flash-lite`. No credit card required.
+</Info>
+
+## Step 1: Get a Gemini API Key
+
+1. Go to [Google AI Studio](https://aistudio.google.com/apikey)
+2. Sign in with your Google account
+3. Accept the Terms of Service
+4. Click **Create API key**
+5. Choose or create a Google Cloud project
+6. Copy your API key - you'll need it in Step 3
+
+<Tip>
+**Higher rate limits:** Enable billing on your Google Cloud project to unlock 4,000 RPM (vs 10 RPM without billing). You won't be charged unless you exceed the free quota.
+</Tip>
+
+## Step 2: Clone and Build Claude-Mem
+
+```bash
+# Clone the repository
+git clone https://github.com/thedotmack/claude-mem.git
+cd claude-mem
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+```
+
+## Step 3: Configure Gemini Provider
+
+### Option A: Interactive Setup (Recommended)
+
+Run the setup wizard which guides you through everything:
+
+```bash
+npm run cursor:setup
+```
+
+The wizard will:
+1. Detect you don't have Claude Code
+2. Ask you to choose Gemini as your provider
+3. Prompt for your API key
+4. Install hooks automatically
+5. Start the worker
+
+### Option B: Manual Configuration
+
+Create the settings file manually:
+
+```bash
+# Create settings directory
+mkdir -p ~/.claude-mem
+
+# Create settings file with Gemini configuration
+cat > ~/.claude-mem/settings.json << 'EOF'
+{
+  "CLAUDE_MEM_PROVIDER": "gemini",
+  "CLAUDE_MEM_GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
+}
+EOF
+```
+
+Replace `YOUR_GEMINI_API_KEY` with your actual API key.
+
+Then install hooks and start the worker:
+
+```bash
+npm run cursor:install
+npm run worker:start
+```
+
+## Step 4: Restart Cursor
+
+Close and reopen Cursor IDE for the hooks to take effect.
+
+## Step 5: Verify Installation
+
+```bash
+# Check worker is running
+npm run worker:status
+
+# Check hooks are installed
+npm run cursor:status
+```
+
+Open http://localhost:37777 to see the memory viewer.
+
+## Available Gemini Models
+
+| Model | Free Tier RPM | Notes |
+|-------|---------------|-------|
+| `gemini-2.5-flash-lite` | 10 (4,000 with billing) | **Default.** Fastest, highest free tier RPM |
+| `gemini-2.5-flash` | 5 (1,000 with billing) | Higher capability |
+| `gemini-3-flash` | 5 (1,000 with billing) | Latest model |
+
+To change the model, update your settings:
+
+```json
+{
+  "CLAUDE_MEM_PROVIDER": "gemini",
+  "CLAUDE_MEM_GEMINI_API_KEY": "your-key",
+  "CLAUDE_MEM_GEMINI_MODEL": "gemini-2.5-flash"
+}
+```
+
+## Rate Limiting
+
+Claude-mem automatically handles rate limiting for free tier usage:
+
+- Requests are spaced to stay within limits
+- Processing may be slightly slower but stays within quota
+- No errors or lost observations
+
+**To remove rate limiting:** Enable billing on your Google Cloud project, then add to settings:
+
+```json
+{
+  "CLAUDE_MEM_GEMINI_BILLING_ENABLED": true
+}
+```
+
+You'll still use the free quota but with much higher rate limits.
+
+## Troubleshooting
+
+### "Gemini API key not configured"
+
+Ensure your settings file exists and has the correct format:
+
+```bash
+cat ~/.claude-mem/settings.json
+```
+
+Should output something like:
+```json
+{
+  "CLAUDE_MEM_PROVIDER": "gemini",
+  "CLAUDE_MEM_GEMINI_API_KEY": "AIza..."
+}
+```
+
+### Rate limit errors (HTTP 429)
+
+You're exceeding the free tier limits. Options:
+1. Wait a few minutes for the rate limit to reset
+2. Enable billing on Google Cloud to unlock higher limits
+3. Switch to OpenRouter for higher volume needs
+
+### API key invalid
+
+1. Verify your key at [Google AI Studio](https://aistudio.google.com/apikey)
+2. Ensure there are no extra spaces or newlines in your settings.json
+3. Try generating a new API key
+
+### Worker not processing observations
+
+Check the worker logs:
+
+```bash
+npm run worker:logs
+```
+
+Look for error messages related to Gemini API calls.
+
+## Switching Providers Later
+
+You can switch between Gemini, OpenRouter, and Claude SDK at any time by updating your settings. No restart required - changes take effect on the next observation.
+
+```json
+{
+  "CLAUDE_MEM_PROVIDER": "openrouter"
+}
+```
+
+## Next Steps
+
+- [Cursor Integration Overview](index) - All Cursor features
+- [OpenRouter Setup](openrouter-setup) - Alternative provider with 100+ models
+- [Configuration Reference](../configuration) - All settings options
diff --git a/docs/public/cursor/index.mdx b/docs/public/cursor/index.mdx
new file mode 100644
index 00000000..95d9cb60
--- /dev/null
+++ b/docs/public/cursor/index.mdx
@@ -0,0 +1,163 @@
+---
+title: "Cursor Integration"
+description: "Use Claude-Mem's persistent memory in Cursor IDE - with free provider options"
+---
+
+# Cursor Integration
+
+Claude-mem brings persistent AI memory to Cursor IDE. Your coding sessions remember context across restarts, helping the AI understand your codebase deeply over time.
+
+<Info>
+**No Claude Code subscription required.** Use Gemini (free tier) or OpenRouter as your AI provider.
+</Info>
+
+## How It Works
+
+Claude-mem integrates with Cursor through native hooks:
+
+1. **Session hooks** capture tool usage, file edits, and shell commands
+2. **AI extraction** compresses observations into semantic summaries
+3. **Context injection** loads relevant history into each new session
+4. **Memory viewer** at http://localhost:37777 shows your knowledge base
+
+## Installation Paths
+
+Choose the installation method that fits your setup:
+
+### Path A: Cursor-Only Users (No Claude Code)
+
+If you're using Cursor without a Claude Code subscription:
+
+```bash
+# Clone and build
+git clone https://github.com/thedotmack/claude-mem.git
+cd claude-mem && npm install && npm run build
+
+# Run interactive setup wizard
+npm run cursor:setup
+```
+
+The setup wizard will:
+- Detect you don't have Claude Code
+- Help you choose and configure a free AI provider (Gemini recommended)
+- Install hooks automatically
+- Start the worker service
+
+**Detailed guides:**
+- [Gemini Setup](gemini-setup) - Recommended free option (1500 req/day)
+- [OpenRouter Setup](openrouter-setup) - 100+ models including free options
+
+### Path B: Claude Code Users
+
+If you have Claude Code installed:
+
+```bash
+# Install the plugin (if not already)
+/plugin marketplace add thedotmack/claude-mem
+/plugin install claude-mem
+
+# Install Cursor hooks
+claude-mem cursor install
+```
+
+The plugin uses Claude's SDK by default but you can switch to Gemini or OpenRouter anytime.
+
+## Prerequisites
+
+<AccordionGroup>
+  <Accordion title="macOS">
+    - Node.js 18+
+    - Cursor IDE
+    - jq and curl: `brew install jq curl`
+  </Accordion>
+  <Accordion title="Linux">
+    - Node.js 18+
+    - Cursor IDE
+    - jq and curl: `apt install jq curl` or `dnf install jq curl`
+  </Accordion>
+  <Accordion title="Windows">
+    - Node.js 18+
+    - Cursor IDE
+    - PowerShell 5.1+ (included in Windows 10/11)
+    - Git for Windows
+  </Accordion>
+</AccordionGroup>
+
+## Quick Commands Reference
+
+After installation, these commands are available from the claude-mem directory:
+
+| Command | Description |
+|---------|-------------|
+| `npm run cursor:setup` | Interactive setup wizard |
+| `npm run cursor:install` | Install Cursor hooks |
+| `npm run cursor:uninstall` | Remove Cursor hooks |
+| `npm run cursor:status` | Check hook installation status |
+| `npm run worker:start` | Start the worker service |
+| `npm run worker:stop` | Stop the worker service |
+| `npm run worker:status` | Check worker status |
+
+## Verifying Installation
+
+After setup, verify everything is working:
+
+1. **Check worker status:**
+   ```bash
+   npm run worker:status
+   ```
+
+2. **Check hook installation:**
+   ```bash
+   npm run cursor:status
+   ```
+
+3. **Open the memory viewer:**
+   Open http://localhost:37777 in your browser
+
+4. **Restart Cursor** and start a coding session - you should see context being captured
+
+## Provider Comparison
+
+| Provider | Cost | Rate Limit | Best For |
+|----------|------|------------|----------|
+| Gemini | Free tier | 1500 req/day | Individual use, getting started |
+| OpenRouter | Pay-per-use + free models | Varies by model | Model variety, high volume |
+| Claude SDK | Included with Claude Code | Unlimited | Claude Code subscribers |
+
+<Tip>
+**Recommendation:** Start with Gemini's free tier. It handles typical individual usage well. Switch to OpenRouter or Claude SDK if you need higher limits.
+</Tip>
+
+## Troubleshooting
+
+### Worker not starting
+
+```bash
+# Check if port is in use
+lsof -i :37777
+
+# Force restart
+npm run worker:stop && npm run worker:start
+
+# Check logs
+npm run worker:logs
+```
+
+### Hooks not firing
+
+1. Restart Cursor IDE after installation
+2. Check hooks are installed: `npm run cursor:status`
+3. Verify hooks.json exists in `.cursor/` directory
+
+### No context appearing
+
+1. Ensure worker is running: `npm run worker:status`
+2. Check that you have observations: visit http://localhost:37777
+3. Verify your API key is configured correctly
+
+## Next Steps
+
+- [Gemini Setup Guide](gemini-setup) - Detailed free tier setup
+- [OpenRouter Setup Guide](openrouter-setup) - Configure OpenRouter
+- [Configuration Reference](../configuration) - All settings options
+- [Troubleshooting](../troubleshooting) - Common issues and solutions
diff --git a/docs/public/cursor/openrouter-setup.mdx b/docs/public/cursor/openrouter-setup.mdx
new file mode 100644
index 00000000..a7141d1a
--- /dev/null
+++ b/docs/public/cursor/openrouter-setup.mdx
@@ -0,0 +1,191 @@
+---
+title: "Cursor + OpenRouter Setup"
+description: "Use Claude-Mem in Cursor with OpenRouter's 100+ AI models"
+---
+
+# Cursor + OpenRouter Setup
+
+This guide walks you through setting up Claude-Mem in Cursor using OpenRouter. OpenRouter provides access to 100+ AI models from various providers, including several free options.
+
+<Info>
+**Model variety:** Access Claude, GPT-4, Gemini, Llama, Mistral, and many more through a single API key.
+</Info>
+
+## Step 1: Get an OpenRouter API Key
+
+1. Go to [OpenRouter](https://openrouter.ai)
+2. Sign up or sign in
+3. Navigate to [API Keys](https://openrouter.ai/keys)
+4. Click **Create Key**
+5. Copy your API key - you'll need it in Step 3
+
+<Tip>
+**Free models available:** OpenRouter offers free versions of several models including Gemini Flash and others. Check the [model list](https://openrouter.ai/models?show_free=true) for current free options.
+</Tip>
+
+## Step 2: Clone and Build Claude-Mem
+
+```bash
+# Clone the repository
+git clone https://github.com/thedotmack/claude-mem.git
+cd claude-mem
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+```
+
+## Step 3: Configure OpenRouter Provider
+
+### Option A: Interactive Setup (Recommended)
+
+Run the setup wizard which guides you through everything:
+
+```bash
+npm run cursor:setup
+```
+
+When prompted for provider, select **OpenRouter**.
+
+### Option B: Manual Configuration
+
+Create the settings file manually:
+
+```bash
+# Create settings directory
+mkdir -p ~/.claude-mem
+
+# Create settings file with OpenRouter configuration
+cat > ~/.claude-mem/settings.json << 'EOF'
+{
+  "CLAUDE_MEM_PROVIDER": "openrouter",
+  "CLAUDE_MEM_OPENROUTER_API_KEY": "YOUR_OPENROUTER_API_KEY"
+}
+EOF
+```
+
+Replace `YOUR_OPENROUTER_API_KEY` with your actual API key.
+
+Then install hooks and start the worker:
+
+```bash
+npm run cursor:install
+npm run worker:start
+```
+
+## Step 4: Restart Cursor
+
+Close and reopen Cursor IDE for the hooks to take effect.
+
+## Step 5: Verify Installation
+
+```bash
+# Check worker is running
+npm run worker:status
+
+# Check hooks are installed
+npm run cursor:status
+```
+
+Open http://localhost:37777 to see the memory viewer.
+
+## Recommended Models
+
+### Free Models
+
+| Model | Provider | Notes |
+|-------|----------|-------|
+| `google/gemini-2.0-flash-exp:free` | Google | Fast, capable |
+| `xiaomi/mimo-v2-flash:free` | Xiaomi | Good general purpose |
+
+### Paid Models (Low Cost)
+
+| Model | Approx. Cost | Notes |
+|-------|--------------|-------|
+| `anthropic/claude-3-haiku` | ~$0.25/1M tokens | Fast, efficient |
+| `google/gemini-flash-1.5` | ~$0.075/1M tokens | Great value |
+| `mistralai/mistral-7b-instruct` | ~$0.07/1M tokens | Budget option |
+
+To specify a model, add to your settings:
+
+```json
+{
+  "CLAUDE_MEM_PROVIDER": "openrouter",
+  "CLAUDE_MEM_OPENROUTER_API_KEY": "your-key",
+  "CLAUDE_MEM_OPENROUTER_MODEL": "google/gemini-2.0-flash-exp:free"
+}
+```
+
+## Cost Management
+
+OpenRouter charges per token. To manage costs:
+
+1. **Use free models:** Several high-quality free models are available
+2. **Monitor usage:** Check your [OpenRouter dashboard](https://openrouter.ai/activity)
+3. **Set spending limits:** Configure limits in OpenRouter settings
+
+<Warning>
+**Cost awareness:** Unlike Gemini's free tier, OpenRouter paid models charge per request. Monitor your usage if using paid models.
+</Warning>
+
+## Troubleshooting
+
+### "OpenRouter API key not configured"
+
+Ensure your settings file exists with the correct format:
+
+```bash
+cat ~/.claude-mem/settings.json
+```
+
+Should output something like:
+```json
+{
+  "CLAUDE_MEM_PROVIDER": "openrouter",
+  "CLAUDE_MEM_OPENROUTER_API_KEY": "sk-or-..."
+}
+```
+
+### Model not found
+
+1. Check the model ID is correct at [OpenRouter Models](https://openrouter.ai/models)
+2. Some models may require payment - check if you have credits
+3. Free models have `:free` suffix in their ID
+
+### Rate limits
+
+OpenRouter rate limits vary by model and your account tier. If you hit limits:
+1. Wait briefly and retry
+2. Consider upgrading your OpenRouter account tier
+3. Switch to a less popular model
+
+### API errors
+
+Check the worker logs for details:
+
+```bash
+npm run worker:logs
+```
+
+Common issues:
+- Invalid API key (regenerate at OpenRouter)
+- Insufficient credits for paid models
+- Model temporarily unavailable
+
+## Switching Providers Later
+
+You can switch between OpenRouter, Gemini, and Claude SDK at any time by updating your settings. No restart required - changes take effect on the next observation.
+
+```json
+{
+  "CLAUDE_MEM_PROVIDER": "gemini"
+}
+```
+
+## Next Steps
+
+- [Cursor Integration Overview](index) - All Cursor features
+- [Gemini Setup](gemini-setup) - Alternative free provider
+- [Configuration Reference](../configuration) - All settings options
diff --git a/docs/public/docs.json b/docs/public/docs.json
index 7f2b2771..6d52a84f 100644
--- a/docs/public/docs.json
+++ b/docs/public/docs.json
@@ -47,6 +47,15 @@
           "endless-mode"
         ]
       },
+      {
+        "group": "Cursor Integration",
+        "icon": "wand-magic-sparkles",
+        "pages": [
+          "cursor/index",
+          "cursor/gemini-setup",
+          "cursor/openrouter-setup"
+        ]
+      },
       {
         "group": "Best Practices",
         "icon": "lightbulb",