Desktop configuration (Windows, Linux and macOS)

Memories reads a UTF-8 TOML file for non-secret local settings. The CLI, daemon, Windows tray, macOS menu-bar app and WebUI use the same configuration loader. The release archive contains memories.example.toml; the source template lives in crates/cli/assets/memories.example.toml.

Create and inspect

memories config path
memories config init
memories config show

config init creates a commented example at the normal configuration location. It never overwrites an existing file. config path reports the exact selected location, and config show displays the effective values without opening or creating the encrypted store. To keep a separate development configuration:

memories config init --output ./development.toml
memories --config ./development.toml config show
memories --config ./development.toml daemon
memories --config ./development.toml tray

Configuration-file selection is --config, then MEMORIES_CONFIG, then the OS default. A current-directory file is never discovered implicitly. An explicitly selected missing file is an error, except when creating it with config init.

Use memories config path as the authoritative path for the current account. No personal configuration is created just by installing or launching a release.

Settings

# Windows example: storage_dir = "D:/MemoriesData"
storage_dir = "~/MemoriesData"
relay_url = "wss://relay.example.com"

[desktop]
port = 0
open_browser = true

For each setting, command-line options take precedence over environment variables, then the TOML value, then the built-in default. Without storage_dir, the existing OS data directory is unchanged. There is no built-in public relay. Browser opening defaults to true and the dashboard port defaults to zero.

Relative storage_dir paths are resolved beside the configuration file, not the shell working directory. A leading ~/ expands to the current user's home. Use forward slashes or TOML literal strings for Windows paths. Changing this setting selects a different store; it does not migrate or copy existing data. Restart the daemon and tray together after changing storage or desktop settings. The tray forwards its selected configuration and resolved store to child probes and daemon launches.

Language remains controlled by the existing --lang, MEMORIES_LANG, and memories language settings. A saved language is read from the configured store directory. The WebUI also has its own browser language selector.

Relay examples

memories --config ./development.toml sync receive --room ROOM
memories --config ./development.toml sync send VAULT_ID RECIPIENT_DEVICE_PUBLIC_KEY --room ROOM
memories sync receive --relay wss://another-relay.example.com --room ROOM

Only wss:// is accepted for remote relays. ws:// is allowed for loopback development (localhost, 127.0.0.1 or ::1). URLs cannot contain a username/password. The existing relay protocol determines the channel path from the room and slot. Setting a relay does not enable automatic relay synchronization or start a relay server; it supplies the default address for explicit send/receive operations.

The file is not encrypted. Store passwords, private keys, OAuth tokens and MCP grants in their existing protected mechanisms, never in this file. Unknown keys, invalid values and malformed TOML fail closed instead of silently switching to another store. Configuration error messages do not echo TOML source values.

Retrieval and model settings

The same file accepts [rag], [rag.http] and optional [rag.embedding], [rag.generation] and [rag.rerank] sections. They configure the in-process EmbeddingGemma model directory/CPU threads, customer-selected API URLs and model names, API-key environment-variable names, proxies, timeouts and retries. Generation has no default endpoint; embeddings default to the local model. See retrieval and RAG and the shipped example for complete settings. Restart the daemon after changing these settings. The tray forwards the config path when it starts the daemon; model keys must be available in its environment.

Remote daemon listen (not TOML)

HTTP/relay RPC listen tokens must not be placed in the configuration file. Use flags or environment variables only:

See remote daemon for HTTP/WebSocket listen details.

Authorization Centers

This section configures the desktop daemon and CLI. The phone's Standalone, Center and SaaS choices are separate app settings; see mobile mode selection.

Optional [[centers]] entries (id, url, public_key, optional mode) make an endpoint Center-managed: init/restore and local MCP grants are refused. mode = "ticket" is the default: use memories center enroll / import-grant with signed tickets. Exactly one mode = "saas" entry may instead attach daemon content to a hosted Center using MEMORIES_CENTER_TOKEN; no parallel local enrollment/content path is created. Direct Center CLI calls use MEMORIES_CENTER_URL / MEMORIES_CENTER_TOKEN, or MEMORIES_CENTER_ADMIN_TOKEN for admin operations. Signing secrets and bearer tokens stay in environment, never TOML. See center.

