Operations
Memory Layer is local-first, but it still has operational concerns: service health, database availability, backups, logs, privacy, and upgrade safety. Use this page as a runbook, not a second copy of the troubleshooting guide.
Baseline
memory health # backend service
memory doctor # config and dependencies
memory status --project <project-slug> # combined service, watcher, MCP, doctorRun these once at the start of an incident or change. After that, move to the relevant section below instead of repeating them.
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.sqlFor 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
Memory Layer v2.0.0 is a breaking upgrade from v1. Follow the v2 Update guide for removed config keys, renamed commands, API changes, package-specific install steps, migrations, and rollback. The sequence below is the shorter runbook for routine updates within a compatible release line.
Before upgrading, take a baseline and back up the database:
pg_dump "$DATABASE_URL" > memory-layer-before-upgrade.sqlAfter upgrading:
memory service restart-all
memory doctor
memory health
memory status --project <project-slug>
memory upgrade --dry-runRun 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. |
memory loops runs --project <slug> | Automation run ledger and recent loop outcomes. |
| TUI Errors tab | Persisted diagnostics with fix hints and raw errors. |
| Web 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 service or MCP HTTP route directly to the public internet. For remote multi-user access, enable Authentik mode, terminate HTTPS at a trusted reverse proxy, keep service-token clients scoped, and add network controls. HTTP MCP remains cookie-blind and needs its own service token.
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.
Web UI
The Web 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 explicitly configured Authentication and access, HTTPS, trusted proxy behavior, and network controls.
Automations
The Automations control plane is service-owned. Treat it like an operational surface: inspect settings before enabling loops, prefer dry-runs when exploring outputs, and review approval requests before accepting memory or repository changes.
Next
Read Automations, Reference, Troubleshooting, or MCP.