feat(windsurf): add Windsurf (Codeium) integration via MCP

.github/workflows/test.yml

@@ -59,6 +59,7 @@ jobs:
       integrations-lockfiles: ${{ steps.filter.outputs.integrations-lockfiles }}
       integrations-openai-agents: ${{ steps.filter.outputs.integrations-openai-agents }}
       integrations-openhands: ${{ steps.filter.outputs.integrations-openhands }}
+      integrations-windsurf: ${{ steps.filter.outputs.integrations-windsurf }}
       integrations-pipecat: ${{ steps.filter.outputs.integrations-pipecat }}
       integrations-agentcore: ${{ steps.filter.outputs.integrations-agentcore }}
       integrations-smolagents: ${{ steps.filter.outputs.integrations-smolagents }}
@@ -189,6 +190,8 @@ jobs:
             - 'hindsight-integrations/openai-agents/**'
           integrations-openhands:
             - 'hindsight-integrations/openhands/**'
+          integrations-windsurf:
+            - 'hindsight-integrations/windsurf/**'
           integrations-pipecat:
             - 'hindsight-integrations/pipecat/**'
           integrations-agentcore:
@@ -3787,6 +3790,45 @@ jobs:
       # (requires_real_llm) needs a live Hindsight server and runs separately.
       run: uv run pytest tests -v -m "not requires_real_llm"
 
+  test-windsurf-integration:
+    needs: [detect-changes]
+    if: >-
+      (github.event_name == 'workflow_dispatch' ||
+      needs.detect-changes.outputs.integrations-windsurf == 'true' ||
+      needs.detect-changes.outputs.ci == 'true')
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        ref: ${{ github.event.pull_request.head.sha || '' }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+      with:
+        enable-cache: true
+        prune-cache: false
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version-file: ".python-version"
+
+    - name: Build windsurf integration
+      working-directory: ./hindsight-integrations/windsurf
+      run: uv build
+
+    - name: Install dependencies
+      working-directory: ./hindsight-integrations/windsurf
+      run: uv sync --frozen
+
+    - name: Run tests
+      working-directory: ./hindsight-integrations/windsurf
+      # PR CI runs only the deterministic bucket; the real-LLM E2E bucket
+      # (requires_real_llm) needs a live Hindsight server and runs separately.
+      run: uv run pytest tests -v -m "not requires_real_llm"
+
   test-claude-agent-sdk-integration:
     needs: [detect-changes]
     if: >-
@@ -4837,6 +4879,7 @@ jobs:
       - test-llamaindex-integration
       - test-openai-agents-integration
       - test-openhands-integration
+      - test-windsurf-integration
       - test-agentcore-integration
       - test-haystack-integration
       - test-pip-slim

hindsight-dev/hindsight_dev/generate_changelog.py

@@ -80,6 +80,7 @@ class IntegrationMeta:
     "continue": IntegrationMeta("hindsight-continue", "Continue"),
     "zed": IntegrationMeta("hindsight-zed", "Zed"),
     "openhands": IntegrationMeta("hindsight-openhands", "OpenHands"),
+    "windsurf": IntegrationMeta("hindsight-windsurf", "Windsurf"),
 }
 
 VALID_INTEGRATIONS = list(INTEGRATIONS.keys())

hindsight-docs/docs-integrations/windsurf.md

