Flowly keeps all of its state in one directory: ~/.flowly/ (override with
FLOWLY_HOME; named profiles live under ~/.flowly/profiles/<name>/). Nothing is
written outside it without your involvement.
Top level
| Path | What it is |
|---|---|
config.json | Main configuration (camelCase keys). The one file you edit by hand. |
config.json.bak | Copy of the previous parseable config.json, refreshed before each save. If the active file is ever corrupted, Flowly moves it aside as config.json.broken-<timestamp> and restores from here. |
.env | Secrets / environment overrides loaded at startup. |
workspace/ | Context files, memory, skills, personas — see below. |
credentials/ | Account and OAuth tokens (e.g. account.json, gmail.json), each 0600. Used whenever the OS keychain isn't available — which includes every sandboxed run on macOS, since the sandbox hides ~/Library/Keychains. |
plugins/ | User-installed plugins. |
cron/ | Scheduled-job data. |
plan-mode/ | Plan mode state: per-session plans (<session>/plan_<id>.json plus an append-only plan_<id>.revisions.log) and sticky.json, which conversations have the standing mode on (what makes the mode survive restarts). |
audit/ | Command + decision audit log. |
sessions/ | Session routing index and transcripts. |
goals/ | Durable standing goal state — one lock + JSON record per conversation. |
assistants/ | Saved assistant / multi-agent definitions. |
desktop-client-id | Stable id Flowly Desktop reconnects with. |
Two more files appear only in certain states, and both are safe to delete:
| Path | When it appears |
|---|---|
credentials/.keychain-broken | After the OS keychain refused a write. While it exists, Flowly skips the keychain and uses the 0600 files. Clear it with flowly keychain retry once the keychain works again. |
.machine-id | In a non-default home only (a profile, or a FLOWLY_HOME you set). It gives that instance its own identity, so signing in from it registers a separate <machine>-dev server rather than taking over your main one. |
Workspace (~/.flowly/workspace/)
| Path | What it is |
|---|---|
AGENTS.md, SOUL.md, USER.md, TOOLS.md, IDENTITY.md | Context files injected every turn. |
memory/MEMORY.md | Human-readable curated memory. |
memory/YYYY-MM-DD.md | Daily notes. |
skills/ | Built-in + installed + agent-created skills. |
personas/ | Persona definitions. |
Databases
Flowly uses local SQLite files (WAL mode, so you'll also see -wal / -shm
sidecars):
| File | Holds |
|---|---|
memory_governance.sqlite3 | Memory lifecycle + audit trail (governance). |
knowledge_graph.sqlite3 | Temporal knowledge graph (triples). |
memory_index.sqlite | Hybrid search index (embeddings + FTS). |
board.db | The cross-channel task board. |
artifacts.sqlite | Version-tracked artifacts. |
| session store | Session history + full-text search. |
MCP state
Paths below are relative to the selected $FLOWLY_HOME (or named profile home).
Do not copy credentials between profiles or edit credential identifiers by hand.
| Path | What it is |
|---|---|
config.json → mcpServers | Server configuration, explicit tool permissions, and app-managed OAuth credential-slot pointers |
mcp-tokens/ | Private provider OAuth client/token records, staged credential slots, and cross-process lock files |
mcp-access.json | Scoped external-access key digests, owning conversations, tool grants, expiry and revocation state; not a recoverable list of raw keys |
cache/mcp-manifests/ | Bounded discovery hints for lazy startup; cached tools do not grant permission to execute |
mcp/conversation-events.sqlite | Restart-safe, bounded conversation event journal and cursor state, with SQLite WAL/SHM sidecars |
logs/mcp/diagnostics.jsonl | Private, sanitized MCP diagnostics and subprocess stderr, with bounded rotations |
media/mcp/ | Validated binary MCP content saved for rendering as media |
The SSH management endpoint does not create an SSH password store on the runtime. SSH credentials and host trust belong to the client; MCP provider OAuth tokens stay on the selected runtime. For backups, treat MCP configuration, tokens, access state, logs and media as sensitive. Restoring an old access-state backup can restore older authorization decisions; file restoration is outside the live key-revocation protocol. See MCP and Remote MCP setup.
Runtime / IPC files
| File | What it is |
|---|---|
gateway-api.json | Local gateway token (loopback auth). |
electron-api.json | Shared-secret handshake with Flowly Desktop (screenshots, perms). |
imessage-state.json | iMessage channel watermark/state. |
desktop-client-id | Stable id for the paired desktop client. |
The install itself (not your data)
The install script installs Flowly's code separately from your data, under
~/.local/share/flowly/:
| Path | What it is |
|---|---|
repo/ | The git checkout flowly update fast-forwards (git pull). |
venv/ | The uv-managed virtualenv Flowly runs from (editable install of repo/). |
The flowly launcher is a symlink into this venv, placed on your PATH. None of
this is your data — you don't back it up; re-running the install script (or
flowly update) reproduces it from git. A packaged uv tool / pip install
lives wherever that tool keeps it instead, and has no repo/.
Backing up
A backup is just a copy of ~/.flowly/ while the gateway is stopped — that's
your data. (Flowly's code lives elsewhere; see above.) To move to a new machine:
stop the gateway, copy the directory, and start it there. Keep config.json,
.env, and credentials/ private — they hold your keys and tokens.
FLOWLY_HOME=/path/to/dir (or -p <profile>) to run an isolated instance
without touching your real ~/.flowly — handy for testing, a second bot, or a
headless server.