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. |
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.