Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions content/docs/mcp_servers/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,9 @@ Use these guides to configure specific MCP servers with the right transport, OAu
<Cards.Card title="Google Workspace MCP" href="/docs/mcp_servers/google_workspace" arrow>
Configure Gmail, Drive, Calendar, People, and Chat remote MCP servers with Google OAuth.
</Cards.Card>
<Cards.Card title="Perseus Vault MCP" href="/docs/mcp_servers/perseus_vault" arrow>
Give agents durable, encrypted, local-first long-term memory with the Perseus Vault MCP server.
</Cards.Card>
<Cards.Card title="Salesforce MCP" href="/docs/mcp_servers/salesforce" arrow>
Configure Salesforce Hosted MCP servers with an External Client App and per-user OAuth.
</Cards.Card>
Expand Down
2 changes: 1 addition & 1 deletion content/docs/mcp_servers/meta.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"title": "MCP Servers",
"icon": "Blocks",
"pages": ["index", "google_workspace", "salesforce"]
"pages": ["index", "google_workspace", "perseus_vault", "salesforce"]
}
135 changes: 135 additions & 0 deletions content/docs/mcp_servers/perseus_vault.mdx
Original file line number Diff line number Diff line change
@@ -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.

<Callout type="info" title="How this fits with LibreChat's built-in memory">
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.
</Callout>

## 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

<Steps>
<Step>

### 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
```

</Step>
<Step>

### 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=<the token from --mcp-token>` in your LibreChat `.env`.

</Step>
<Step>

### 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.

</Step>
<Step>

### 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.

</Step>
</Steps>

## 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)