Mnemosyne — SQLite-Backed Memory Provider
Purpose
SQLite-backed memory provider with sync and optional MCP server. Part of the ai/ module tree.
Entry Point
- Main file: mnemosyne.nix
- Upstream: mnemosyne-oss/mnemosyne
Architecture / Services / Scope
graph TB
subgraph "NixAI Host"
HC["Hermes Container<br/>(mnemosyne-hermes plugin)"]
SS["Sync Server<br/>(mnemosyne sync-serve)"]
MS["MCP Server<br/>(mnemosyne mcp)"]
CD["Caddy Proxy"]
CT["systemd Timer<br/>(sync client)"]
end
subgraph "External"
EXT["External MCP Clients<br/>(Cursor, Claude Code)"]
REMOTE["Remote Mnemosyne<br/>(laptop, other host)"]
end
HC -->|"plugin reads/writes"| DB[(mnemosyne.db<br/>in container)]
CT -->|"mnemosyne sync --remote"| SS
SS -->|"serve"| SDB[(mnemosyne.db<br/>/var/lib/mnemosyne)]
MS -->|"mcp"| SDB
CD -->|"reverse_proxy"| SS
CD -->|"reverse_proxy"| MS
EXT -->|"MCP/SSE"| CD
REMOTE -->|"sync protocol"| CD
The module can run three kinds of services, each either natively on the host or inside a Docker container:
- Sync server (
mnemosyne sync-serve) — stdlib HTTP, no extra Python dependencies. - MCP server (
mnemosyne mcp) — adds themcpandanyiodependencies via the package’s optionalmcpgroup. - Sync client — per-profile periodic sync to a remote server, driven by a systemd timer (default interval 10 minutes).
Options
services.mnemosyne.client.sync
| Type | attribute set of (submodule) |
| Default | { } |
Sync client profiles for periodic sync to remote servers.
services.mnemosyne.client.sync.<name>.apiKeyFile
| Type | null or absolute path |
| Default | null |
Runtime path to a file containing the API key for authentication.
services.mnemosyne.client.sync.<name>.container
| Type | null or string |
| Default | null |
Docker container to run the sync client inside. If null, the server runs natively on the host.
Additionally, this will only work if the /nix/store is mounted inside the container.
services.mnemosyne.client.sync.<name>.interval
| Type | string |
| Default | "*:0/10" |
Systemd OnCalendar interval for sync. Default runs every 10 minutes.
services.mnemosyne.client.sync.<name>.remote
| Type | string |
Sync server URL (e.g. http://sync.example.com).
services.mnemosyne.client.sync.<name>.user
| Type | null or string |
| Default | null |
User to run the sync client as inside the container.
services.mnemosyne.dataDir
| Type | string |
| Default | "/var/lib/mnemosyne" |
Data directory for Mnemosyne state.
services.mnemosyne.enable
| Type | boolean |
| Default | false |
| Example | true |
Whether to enable Mnemosyne memory service.
services.mnemosyne.server.mcp.container
| Type | null or string |
| Default | null |
Docker container to run the mcp server inside. If null, the server runs natively on the host.
Additionally, this will only work if the /nix/store is mounted inside the container.
services.mnemosyne.server.mcp.enable
| Type | boolean |
| Default | false |
| Example | true |
Whether to enable Mnemosyne mcp server.
services.mnemosyne.server.mcp.host
| Type | string |
| Default | "127.0.0.1" |
Host address for the mcp server to listen on.
services.mnemosyne.server.mcp.port
| Type | 16 bit unsigned integer; between 0 and 65535 (both inclusive) |
| Default | 8766 |
Port for the mcp server to listen on.
services.mnemosyne.server.mcp.user
| Type | null or string |
| Default | null |
User to run the mcp server as inside the container.
services.mnemosyne.server.sync.apiKeyFile
| Type | null or absolute path |
| Default | null |
Runtime path to a file containing the API key for authentication.
services.mnemosyne.server.sync.container
| Type | null or string |
| Default | null |
Docker container to run the sync server inside. If null, the server runs natively on the host.
Additionally, this will only work if the /nix/store is mounted inside the container.
services.mnemosyne.server.sync.enable
| Type | boolean |
| Default | false |
| Example | true |
Whether to enable Mnemosyne sync server.
services.mnemosyne.server.sync.host
| Type | string |
| Default | "127.0.0.1" |
Host address for the sync server to listen on.
services.mnemosyne.server.sync.port
| Type | 16 bit unsigned integer; between 0 and 65535 (both inclusive) |
| Default | 8765 |
Port for the sync server to listen on.
services.mnemosyne.server.sync.user
| Type | null or string |
| Default | null |
User to run the sync server as inside the container.
Secrets
MNEMOSYNE_SYNC_KEY— API key for sync server authentication (host-level sops secret), provided viaapiKeyFileand loaded into the services through systemd credentials.
Operational Notes / Assumptions
- Sync protocol is plain HTTP with delta-based bidirectional sync.
- Sync interval default is 10 minutes.
Usage Examples
Server-only (central sync)
{
services.mnemosyne = {
enable = true;
server.sync.enable = true;
};
}
Client-only (sync to remote)
{
services.mnemosyne = {
enable = true;
client.sync.hermes = {
enable = true;
remote = "http://sync.example.com:8765";
interval = "*:0/15";
};
};
}