@@ -0,0 +1,42 @@
+---
+sidebar_position: 7
+title: "Windsurf Persistent Memory with Hindsight | Integration"
+description: "Add long-term memory to Windsurf (Codeium) with Hindsight via MCP. One command wires the Hindsight MCP server into mcp_config.json plus an always-on recall/retain rule, so memory works automatically in Cascade."
+---
+
+# Windsurf
+
+Long-term memory for [Windsurf](https://windsurf.com) (Codeium), powered by [Hindsight](https://vectorize.io/hindsight). One command connects Cascade to the Hindsight MCP server and adds a rule telling the agent to use it — so it recalls relevant memory at the start of a task and retains durable facts as it goes. Recall happens at query time against your actual message, and from your seat it's automatic.
+
+## How It Works
+
+Windsurf supports two things this integration uses:
+
+- **MCP servers:** Windsurf runs MCP servers configured under `mcpServers` in `~/.codeium/windsurf/mcp_config.json` and surfaces their tools in Cascade. Remote servers connect via a `serverUrl` field with optional headers, so the Hindsight MCP endpoint connects directly — no bridge needed — giving the agent `recall` / `retain` / `reflect` tools.
+- **Workspace rules** in `.windsurf/rules/`. A rule file with `trigger: always_on` frontmatter is included in every Cascade request in the workspace. The integration writes a small rule there telling the agent to recall first and retain what it learns.
+
+## Setup
+
+```bash
+pip install hindsight-windsurf
+cd your-project
+hindsight-windsurf init --api-token YOUR_HINDSIGHT_API_KEY --bank-id my-memory
+```
+
+`init` adds the `hindsight` MCP server to `~/.codeium/windsurf/mcp_config.json` (Windsurf's single global MCP config) and writes the recall/retain rule to `./.windsurf/rules/hindsight.md`. Reload Windsurf (or refresh MCP servers in Cascade), and the `hindsight` server's tools become available.
+
+Use a [Hindsight Cloud](https://hindsight.vectorize.io) key, or point at a self-hosted server with `--api-url http://localhost:8888` (no token needed for an open local server). If your `mcp_config.json` isn't plain JSON, `init` prints the entry to paste rather than rewriting the file — or run `hindsight-windsurf init --print-only` anytime.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `hindsight-windsurf init` | Add the MCP server + recall/retain rule |
+| `hindsight-windsurf status` | Show whether the server + rule are configured |
+| `hindsight-windsurf uninstall` | Remove the server + rule |
+
+## Note
+
+Recall and retain run through MCP tools the agent calls, guided by the always-on rule. This makes recall query-time precise (no lag), with the tradeoff that it relies on the agent following the "recall first" instruction rather than the editor enforcing it.
+
+See the [package README](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/windsurf) for full configuration options.

hindsight-docs/src/data/integrations.json

@@ -549,6 +549,16 @@
       "category": "tool",
       "link": "/sdks/integrations/openhands",
       "icon": "/img/icons/openhands.png"
+    },
+    {
+      "id": "windsurf",
+      "name": "Windsurf",
+      "description": "Long-term memory for Windsurf (Codeium) via its native MCP support. One command wires the Hindsight MCP server into mcp_config.json plus an always-on recall/retain rule, so memory works automatically in Cascade.",
+      "type": "official",
+      "by": "hindsight",
+      "category": "tool",
+      "link": "/sdks/integrations/windsurf",
+      "icon": "/img/icons/windsurf.svg"
     }
   ]
 }

hindsight-integrations/README.md

@@ -13,6 +13,7 @@ Each integration lives in its own subdirectory with its own README, configuratio
 | [**Codex CLI**](./codex) | Python hook scripts for OpenAI's Codex CLI. Auto-recall on `UserPromptSubmit`, auto-retain on `Stop`. | `curl -fsSL https://hindsight.vectorize.io/get-codex \| bash` |
 | [**Cursor CLI**](./cursor-cli) | Python hook scripts for Cursor CLI. Auto-recall on `beforeSubmitPrompt`, auto-retain on `stop`, final flush on `sessionEnd`. | `./scripts/install.sh` |
 | [**Continue.dev**](./continue) | HTTP context provider for precise `@hindsight` recall in chat, plus optional MCP-server + rules for automatic recall/retain in agent mode. | `pip install hindsight-continue` |
+| [**Windsurf**](./windsurf) | Native MCP server config + always-on recall/retain rule for Windsurf (Codeium) Cascade. | `pip install hindsight-windsurf` |
 | [**Roo Code**](./roo-code) | Persistent memory for Roo Code VS Code extension. | See README |
 | [**Hermes (OpenAI Agents SDK)**](./hermes) | Memory layer for OpenAI Agents SDK. | See README |
 | [**Grok Build**](./grok-build) | Hooks for Grok Build (xAI). | See README |

