Workspace

The workspace is a folder of markdown files that serve as the agent's persistent knowledge base. Unlike the SQLite database (structured key-value memory), workspace files are human-readable documents you can browse and edit directly.

Workspace Structure复制锚点链接

~/.foxl/workspace/
  SOUL.md                       # Agent personality and behavior rules
  USER.md                       # Information about you
  MEMORY.md                     # General knowledge and notes
  AGENTS.md                     # How the main agent coordinates helpers
  TOOLS.md                      # Tool usage notes and preferences
  HEARTBEAT.md                  # The Feed Generator heartbeat's settings and prompt
  BOOTSTRAP.md                  # Initial setup instructions
  memory/
    2026-03-15.md               # The day's journal
    2026-03-16.md               # The day's journal
    sessions/                   # Session records
    topics/                     # Topic files listed in MEMORY.md
    ...

Core Files复制锚点链接

A new workspace's USER.md records your language (for example "Language: Korean"), taken from the language the app starts in; an existing USER.md is not changed. Settings > Personality has two plain boxes, How should Foxl answer? and What should Foxl know about you?, which are written into SOUL.md and USER.md (the "About you" section first-run setup made); the rest of each file is left as it is, and if that part changed somewhere else since you opened it, Foxl asks you to reload instead of overwriting it. On a phone they are under Your Foxl > How Foxl responds, while your computer is connected.

For detailed descriptions of each file - including how to customize SOUL.md as your system prompt and what to put in USER.md - see the Memory guide. Settings > Memory lists MEMORY.md and everything in memory/, searchable, with delete.

AGENTS.md is also at ~/.foxl/AGENTS.md复制锚点链接

AGENTS.md is a file name other agent tools use too, so Foxl also links it at the top of its own folder, where a script or tool you point at ~/.foxl finds it. Foxl does not hand the file to the coding agents it starts; a tool sees it only if it reads that path itself:

~/.foxl/AGENTS.md  ->  ~/.foxl/workspace/AGENTS.md

Both paths are the same file, so reading either one gives you the same bytes and there is no copy to keep in sync. The link is created the first time the Foxl app starts and re-checked on every launch, so deleting it is not permanent.

A few details worth knowing:

• The real file is the one in workspace/. That is what the Files page edits and what the agent reads; the home-directory entry points at it. On macOS and Linux you can edit through either path.
• On Windows, prefer editing ~/.foxl/workspace/AGENTS.md. The link needs symlink permission there - either an elevated app or Developer Mode (Settings > System > For developers, called Settings > System > Advanced on Windows 11 25H2 and later). Without it Foxl uses a hard link instead, and a hard link is joined by the file's identity rather than by its path: most editors save by writing a new file and renaming it over the old one, which separates the two copies. Editing the workspace path avoids the question entirely. If neither a symlink nor a hard link is possible, Foxl logs why and the workspace copy is simply the one place to edit.
• If the two ever do come apart on Windows, Foxl notices at the next launch and usually fixes it by itself. Where the two copies still hold the same text it re-links them silently. Where only one of them holds your writing and the other is still the starter text Foxl wrote, it re-links onto yours - which is what happens when you edit the workspace copy, the path this page recommends. Only when both copies hold real and different text does it change neither and say so, since either choice would discard something you wrote; make the two agree and the next launch re-links them.
• If you already wrote ~/.foxl/AGENTS.md yourself, Foxl moves your content into the workspace and links the two, so nothing is lost. The same is true the other way round: if the writing is in the workspace copy and the home file is still the starter text, the link is made onto your writing. If both files hold real and different content, Foxl changes neither and logs that it left them alone - merge them by hand and the link appears on the next launch.
• Running Foxl from source (a dev checkout) uses ./data/workspace instead of ~/.foxl/workspace, and deliberately creates no link - a link in your real home directory pointing into a git checkout would break as soon as the checkout moved.

Browsing the Workspace复制锚点链接

From the Dashboard复制锚点链接

Open the Files page in the sidebar to browse all files in a web-based editor. You can read and edit files directly.

The page opens with a title and a line saying what it holds, and search is always visible at the top of the list with its result count inside it. An open pane with nothing selected shows a centred prompt to pick a file.

