A local AI assistant is about where your context lives, not where your model runs

Most guides to local AI assistants conflate two very different things: where the model weights run (the inference layer) and where your personal data lives (the context layer). Fazm treats them as independent. The model that writes the chain of tool calls can be whichever one is best today, but the context the model reads from is a SQLite file on your disk at ~/Library/Application Support/Fazm/users/{userId}/fazm.db. Your file index, your conversation history, your knowledge graph, your onboarding notes, and your user profile never get uploaded to a vendor vector store. The agent queries them in place with SELECT statements. That separation is the part of 'local' that actually affects your privacy and your latency.

The path is ~/Library/Application Support/Fazm/users/{userId}/fazm.db, built in Desktop/Sources/AppDatabase.swift by a function called userBaseDirectory (lines 238 to 248). The file is opened as a GRDB DatabasePool with WAL mode enabled, which is why you also see fazm.db-wal and fazm.db-shm sidecar files next to it. A per-user flag file called .fazm_running tracks unclean shutdowns so the next launch can run an integrity check if the previous session did not mark a clean shutdown. No other process touches the file; the Mac app itself is the only writer.

Seven tables matter for day-to-day context. indexed_files stores metadata for every file the scanner visits under ~/Downloads, ~/Documents, ~/Desktop, ~/Developer, ~/Projects, ~/Code, ~/src, ~/repos, ~/Sites, and /Applications, up to depth 3, skipping files larger than 500 MB and about twenty common build folders like node_modules, .git, __pycache__, DerivedData, and target. local_kg_nodes and local_kg_edges hold a personal knowledge graph (concept nodes, typed edges, source file ids). chat_messages stores every conversation with the assistant, with chat_messages_fts shadowing it as an FTS5 virtual table so full-text search is O(log n) instead of a full scan. observer_activity tracks background insight cards and auto-drafted skills. ai_user_profiles is a writable profile the agent updates on its own. Each table has a short description in ChatPrompts.swift that the model reads at query time so it can write correct SQL.

No. There is one tool called execute_sql, defined in Desktop/Sources/Providers/ChatToolExecutor.swift, that accepts a raw SQL string. The tool is restricted to SELECT, INSERT, UPDATE, and DELETE (anything else returns 'only SELECT, INSERT, UPDATE, DELETE statements are allowed'). If the SELECT query has no LIMIT clause, the executor auto-appends LIMIT 200 to prevent the model from pulling half your disk into its context window. Results come back as a plain text table with ' | ' separators, truncated at 500 characters per cell. That simplicity is deliberate: it means the model talks to your data the same way a human would in a psql prompt, and you can read what it did by tailing the app log.

Those are inference runtimes. They give you a chat UI and a local model. They do not know anything about your files, your calendar, or what you were doing in Finder an hour ago, and they cannot do anything in an app on your Mac. Fazm is the other half of the stack: it keeps your context on your Mac in one SQL-queryable file and drives the apps that already have that context open. You can point Fazm at a cloud model or, in principle, at a local model over the same agent loop; the on-disk layout does not change. The usual 'local vs cloud' framing treats these as competitors; in practice they solve different problems.

Because the agent can write the query. Vector databases are excellent when the consumer of the data is another program running similarity search; they are awkward when the consumer is a language model that can write exact SQL. A single SQLite file works with the same mental model the model already has from reading millions of lines of application code, supports full-text search via the FTS5 module for free (see the chat_messages_fts virtual table and its three triggers in the fazmV5 migration), runs offline with zero setup, lives on one disk, and can be backed up with cp. Embedding search is still available where it helps, but flat SQL is the default because it is the most reliable way to ask a precise question about your own stuff.

The opposite. Retrieval-augmented chatbots spend most of their time turning your question into an embedding, comparing it against a remote index, and streaming back the top k chunks. Fazm just runs a SELECT on a local file. For a question like 'show me my Swift projects,' the path is: execute_sql → SELECT fileExtension, COUNT(*) FROM indexed_files WHERE fileType = 'code' GROUP BY fileExtension ORDER BY count DESC → text table back. That entire round trip is a single function call on local storage, not a network round trip to a vector service.

The executor allows writes but logs every one (see the log line 'Tool execute_sql write: \(changes) row(s) affected' at line 330 of ChatToolExecutor.swift), and the tables the model is encouraged to write to are narrow: ai_user_profiles for profile updates, and the knowledge graph via a separate save_knowledge_graph tool that batches nodes and edges into a single transaction. The core chat_messages and indexed_files tables are read almost exclusively. The guardrail is that the model knows what the table is for (every table has a human-readable description attached to the prompt) and that the tool name makes the operation legible in the tool-call log. There is no silent 'clear memory' path.

There is an actor called FileIndexerService in Desktop/Sources/FileIndexing/FileIndexerService.swift. On boot and on an incremental schedule, it walks a fixed list of folders (~/Downloads, ~/Documents, ~/Desktop, ~/Developer, ~/Projects, ~/Code, ~/src, ~/repos, ~/Sites, /Applications, and ~/Applications), up to a max depth of 3, batching 500 records at a time into indexed_files. It skips folders like .Trash, node_modules, .git, .venv, DerivedData, and target because scanning those produces mostly noise. Package extensions like .app, .framework, .xcodeproj, and .xcworkspace are treated as leaves, not walked into. It skips files larger than 500 MB. The scanner does not read file contents; it only stores metadata (path, name, extension, size, folder, depth, timestamps).

The SQLite file never leaves. The accessibility tree the agent reads from other apps (from the macos-use MCP server) never leaves as bulk data. What leaves is exactly what the model needs to decide the next action: the current question, whatever rows came back from your execute_sql call, and whatever part of the AX tree the agent chose to quote. That is a fundamentally different shape from cloud assistants that index your Drive, your Gmail, or your calendar into their own vector store and keep a shadow copy. Here the shadow copy is the SQLite file, and it is in your home directory, owned by you.

Yes. Open Terminal, run sqlite3 ~/Library/Application\ Support/Fazm/users/{userId}/fazm.db, then .tables to see the list, and e.g. SELECT fileType, COUNT(*) FROM indexed_files GROUP BY fileType to see what it knows about your disk. If you want to export it, .dump or .backup work. Quit the Fazm app first so the WAL is checkpointed cleanly. The schema is identical to what the agent sees, which is the whole point: the assistant has no private view of your data.

When you sign in, the Firebase UID becomes the directory name. Before sign-in, Fazm writes to the subdirectory 'anonymous'. A migration step in AppDatabase.swift (migrateFromLegacyUserDirectory) moves the legacy anonymous or device-UUID database into the correct per-user folder once you authenticate, so your indexed files and conversation history follow the account rather than the device session. If you switch users on the same machine, the code calls switchUser(to:), which closes the pool, reconfigures for the new userId, and reopens a fresh database file.