Operations

Memory Layer is local-first, but it still has operational concerns: service health, database availability, backups, logs, privacy, and upgrade safety.

Daily commands

memory health                          # backend service
memory doctor                          # config and dependencies
memory status --project <project-slug> # combined service, watcher, MCP, doctor

Operations checklist

Before making changes to a running instance:

Know which service instance you are operating.
Check database connectivity before blaming retrieval.
Back up state before upgrades or migrations.
Redact secrets before sharing logs.
Confirm agent and MCP integrations are scoped to the intended project.

Service

The service runs as a systemd unit on Linux or a launchd agent on macOS. Use standard OS tools to start, stop, and inspect it. See Service setup for initial configuration.

Task	Command
Run in foreground for debugging	`memory service run`
Enable packaged background service	`memory service enable`
Inspect configured service	`memory service status`
Restart known service components	`memory service restart-all`
Regenerate or confirm API token	`memory service ensure-api-token`

The foreground run command is intentionally blocking. If it exits, the service is not running from that terminal.

Database

Memory Layer stores everything in PostgreSQL with pgvector. See PostgreSQL and pgvector for setup.

Backups and restore

What to back up

PostgreSQL database.
Global configuration.
Repo-local .mem/ project config.
.agents/ integration files if they are part of the project workflow.

Basic database backup

pg_dump "$DATABASE_URL" > memory-layer-backup.sql
psql "$DATABASE_URL" < memory-layer-backup.sql

For production-grade backups, prefer custom-format dumps, checksums, restore tests, and a retention policy. Verify a restore by running memory doctor against a disposable database.

Do not commit secrets, API keys, local database URLs, or runtime state.

Upgrades

Before upgrading:

memory status --project <project-slug>
memory doctor
pg_dump "$DATABASE_URL" > memory-layer-before-upgrade.sql

After upgrading:

memory service restart-all
memory doctor
memory health
memory status --project <project-slug>
memory upgrade --dry-run

Run memory upgrade inside repositories only after reviewing the dry run, because it can refresh .agents/ and other repo-local integration files.

Logs and diagnostics

Surface	Use it for
`memory doctor`	Configuration, database, provider, and environment checks.
`memory status --project <slug>`	Combined project, service, watcher, MCP, and health view.
TUI Errors tab	Persisted diagnostics with fix hints and raw errors.
Browser UI Errors tab	Same diagnostic model in a browser surface.
OS service logs	Startup failures, migrations, port conflicts, crashes.

Redact provider tokens, database URLs, prompts, and local file paths before sharing logs publicly.

Security and privacy

Memory Layer can be local-first, but external embedding or LLM providers may receive text depending on your configuration.

Check before enabling integrations

Which database stores project memory?
Which LLM provider is configured?
Which embedding provider is active?
Is MCP HTTP local and token-protected?
What does the watcher capture?
Are logs redacted before sharing?

Do not expose the MCP HTTP server to the public internet unless you have added an authentication and network control layer.

Multi-project use

One backend serves multiple projects. Each project has its own slug, config, watchers, and scoped queries. Use memory status --project <slug> to inspect each one independently.

The Browser UI is served by the same local service. Use it when you need a wider inspection surface for memories, query evidence, activities, review proposals, errors, embeddings, and resume briefings.

Keep the service bound to local interfaces unless you have added an explicit authentication and network control layer.

Read Reference, Troubleshooting, or MCP.