Omitted grant scopes now default to read, including Center tickets and static hosted grant specifications. Local Admin/Owner grant issuance and ticket import need an unlocked vault, but not terminal elevation. Issuance is bounded by the vault role and any parent grant's scope and expiry; only an Owner may explicitly select allow_all. Bearers remain outside TOML. Membership changes revoke affected delegated grants, and locking clears all local grants. See authorization for the RPC names, permission requests, access lists, audit compatibility, and behavior changes.

In hosted mode, memories-center --data DIR (environment MEMORIES_CENTER_DATA) also stores durable request metadata in DIR/requests.json and the append-only SHA-256 audit chain in DIR/audit.jsonl; both use Unix mode 0600, with DIR mode 0700. Existing DIR/members.json still contains plaintext durable bearer credentials. Protect all three files and their backups; never commit them. No new password, token, or audit settings belong in TOML. Audit/request/member save failures lock the server and set restart_required; remote unlock cannot bypass that state. Repair and restart with the operator-held password instead.

Hosted member HTTP bodies accept optional role=reader|editor|admin|owner; role omission preserves the existing scope-to-role mapping. POST /v1/grants defaults to scope=read, duration_minutes=30 (alias minutes), and requires Admin/Owner. POST /v1/requests uses duration_minutes (alias duration) plus optional approvers; GET /v1/requests lists pending work. GET /v1/access/{vault} and GET /v1/grants expose token-free access metadata. GET /v1/audit?vault=NAME filters verified entries and GET /v1/audit?format=jsonl exports the complete operator-visible log. These authorization routes use existing hosted/admin bearers, not new environment variables. Member removal/scope changes invalidate all older minted grants through frozen issuance generations; static/durable credentials are re-established at the transition. See Center for exact routes, response fields, and audit-chain limitations.

Mobile mode selection

Select the mode on first launch, then use Switch mode in the main toolbar. The app does not read MEMORIES_CENTER_URL / MEMORIES_CENTER_TOKEN or edit [[centers]] when this choice changes.

Center URLs must use HTTPS off loopback and contain no username, password, non-root path, query or fragment. Enter the server origin, not /v1/rpc. The phone's loopback address refers to the phone itself, not a development computer.

The non-secret preference memories.app-mode.v1 stores standalone, center or saas. Missing or unknown values show the mode chooser. Connection profiles are JSON objects stored with flutter_secure_storage under memories.hosted.center.connection.v2 and memories.hosted.saas.connection.v2; each binds a url to its bearer. A successful new connection saves the pair only after the request list can be loaded. Disconnect removes the bearer while retaining the URL; switching modes retains both profiles for later use.

On upgrade, the legacy memories.hosted.url.v1 / memories.hosted.bearer.v1 pair is imported only if that mode has no new profile. An exact https://memories.ivjn.us URL, optionally with a trailing slash, belongs to SaaS; other URLs belong to Center. The legacy pair is removed after migration. SaaS will not reconnect a saved token whose URL points elsewhere.

Opening a hosted mode restores its saved connection when available. After backgrounding, the current page requires Reconnect saved session or a new login. Switching never migrates library content, changes server membership or revokes a server-issued token. See mobile usage for the feature comparison and connection troubleshooting.

Client CLI defaults

Separate from config.toml, the CLI stores optional non-secret command defaults in defaults.json under the Memories home (storage_dir / MEMORIES_HOME / --home):

memories default set KEY VALUE
memories default get [KEY]
memories default delete KEY

Keys: persona, vault, type, category, daemon, daemon_relay, daemon_room. These are never vault secrets; do not put passwords or MCP grant tokens here.