Pensyve MCP Server

Pensyve

Pensyve is an open-source runtime for persistent AI agent memory. It stores facts, conversations, observations, and action outcomes so an agent can retrieve them in later sessions. You can use it through Python, a Model Context Protocol (MCP) server, a command-line tool, or a REST API.

The Rust engine uses SQLite for local storage and runs embedding models locally to search by meaning. TypeScript and Go clients connect to a gateway you run yourself. Local use does not require a Pensyve account or API key. Your application or client integration calls Pensyve to save and retrieve memories.

Choose a setup

Project status

Pensyve Cloud closed on October 1, 2026. The open-source project continues in this repository under the Apache 2.0 license, with the engine, SDKs, integrations, and documentation available here.

Pensyve is in maintenance mode. Releases cover security fixes and dependency updates, with no new features planned. See the maintenance policy for contribution and support expectations. If you have a saved Cloud export, the self-hosting guide explains how to use it with your own gateway.

What you can do

• Store facts about users, projects, or other named entities, and record conversations as episodes.
• Search memories using text matching, embeddings, and relationships between entities.
• Record observations and action outcomes, and use consolidation to promote repeated facts and update memory retention.
• Keep data in local SQLite storage, or run the HTTP gateway with SQLite or PostgreSQL.

Embedding models may download when first loaded unless they are already cached. Running without network access requires preparing the model files first. See the model setup and deployment guide.

How agent memory works

Pensyve stores memory outside the language model. Your application saves facts or conversations, searches for relevant records, and adds the results to a later prompt. Reusing the same storage path and namespace lets the agent retrieve information across processes and sessions. Saving a memory does not train the language model or change its weights.

The store holds four kinds of records: facts (semantic memory), conversations (episodic memory), action outcomes (procedural memory), and observations. Your integration decides what to record and when to retrieve it. Recording a conversation does not automatically turn it into a successful procedure. See how storage and retrieval work and the usage recipes for the APIs and their limits.

Python quick start

Python 3.10 or newer is required.

pip install pensyve

Create a local store, save a fact, and retrieve it:

import pensyve

p = pensyve.Pensyve(path="./memories", namespace="my-agent")
user = p.entity("user", kind="user")

p.remember(
    entity=user,
    fact="Prefers dark mode and vim keybindings",
    confidence=0.95,
)

for memory in p.recall("editor preferences", entity=user):
    print(memory.content)

Reuse the same path and namespace in a later process to retrieve saved memories. The Python SDK runs the engine in your process and does not need the HTTP gateway.

You can also record a conversation with the same p and user:

with p.episode(user) as episode:
    episode.message("user", "Use dark mode in my editor")
    episode.message("agent", "I updated the editor settings")
    episode.outcome("success")

groups = p.recall_grouped("editor settings", limit=10)
for group in groups:
    for memory in group.memories:
        print(memory.content)

recall_grouped() groups results by source session for use in an agent's prompt. See the Python SDK guide and recipes for more examples.

MCP server

Pensyve's local MCP memory server lets clients such as Claude Code, Codex, and Cursor store and retrieve memories across sessions. From a checkout of this repository, install the server with Rust 1.94 or newer:

git clone https://github.com/major7apps/pensyve.git
cd pensyve
cargo install --path pensyve-mcp --locked

Make sure Cargo's binary directory is on your client's PATH, then add a stdio server entry to its MCP configuration:

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

The server provides tools such as pensyve_remember, pensyve_recall, pensyve_observe, and pensyve_inspect. It stores data locally and needs no API key. The configuration file location depends on your client. See the MCP setup guide and integration guides.

HTTP gateway

Run the gateway to access Pensyve over REST or MCP HTTP, including from the TypeScript and Go SDKs. From the repository root, start a local instance:

HOST=127.0.0.1 PENSYVE_API_KEYS=psy_local_example \
  cargo run --release -p pensyve-mcp-gateway

In another terminal, save and recall a fact:

curl http://localhost:3000/v1/remember \
  -H "Authorization: Bearer psy_local_example" \
  -H "Content-Type: application/json" \
  -d '{"entity":"user","fact":"Prefers Python","confidence":0.95}'

curl http://localhost:3000/v1/recall \
  -H "Authorization: Bearer psy_local_example" \
  -H "Content-Type: application/json" \
  -d '{"query":"programming language","entity":"user"}'

The MCP HTTP endpoint is http://localhost:3000/mcp. Use the same API key in your client's Authorization: Bearer header.

The example key is for local testing. For a deployment, choose your own key with the required psy_ prefix and configure HTTPS and allowed hosts. See the self-hosting guide, gateway configuration, and security documentation.

SDKs and integrations

The TypeScript and Go SDKs require a running gateway. Configure its URL and, when authentication is enabled, an API key from that gateway.

Command-line tool

From the repository root, install the CLI and inspect its commands:

cargo install --path pensyve-cli --locked
pensyve --help
pensyve status
pensyve recall "editor preferences" --entity user

The binary is named pensyve. Its default output is JSON, and --format text selects text output. The CLI uses its own default local storage location; it does not automatically open the ./memories directory from the Python example. See the CLI source and command definitions for storage and namespace options.

Documentation

Development and contributions

Start with CONTRIBUTING.md for prerequisites and setup. From the repository root:

uv sync --extra dev
make build
make check

make build compiles Rust and builds the Python extension. make check runs the Rust and Python lint and test commands. TypeScript and Go have separate checks documented in the contribution guide.

Issues and pull requests follow the maintenance policy. Report security issues through private vulnerability reporting.

License

Pensyve is licensed under Apache 2.0.