Repository navigation
Storage and Migrations
mnemo stores memory locally in ~/.mnemo/memory.db using SQLite and FTS5. The embedded controller is the normal reader and sole writer for agent events and memory commands; publishers and MCP processes do not open the database. ~/.mnemo/events/ contains the controller's JetStream data, and each activated project has its own .mnemo marker containing the canonical project ID.
Observations hold decisions, bug fixes, discoveries and other memories. Sessions bind those observations to an agent execution. Review records track stale, reviewed and superseded memories. FTS5 indexes support local search.
The schema snapshot is database/target_schema.sql; incremental migrations live in database/migrations/; sqlc queries live in internal/db/queries/. Existing migrations are immutable. The controller applies safe pending migrations when it opens the store. An inconsistent or future database is rejected rather than repaired silently.
For diagnostics, mnemo doctor and mnemo db migrate --check inspect schema state without applying changes. mnemo db migrate is an explicit maintenance operation and must not run while the controller owns the database. Back up memory.db before manual repair or import. See the repository's migration maintainer guide for the development workflow.
The project ID is the id in .mnemo, never a hash of a path. directory describes the session workspace but is not project identity. The controller derives an execution key from project ID, agent and native execution ID; callers never invent a mnemo session ID.