MCP Setup (Local) — Pensyve Docs

The local MCP server runs Pensyve on your machine with SQLite storage and ONNX embeddings. No cloud account or API key needed.

For zero-setup cloud access, see Remote MCP instead — just an API key, no binary to install.

Build

git clone https://github.com/major7apps/pensyve
cd pensyve
cargo build --release -p pensyve-mcp
# Binary at: target/release/pensyve-mcp

Client Configuration

Claude Code

Install the full plugin (recommended):

/plugin marketplace add /path/to/pensyve/integrations/claude-code
/plugin install pensyve@pensyve

Then override the MCP config in .claude/settings.json to use your local binary:

{
  "mcpServers": {
    "pensyve": {
      "command": "pensyve-mcp",
      "args": ["--stdio"],
      "env": {
        "PENSYVE_NAMESPACE": "my-project"
      }
    }
  }
}

Or connect directly without the plugin:

claude mcp add pensyve -- /path/to/pensyve-mcp

Claude Desktop

Add to your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pensyve": {
      "command": "/path/to/pensyve-mcp",
      "args": ["--stdio"],
      "env": {
        "PENSYVE_NAMESPACE": "default"
      }
    }
  }
}

Restart Claude Desktop after editing the config.

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "pensyve": {
      "command": "pensyve-mcp",
      "args": ["--stdio"],
      "env": {
        "PENSYVE_NAMESPACE": "default"
      }
    }
  }
}

VS Code (Copilot Chat)

Add to .vscode/mcp.json:

{
  "servers": {
    "pensyve": {
      "type": "stdio",
      "command": "pensyve-mcp",
      "args": ["--stdio"],
      "env": {
        "PENSYVE_NAMESPACE": "default"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "pensyve": {
      "command": "pensyve-mcp",
      "args": ["--stdio"],
      "env": {
        "PENSYVE_NAMESPACE": "default"
      }
    }
  }
}

Cline / Continue

See the integration READMEs in the GitHub repo.

Available Tools

The MCP server exposes 8 tools:

Tool	Description
`pensyve_recall`	Search memories by semantic similarity and text matching
`pensyve_remember`	Store a fact about an entity as semantic memory
`pensyve_episode_start`	Begin tracking an interaction episode
`pensyve_episode_end`	Close an episode and extract memories
`pensyve_forget`	Delete all memories for an entity
`pensyve_inspect`	View all memories for an entity
`pensyve_status`	Namespace info, memory counts, health
`pensyve_account`	Plan and usage info

For detailed parameter reference and response examples, see the MCP Tools Reference.

Environment Variables

Variable	Default	Purpose
`PENSYVE_PATH`	`~/.pensyve/default`	SQLite database directory
`PENSYVE_NAMESPACE`	`"default"`	Memory namespace for isolation

Set these in the env block of your MCP config, or export them in your shell.

Troubleshooting

Server doesn't start: Check that PENSYVE_PATH is writable. The server creates the SQLite database and WAL files on first run.

No semantic search results: If the ONNX embedding model can't load, the server falls back to a mock embedder. Check stderr logs for "mock" warnings.

Slow first recall: The vector index is built in memory on startup. With large stores (10K+ memories), startup may take a few seconds.

Entity not found after remember: Entities are created automatically. If filtering by entity in pensyve_recall, ensure the entity name matches exactly (case-sensitive, lowercase, hyphenated).

On this page