diff --git a/content/docs/mcp_servers/index.mdx b/content/docs/mcp_servers/index.mdx index 847cb162a..959c0b2f5 100644 --- a/content/docs/mcp_servers/index.mdx +++ b/content/docs/mcp_servers/index.mdx @@ -10,6 +10,9 @@ Use these guides to configure specific MCP servers with the right transport, OAu Configure Gmail, Drive, Calendar, People, and Chat remote MCP servers with Google OAuth. + + Give agents durable, encrypted, local-first long-term memory with the Perseus Vault MCP server. + Configure Salesforce Hosted MCP servers with an External Client App and per-user OAuth. diff --git a/content/docs/mcp_servers/meta.json b/content/docs/mcp_servers/meta.json index 396b0e2c6..357c1a481 100644 --- a/content/docs/mcp_servers/meta.json +++ b/content/docs/mcp_servers/meta.json @@ -1,5 +1,5 @@ { "title": "MCP Servers", "icon": "Blocks", - "pages": ["index", "google_workspace", "salesforce"] + "pages": ["index", "google_workspace", "perseus_vault", "salesforce"] } diff --git a/content/docs/mcp_servers/perseus_vault.mdx b/content/docs/mcp_servers/perseus_vault.mdx new file mode 100644 index 000000000..f5639a772 --- /dev/null +++ b/content/docs/mcp_servers/perseus_vault.mdx @@ -0,0 +1,135 @@ +--- +title: Perseus Vault MCP +icon: Lock +description: Give LibreChat agents durable, encrypted, local-first long-term memory with the Perseus Vault MCP server. +--- + +[Perseus Vault](https://github.com/Perseus-Computing-LLC/perseus-vault) is an open-source +(MIT), local-first, encrypted memory engine that ships as a single binary and speaks MCP +natively. This guide wires it into LibreChat so any **Agent** can remember and recall across +conversations using a private store that never leaves your machine, with no cloud and no API keys. + + + LibreChat ships a built-in *User Memory* system: a token-limited key/value store managed by an + internal memory agent (configured under the `memory:` key). That built-in agent takes a + provider/model but does **not** expose a pluggable storage backend or an MCP hookup, so this + guide does **not** replace LibreChat's memory store. Instead it gives your LibreChat **Agents** + the Perseus Vault MCP tools (`remember`, `recall`, `journal`, `timeline`, and more) as + first-class tools the agent calls directly. The two can coexist: keep LibreChat's lightweight + personalization memory on, and add Perseus Vault for long-term, private, structured recall. + + +## Prerequisites + +- A running LibreChat instance with `librechat.yaml` mounted or otherwise loaded. +- The Perseus Vault binary installed (via the bootstrap script or Docker — see the + [Perseus Vault repository](https://github.com/Perseus-Computing-LLC/perseus-vault)). + +## Setup + + + + +### Run Perseus Vault + +Perseus Vault runs as a local single binary. If LibreChat runs on the **same host** (not +containerized), you can skip networking entirely and let LibreChat launch the binary over stdio +(see Option A below). + +If LibreChat runs in **Docker**, expose Perseus Vault over its HTTP/SSE MCP transport so the +container can reach it: + +```bash +perseus-vault \ + --db ~/.mimir/data/perseus-vault.db \ + --transport sse \ + --web-bind 127.0.0.1 \ + --port 8765 \ + --mcp-token "$(openssl rand -hex 32)" # required for non-loopback binds + # optional encryption at rest: + # --encryption-key ~/.mimir/secret.key +``` + + + + +### Add Perseus Vault to `librechat.yaml` + +Register the server under `mcpServers`. Choose the option that matches your deployment. + +#### Option A — stdio (LibreChat and Perseus Vault on the same host) + +```yaml +mcpServers: + perseus-vault: + type: stdio + title: "Perseus Vault" + description: "Local-first encrypted long-term memory (remember / recall across sessions)." + command: perseus-vault + args: + - "--db" + - "/home/YOUR_USER/.mimir/data/perseus-vault.db" + timeout: 60000 + initTimeout: 15000 + chatMenu: true + serverInstructions: true # surfaces Perseus Vault's tool usage guidance to the agent +``` + +#### Option B — SSE/HTTP (LibreChat in Docker, Perseus Vault on the host or another container) + +```yaml +mcpServers: + perseus-vault: + type: sse # or: streamable-http + title: "Perseus Vault" + description: "Local-first encrypted long-term memory (remember / recall across sessions)." + url: "http://host.docker.internal:8765/sse" + headers: + Authorization: "Bearer ${PERSEUS_VAULT_TOKEN}" # matches --mcp-token + timeout: 60000 + chatMenu: true + serverInstructions: true +``` + +For Option B, put `PERSEUS_VAULT_TOKEN=` in your LibreChat `.env`. + + + + +### Attach it to an Agent + +In the LibreChat **Agent Builder**, create or edit an agent and enable the **perseus-vault** MCP +server under its tools. The agent can now call Perseus Vault to persist and retrieve memory. + +A good agent instruction: + +> At the start of a task, call Perseus Vault `recall` to load relevant prior context. When you +> learn a durable fact, decision, or user preference, store it with `remember`. Use `journal` for +> time-ordered notes. + + + + +### Verify + +1. Start a chat with the agent and tell it a durable fact, for example: + "remember that our staging DB is `pg-eu-2`". +2. Start a **new** conversation with the same agent and ask it to recall the fact. It should + retrieve it from Perseus Vault, proving cross-session persistence backed by the encrypted + local store. + + + + +## Why this fits LibreChat + +- **Local-first and private:** data never leaves the box and is encrypted at rest — matching the + reasons self-hosters run LibreChat instead of a hosted assistant. +- **No new infrastructure:** a single binary, with no Postgres, Redis, or vector database to + stand up. +- **MCP-native:** uses LibreChat's first-class MCP support, so there is nothing custom to maintain. + +## Learn more + +- [Perseus Vault on GitHub](https://github.com/Perseus-Computing-LLC/perseus-vault) (MIT license) +- [MCP overview in LibreChat](/docs/features/mcp)