Workspace

Your agent's file-based knowledge base - memory, personality, and daily journals

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                     # Sub-agent configurations
  TOOLS.md                      # Tool usage notes and preferences
  HEARTBEAT.md                  # Heartbeat schedule configuration
  BOOTSTRAP.md                  # Initial setup instructions
  memory/
    2026-03-15.md               # Daily conversation summary
    2026-03-16.md               # Daily conversation summary
    ...

Core Files

File	Purpose
SOUL.md	Agent personality, behavior rules, and system prompt. The most important customization file.
USER.md	Information about you - the agent learns and updates this over time.
MEMORY.md	General knowledge, notes, and reference material.
AGENTS.md	Sub-agent configurations.
TOOLS.md	Tool usage notes and preferences.
HEARTBEAT.md	Heartbeat schedule configuration.
BOOTSTRAP.md	Initial setup instructions for new workspaces.
memory/YYYY-MM-DD.md	Auto-generated daily conversation summaries.

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.

AGENTS.md is also at `~/.foxl/AGENTS.md`

AGENTS.md is a convention other agent tools share, and they look for it in the home directory rather than a subfolder. So Foxl links it there:

~/.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 - it used to be hidden behind an icon, which cost a click and hid the fact the tree could be filtered at all. An open pane with nothing selected shows a centred prompt to pick a file.

On a phone the search, open-folder and refresh controls are 44px glass chips matching the rest of the header - real iOS Liquid Glass that lenses the file list scrolling underneath on iOS 26, and a frosted CSS chip on Android and the web app. The desktop toolbar is unchanged.

Right-click a file or folder for Copy, Cut, Paste, Rename, New folder, Delete and Open in Finder (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, hold Option (Alt) while dropping to copy instead, and drop files from your desktop onto the tree to upload them.

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

When you are signed in and belong to a workspace, the tree gains a Shared folder. 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, download or delete them, and read the storage usage and its projected cost at the top before you add more. 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). 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:

Tool	Description
workspace_memory_save	Add content to a workspace file
workspace_memory_read	Read a workspace file
workspace_memory_search	Search across all workspace files
workspace_memory_edit	Edit sections of a workspace file

Privacy

Your workspace files are local. They are never uploaded to Foxl servers or included in API calls to AI providers (unless the agent explicitly reads them into the conversation context). The one exception is 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.

On this page