Skip to content
Palimem Docsspec v1.7.0

Use Palimem with Windsurf

Connect Palimem to Windsurf using the ai-memory connect windsurf helper. Windsurf supports global MCP configuration only (~/.codeium/windsurf/mcp_config.json); project-level MCP scoping is not currently available.

Prerequisites

Section titled “Prerequisites”
  • Windsurf with MCP support enabled
  • Node.js 18+
  • Repository cloned and Node dependencies installed:
    Terminal window
    cd app && npm install
Section titled “Recommended install”

From your repository root:

Terminal window
node app/scripts/ai-memory.js connect windsurf \
  --project-root "$(pwd)" \
  --data-dir .ai-memory/data

This writes the memory-service entry to ~/.codeium/windsurf/mcp_config.json. Restart Windsurf to pick up the change.

Config block

Section titled “Config block”

The committed sample lives at examples/windsurf/mcp_config.json.sample:

{
  "mcpServers": {
    "memory-service": {
      "command": "node",
      "args": ["/absolute/path/to/repo/app/scripts/memory-service-mcp.js"],
      "env": {
        "MEMORY_SERVICE_DATA_DIR": "/absolute/path/to/repo/.ai-memory/data"
      }
    }
  }
}

Replace /absolute/path/to/repo with the actual absolute path to your cloned repository. Always use absolute paths in Windsurf MCP config.

Verification

Section titled “Verification”
  1. Restart Windsurf.
  2. Ask the agent to call tools/list, then memory_status with scope repository and your project namespace.

tools/list — expect 11 tools.

memory_status — expect ok: true and index_status.state: "current".

Agent prompt

Section titled “Agent prompt”

Paste this into Windsurf Cascade to configure Palimem:

Set up Palimem as governed local memory for this Windsurf session.


- Project: Palimem (spec v1.7.0)
- Run: node app/scripts/ai-memory.js connect windsurf --project-root "$(pwd)" --data-dir .ai-memory/data
- Restart Windsurf after running the command
- Verify: tools/list (11 tools), then memory_status — expect ok and index_status current


Use local data directory .ai-memory/data. Do not enable cloud services.

CLI options

Section titled “CLI options”
Flag Purpose
--config PATH Override target mcp_config.json (default: ~/.codeium/windsurf/mcp_config.json)
--project-root PATH Repo root for resolving script paths (default: $PWD)
--data-dir PATH MEMORY_SERVICE_DATA_DIR resolved to absolute (default: .ai-memory/data)
--replace Overwrite existing memory-service entry
--dry-run Print merged JSON without writing

Troubleshooting

Section titled “Troubleshooting”

Server not listed in Windsurf MCP panel

Restart Windsurf after writing the config. Windsurf reads mcp_config.json on startup only.

ENOENT on memory-service-mcp.js

Install Node dependencies first:

Terminal window
cd app && npm install

Existing entry refused

Re-run with --replace:

Terminal window
node app/scripts/ai-memory.js connect windsurf \
  --project-root "$(pwd)" --data-dir .ai-memory/data --replace

Tools show 9 instead of 11

Pull the latest main and reconnect. memory_query_temporal and memory_audit_export require spec v1.6.0+.

Seed memory (optional)

Section titled “Seed memory (optional)”
Terminal window
python3 app/import_markdown.py \
  --data-dir .ai-memory/data \
  examples/markdown/USER.md.sample \
  examples/markdown/MEMORY.md.sample

Next steps

Section titled “Next steps”