MCP Setup — Pensyve Docs

The MCP server exposes Pensyve tools over stdio, so any MCP-compatible client (Claude Desktop, Cursor, etc.) can use agent memory directly.

Build

cargo build -p pensyve-mcp --release

The binary lands at target/release/pensyve-mcp.

Or run directly:

cargo run -p pensyve-mcp

Claude Desktop Configuration

Add this to your Claude Desktop 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"
      }
    }
  }
}

Replace /path/to/pensyve-mcp with the actual path to your built binary.

Restart Claude Desktop after editing the config.

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.
`pensyve_inspect`	View all memories stored for an entity, optionally filtered by type.

Tool Parameters

pensyve_recall

Parameter	Type	Required	Description
`query`	string	yes	Search query text
`entity`	string	no	Filter by entity name
`types`	string[]	no	Filter by memory type: `"episodic"`, `"semantic"`, `"procedural"`
`limit`	number	no	Max results (default: 5)

pensyve_remember

Parameter	Type	Required	Description
`entity`	string	yes	Entity this fact is about
`fact`	string	yes	The fact to store
`confidence`	number	no	Confidence in [0.0, 1.0] (default: 1.0)

pensyve_episode_start

Parameter	Type	Required	Description
`participants`	string[]	yes	Entity names of participants

pensyve_episode_end

Parameter	Type	Required	Description
`episode_id`	string	yes	The ID returned by `pensyve_episode_start`
`outcome`	string	no	`"success"`, `"failure"`, or `"partial"`

pensyve_forget

Parameter	Type	Required	Description
`entity`	string	yes	Entity whose memories to remove
`hard_delete`	boolean	no	Permanently delete instead of soft-delete

pensyve_inspect

Parameter	Type	Required	Description
`entity`	string	yes	Entity to inspect
`memory_type`	string	no	Filter: `"episodic"`, `"semantic"`, or `"procedural"`
`limit`	number	no	Max memories to return (default: 20)

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/`	SQLite database location
`PENSYVE_NAMESPACE`	`default`	Memory namespace

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

On this page