hindsight-integrations/windsurf/README.md

@@ -0,0 +1,79 @@
+# hindsight-windsurf
+
+Long-term memory for **Windsurf** (Codeium), powered by [Hindsight](https://github.com/vectorize-io/hindsight).
+
+`hindsight-windsurf init` wires the Hindsight **MCP server** into Windsurf's
+`~/.codeium/windsurf/mcp_config.json` and adds an always-on recall/retain rule to
+`.windsurf/rules/hindsight.md`. Cascade then has `recall` / `retain` / `reflect`
+tools and — guided by the rule — recalls relevant memory at the start of a task
+and retains durable facts as it works.
+
+## How it works
+
+Windsurf supports two things this integration uses:
+
+- **MCP servers** in `~/.codeium/windsurf/mcp_config.json` under `mcpServers`,
+  including **remote servers** via `serverUrl` with headers — so the Hindsight
+  MCP endpoint connects directly:
+
+  ```json
+  {
+    "mcpServers": {
+      "hindsight": {
+        "serverUrl": "https://api.hindsight.vectorize.io/mcp/my-project/",
+        "headers": { "Authorization": "Bearer hsk_..." }
+      }
+    }
+  }
+  ```
+
+- **Workspace rules** in `.windsurf/rules/`. A rule file with `trigger: always_on`
+  frontmatter is applied to every Cascade request in the workspace — that's where
+  the recall/retain rule lives.
+
+## Install
+
+```bash
+pip install hindsight-windsurf
+cd your-project
+hindsight-windsurf init --api-token YOUR_HINDSIGHT_API_KEY --bank-id my-project
+```
+
+`init` merges the `mcpServers` entry into `~/.codeium/windsurf/mcp_config.json`
+(Windsurf's single global MCP config) and writes the rule into
+`./.windsurf/rules/hindsight.md`. Reload Windsurf (or refresh MCP servers in
+Cascade) and the `hindsight` tools are available.
+
+Use a [Hindsight Cloud](https://hindsight.vectorize.io) key, or a self-hosted
+server with `--api-url http://localhost:8888` (no token needed for an open local
+server). If `mcp_config.json` isn't plain JSON, `init` prints the snippet to
+paste instead of touching the file — or run `hindsight-windsurf init --print-only`
+anytime.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `hindsight-windsurf init` | Add the MCP server + recall/retain rule |
+| `hindsight-windsurf status` | Show whether the server + rule are configured |
+| `hindsight-windsurf uninstall` | Remove the server + rule |
+
+## Configuration
+
+| Setting | Env var | Default |
+| --- | --- | --- |
+| API URL | `HINDSIGHT_API_URL` | `https://api.hindsight.vectorize.io` |
+| API token | `HINDSIGHT_API_TOKEN` | _(none; required for Cloud)_ |
+| Bank id | `HINDSIGHT_WINDSURF_BANK_ID` | `windsurf` |
+
+## Development
+
+```bash
+uv sync
+uv run pytest tests -v -m 'not requires_real_llm'   # deterministic suite
+uv run pytest tests -v -m requires_real_llm          # gated MCP-endpoint check
+```
+
+## License
+
+MIT

hindsight-integrations/windsurf/hindsight_windsurf/__init__.py

@@ -0,0 +1,12 @@
+"""Hindsight memory integration for Windsurf (Codeium).
+
+Wires the Hindsight MCP server into Windsurf's ``~/.codeium/windsurf/mcp_config.json``
+and writes an always-on recall/retain rule into ``.windsurf/rules/hindsight.md``,
+so Cascade has ``recall``/``retain``/``reflect`` tools and uses them automatically.
+
+CLI::
+
+    hindsight-windsurf init --api-token hsk_... --bank-id my-project
+"""
+
+__version__ = "0.1.0"