# File layout

> Everything Flowly stores lives under ~/.flowly. This is the map — config, workspace, memory, skills, credentials, and the SQLite databases — useful for backups, debugging, and self-hosting.

Source: https://useflowlyapp.com/en/docs/reference/file-layout
Language: en

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](https://useflowlyapp.com/en/docs/features/plugins). |
| `cron/` | Scheduled-job data. |
| `plan-mode/` | [Plan mode](https://useflowlyapp.com/en/docs/features/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](https://useflowlyapp.com/en/docs/features/audit-log). |
| `sessions/` | Session routing index and transcripts. |
| `goals/` | Durable [standing goal](https://useflowlyapp.com/en/docs/features/goals) 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](https://useflowlyapp.com/en/docs/using-flowly/workspace) injected every turn. |
| `memory/MEMORY.md` | Human-readable curated [memory](https://useflowlyapp.com/en/docs/features/memory). |
| `memory/YYYY-MM-DD.md` | Daily notes. |
| `skills/` | Built-in + installed + agent-created [skills](https://useflowlyapp.com/en/docs/features/skills). |
| `personas/` | [Persona](https://useflowlyapp.com/en/docs/using-flowly/personas) 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](https://useflowlyapp.com/en/docs/features/knowledge-graph) (triples). |
| `memory_index.sqlite` | Hybrid search index (embeddings + FTS). |
| `board.db` | The cross-channel task [board](https://useflowlyapp.com/en/docs/features/board). |
| `artifacts.sqlite` | Version-tracked [artifacts](https://useflowlyapp.com/en/docs/features/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](https://useflowlyapp.com/en/docs/features/mcp) and
[Remote MCP setup](https://useflowlyapp.com/en/docs/using-flowly/remote-mcp).

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

> [!TIP]
> Use `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.