On a phone (the iPhone and Android apps, and app.foxl.ai in a phone's browser), Files is a folder browser: one folder per screen, with its name and how many items it holds at the top. Tap a folder to open it; Back (the link under the top bar, a swipe from the left edge in the iPhone app, Android's Back button or the browser's) goes up again. The "..." menu shows the folder as a list or as icons, sorts by name, kind, date or size, groups by kind or date, and makes a new folder or file; the view is remembered for each folder on that device. Press and hold a file or folder for its menu: open, share, ask the agent, rename, duplicate, copy, cut, paste, copy path and delete. Search looks in the folder you are in, or everywhere: by name for any kind of file, and inside your notes. At the top, Recently changed lists up to five of the files most recently changed in your workspace, newest first, while your computer is connected; it leaves out the agent's own memory notes and shared files, and tapping its heading folds it away. A file opens on the document, with its name as the title: a Markdown file shows formatted, and Edit (which becomes Done) switches to the editor, with Save beside it once there are changes. Pull down on the folder list to refresh it; there is no Refresh button in the header on a phone (VoiceOver and TalkBack still find one). The iPad and the desktop app keep the file tree and the Refresh button, which also picks up a file you just saved from another app, such as Finder or an editor.

An .html file opens in a sandboxed preview. It cannot reach your account, and a page that keeps data in localStorage or sessionStorage (a game's best score, a remembered setting) runs, with storage that lasts only while the preview is open, so a saved score resets when the preview reloads. A page that needs IndexedDB or cookies still cannot use them in the preview.

Right-click a file or folder for Copy, Cut, Paste, Rename, New folder, Delete and Open in Finder (Show in File Explorer on Windows, Open containing folder on Linux; Download and Share on the web and phone apps, plus Copy path). Delete asks first and cannot be undone. Drag a row onto a folder to move it, and hold Option (Alt) while dropping to copy instead. In the desktop app, drop files from your computer onto the tree to add them; on app.foxl.ai and the phone that is refused with "Add them in Foxl on your computer". The Shared folder, on an account that has one, still takes uploads there.

Foxl Code's Files page is a different surface: four shelves beside Shared - Tasks (the checkout a coding agent edited, per task), Computer (a task that ran on your own machine, plus the local checkouts chat reads and writes), Storage (your private cloud files) and Session (what the chat brain itself wrote) - each loaded only when you open it. Only its Shared shelf is the panel described here.

The Shared folder复制锚点链接

Signed in, the tree has a Shared folder (on a Free account your own holds up to 5 GB, and a workspace a Free account owns stores none). It is not on your disk: shared documents and files are stored by the Foxl relay and every member of the workspace sees them, from the desktop, the web app and the phone. New shared file creates a markdown document at a path you type (runbooks/oncall.md builds the folders). Selecting the Shared folder itself opens the files panel: upload files up to 50 MB each (or drop them on Shared; a large drop reloads the list once, when it is done), download or delete them, and read the storage usage at the top before you add more. Previewing a shared .html file shows the shared file alone: images and stylesheets it refers to by a relative path are listed above the preview as not loaded, rather than taken from files of the same name on your computer. A folder is visible to everyone in the workspace unless a workspace admin restricts it to named people with view or edit access (right-click the folder, Sharing). A restricted folder is open only to the people on that list and to the workspace's admins; whoever created it has no access of their own, so add them to the list if they need it. Turning a restricted folder back to everyone in the workspace clears its list, so restricting it again starts from an empty list with you on it. Search on this page covers your local files and the shared documents together.

From the Filesystem复制锚点链接

Open any workspace file with your preferred text editor:

# macOS / Linux
code ~/.foxl/workspace/USER.md    # VS Code
nano ~/.foxl/workspace/SOUL.md    # Terminal
open ~/.foxl/workspace/           # Finder

# Windows (PowerShell)
code $env:USERPROFILE\.foxl\workspace\USER.md
explorer $env:USERPROFILE\.foxl\workspace

Through Conversation复制锚点链接

Ask the agent about its workspace:

• "What's in your SOUL.md?"
• "Show me my USER.md"
• "What did we discuss yesterday?" (reads daily journal)

Workspace Tools复制锚点链接

The agent uses these tools to interact with the workspace:

Privacy复制锚点链接

Your workspace files are stored on your computer, not on Foxl's servers. The core files - SOUL.md, USER.md (without its identity, address and similar sections), MEMORY.md (without its long reference sections), and TOOLS.md, AGENTS.md and HEARTBEAT.md once they hold more than the starter text - are part of the instructions sent with each request to the model provider you chose, straight from your computer. So are BOOTSTRAP.md's first-run notes while setup is not finished, and the titles and topics of your most recent conversations (no message text). With Save memories off, USER.md, MEMORY.md, the first-run notes and those titles are left out. Any other file reaches the provider only when the agent reads it into the conversation. With a local model, nothing leaves the computer.

Two exceptions involve Foxl's servers:

• The Shared folder: anything you put there is stored by the Foxl relay for your workspace, because the people it is shared with cannot reach your machine.
• Use my computer's memory for remote chat (on the accounts remote chat is offered to, off by default): your phone or browser keeps a copy of SOUL.md, USER.md, MEMORY.md and AGENTS.md, cut the same way, and sends it with each cloud message through the relay to Amazon Bedrock. It is not saved on Foxl's servers. See Security.