MCP Setup — Pensyve Docs

The MCP server exposes Pensyve tools over stdio, so any MCP-compatible client can use agent memory directly. Supported clients include Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, and Continue.

Install

cargo install --path pensyve-mcp

Or build a release binary:

cargo build -p pensyve-mcp --release
# Binary at: target/release/pensyve-mcp

Client Configuration

Claude Code

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

Or add to your project's .mcp.json:

{
  "mcpServers": {
    "pensyve": {
      "command": "/path/to/pensyve-mcp",
      "env": {
        "PENSYVE_PATH": "~/.pensyve/",
        "PENSYVE_NAMESPACE": "default"
      }
    }
  }
}

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",
      "env": {
        "PENSYVE_PATH": "~/.pensyve/",
        "PENSYVE_NAMESPACE": "default"
      }
    }
  }
}

Restart Claude Desktop after editing the config.

Cursor

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

{
  "mcpServers": {
    "pensyve": {
      "command": "/path/to/pensyve-mcp",
      "env": {
        "PENSYVE_PATH": "~/.pensyve/",
        "PENSYVE_NAMESPACE": "default"
      }
    }
  }
}

VS Code (Copilot Chat)

Add to .vscode/mcp.json:

{
  "servers": {
    "pensyve": {
      "command": "/path/to/pensyve-mcp",
      "env": {
        "PENSYVE_PATH": "~/.pensyve/",
        "PENSYVE_NAMESPACE": "default"
      }
    }
  }
}

Replace /path/to/pensyve-mcp with the actual path to your built binary in all configurations above.

Available Tools

The MCP server exposes six tools:

Tool	Description
`pensyve_recall`	Search memories by semantic similarity and text matching. Returns ranked results from episodic, semantic, and procedural memory.
`pensyve_remember`	Store an explicit fact about an entity as a semantic memory.
`pensyve_episode_start`	Begin tracking an interaction episode with named participants. Returns an `episode_id`.
`pensyve_episode_end`	Close an episode and extract memories. Takes the `episode_id` from start.
`pensyve_forget`	Delete all memories associated with an entity. Rebuilds the vector index after deletion.
`pensyve_inspect`	View all memories stored for an entity, optionally filtered by type.

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

Example Usage

Once configured, Claude can use Pensyve tools in conversation:

User: "Remember that I prefer TypeScript over JavaScript."

Claude calls pensyve_remember:

{
  "entity": "user",
  "fact": "Prefers TypeScript over JavaScript",
  "confidence": 0.95
}

User: "What do you know about my preferences?"

Claude calls pensyve_recall:

{
  "query": "user preferences",
  "entity": "user",
  "limit": 10
}

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 before running the binary.

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 that produces zero-value vectors. Semantic similarity won't work with the mock — only BM25 text matching. Check stderr logs for "mock" warnings.

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

Entity not found after remember: Entities are created automatically when you call pensyve_remember or pensyve_episode_start. If you're filtering by entity in pensyve_recall, ensure the entity name matches exactly (case-sensitive).

On this page