MCP Tools

Pensyve exposes an MCP server over stdio. Connect it to any MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.).

# Run the MCP server
cargo run -p pensyve-mcp

The MCP server uses the rmcp crate with stdio transport. All logging goes to stderr — stdout is reserved for the MCP protocol.

Configuration

The server reads these environment variables on startup:

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

On startup the server loads the ONNX embedding model (all-MiniLM-L6-v2, 384 dims). Falls back to a mock embedder if the model is unavailable.

Tools

`pensyve_recall`

Search memories by semantic similarity and text matching. Returns ranked results from episodic, semantic, and procedural memory.

Parameters:

Name	Type	Required	Description
`query`	`string`	yes	Search query text
`entity`	`string`	no	Entity name to filter by
`types`	`string[]`	no	Memory types to include: `"episodic"`, `"semantic"`, `"procedural"`
`limit`	`integer`	no	Max results (default: 5)

Returns: JSON array of memory objects, each with _type and _score fields. Embeddings are stripped from the output.

Example call:

{
  "name": "pensyve_recall",
  "arguments": {
    "query": "deployment process",
    "entity": "my-agent",
    "types": ["procedural"],
    "limit": 10
  }
}

Example response:

[
  {
    "_type": "semantic",
    "_score": 0.87,
    "id": "a1b2c3d4-...",
    "subject": "550e8400-...",
    "predicate": "deploys",
    "object": "via GitHub Actions CI pipeline",
    "confidence": 0.95
  }
]

`pensyve_remember`

Store an explicit fact about an entity as a semantic memory.

Parameters:

Name	Type	Required	Description
`entity`	`string`	yes	Entity name
`fact`	`string`	yes	The fact to store
`confidence`	`number`	no	Confidence in `[0, 1]` (default: 1.0)

The fact is split on the first whitespace into predicate and object. An embedding is generated and stored alongside the memory.

Returns: The stored memory object (embedding stripped).

Example call:

{
  "name": "pensyve_remember",
  "arguments": {
    "entity": "alice",
    "fact": "prefers dark mode in all editors",
    "confidence": 0.9
  }
}

Example response:

{
  "id": "a1b2c3d4-...",
  "namespace_id": "...",
  "subject": "550e8400-...",
  "predicate": "prefers",
  "object": "dark mode in all editors",
  "confidence": 0.9,
  "stability": 1.0
}

`pensyve_episode_start`

Begin tracking an interaction episode with named participants.

Parameters:

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

Creates entities that don't exist yet (as agent kind).

Returns: Episode ID, participant list, and start timestamp.

Example call:

{
  "name": "pensyve_episode_start",
  "arguments": {
    "participants": ["alice", "my-agent"]
  }
}

Example response:

{
  "episode_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "participants": ["alice", "my-agent"],
  "started_at": "2026-03-19T12:00:00Z"
}

`pensyve_episode_end`

Close an episode and extract memories.

Parameters:

Name	Type	Required	Description
`episode_id`	`string`	yes	Episode ID from `pensyve_episode_start`
`outcome`	`string`	no	`"success"`, `"failure"`, or `"partial"` (default: `"success"`)

Returns: Episode ID, memory count, outcome, and end timestamp.

Example call:

{
  "name": "pensyve_episode_end",
  "arguments": {
    "episode_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "outcome": "success"
  }
}

Example response:

{
  "episode_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "memories_created": 0,
  "outcome": "success",
  "ended_at": "2026-03-19T12:05:00Z"
}

`pensyve_forget`

Delete all memories associated with an entity.

Parameters:

Name	Type	Required	Description
`entity`	`string`	yes	Entity name
`hard_delete`	`boolean`	no	Permanently delete (default: false)

Returns: Entity name, entity ID, and count of forgotten memories. Returns forgotten_count: 0 with a message if the entity is not found.

Example call:

{
  "name": "pensyve_forget",
  "arguments": {
    "entity": "alice",
    "hard_delete": true
  }
}

Example response:

{
  "entity": "alice",
  "entity_id": "550e8400-...",
  "forgotten_count": 12
}

`pensyve_inspect`

View all memories stored for an entity, optionally filtered by type.

Parameters:

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

Returns: Entity info, memory count, and array of memory objects (embeddings stripped).

Example call:

{
  "name": "pensyve_inspect",
  "arguments": {
    "entity": "alice",
    "memory_type": "semantic",
    "limit": 50
  }
}

Example response:

{
  "entity": "alice",
  "entity_id": "550e8400-...",
  "memory_count": 3,
  "memories": [
    {
      "_type": "semantic",
      "id": "...",
      "predicate": "prefers",
      "object": "dark mode",
      "confidence": 0.9
    }
  ]
}

Claude Desktop Configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "pensyve": {
      "command": "cargo",
      "args": ["run", "-p", "pensyve-mcp"],
      "cwd": "/path/to/pensyve",
      "env": {
        "PENSYVE_PATH": "~/.pensyve/claude",
        "PENSYVE_NAMESPACE": "default"
      }
    }
  }
}

Or with a pre-built binary:

{
  "mcpServers": {
    "pensyve": {
      "command": "/usr/local/bin/pensyve-mcp"
    }
  }
}

On this page