Memory

Foxl has a persistent memory system that learns about you over time. The more you use it, the better it understands your preferences, workflows, and context.

Two Types of Memory

Database Memory (SQLite)

Key-value pairs stored in SQLite with tags for organization. Used for structured data that the agent needs to recall quickly.

• memory_save: Store a piece of information with a key and optional tags
• memory_recall: Search memory by key, value content, or tags

Workspace Memory (Markdown Files)

Human-readable markdown files stored in your workspace directory. These are the heart of Foxl's personalization:

SOUL.md - Your System Prompt

The most important file. SOUL.md is loaded into the system prompt on every single conversation turn, ahead of the core of USER.md and the smaller sections of MEMORY.md, so the model reads it before every response. Use it to define:

• Communication style: "Be concise", "Respond in Korean when I write in Korean", "Never use emojis"
• Technical preferences: "Use TypeScript", "Prefer pnpm over npm", "Always use functional components"
• Behavior rules: "Always check git status before committing", "Ask before deleting files"
• Domain context: "I work on a SaaS product", "My stack is Next.js + PostgreSQL"

The agent follows these instructions in every conversation. Changes take effect immediately.

USER.md - About You

The agent writes and updates this file as it learns about you. Contains:

• Your name, role, and timezone
• Work context and current projects
• Communication preferences (formal/casual, language)
• Technical skill level and areas of expertise

You can edit this directly or tell the agent: "I'm a backend engineer who prefers Go."

MEMORY.md - Knowledge Base

A general-purpose notes file where the agent stores information it wants to remember:

• Project decisions and rationale
• API keys and service configurations (non-sensitive)
• Frequently referenced facts
• Meeting notes and action items

AGENTS.md - Coordinating helpers

Notes for how the main agent should coordinate helpers, loaded into the system prompt when it holds more than the default text. The same file is reachable at ~/.foxl/AGENTS.md, the path other agent tools read, so a coding CLI pointed at your home folder sees the same instructions. The subagents themselves - each with its own prompt, model and tools - are defined on the Agents page; see Subagents.

TOOLS.md - Tool Preferences

Notes about how the agent should use its tools. For example: "When using the browser tool, always use Chrome", "Prefer code_search over grep for large repos."

HEARTBEAT.md - The heartbeat's brief

Configuration for the Feed Generator heartbeat: whether it is enabled, how often it runs, its active hours and the watch block naming what it should keep an eye on, followed by the prompt it runs with. Schedules do not live here - cron schedules and webhooks are created on the Schedules page (see Scheduling), and the Morning Briefing has its own page.

BOOTSTRAP.md - First Run Setup

Instructions that run when Foxl starts for the first time in a new workspace. Use it to set up project-specific context, install dependencies, or configure tools.

memory/YYYY-MM-DD.md - Daily Journals

Written as you go rather than at midnight. After each turn Foxl appends the first lines of what you said and what it answered (and which tools it used), and when a session ends it adds a short summary. Every entry is tagged with the conversation it came from, so deleting a chat also removes its lines here. Together the files build into a searchable history of your interactions.

Customizing Your Agent with SOUL.md

SOUL.md is the most powerful customization file - it defines your agent's personality, behavior rules, and system prompt. Think of it as the "character sheet" for your AI.

What to Put in SOUL.md

# My Foxl Agent

## Personality
- Respond concisely and directly
- Use Korean when I write in Korean, English when I write in English
- Never use emojis unless I ask

## Rules
- Always check git status before committing
- Prefer TypeScript over JavaScript
- Use pnpm, not npm

## Context
- I'm a full-stack developer working on a SaaS product
- My stack: Next.js, PostgreSQL, Tailwind CSS
- My timezone: KST (UTC+9)

How to Edit SOUL.md

1. From the app: Go to Files in the sidebar, click SOUL.md, and edit directly
2. From the terminal: Open ~/.foxl/workspace/SOUL.md (production) or ./data/workspace/SOUL.md (dev) in any text editor
3. Not through conversation: the agent's memory tool treats SOUL.md, HEARTBEAT.md and AGENTS.md as configuration rather than memory - they are loaded into every system prompt - so telling it "add to your rules: always use dark mode in code examples" is refused, with a message that SOUL.md is edited on the Workspace page. Ask it to remember a preference instead and it saves to USER.md or MEMORY.md, a write that asks first unless auto-approve is on.

Changes take effect immediately - no restart needed. SOUL.md is part of the system prompt on every turn.

How Memory Works

The agent automatically:

1. Saves important information from conversations (your preferences, decisions, context)
2. Recalls relevant memories when they apply to the current conversation
3. Keeps the day's log as you go, and summarizes a session when it ends

You don't need to tell Foxl to remember things - it does this naturally. But you can also explicitly ask it to remember or forget specific information.

Your Foxl Notes assistant threads are saved where the agent can search them too, so "what did I say about this last week" finds the meeting you said it in, from Notes or from chat. Meeting threads stay out of your chat list; they are reachable only by search.

Privacy and Transparency

• Location: ~/.foxl/workspace/ (macOS/Linux) or %USERPROFILE%\.foxl\workspace\ (Windows)
• Format: Standard markdown - open with any text editor
• No cloud sync: Memory never leaves your machine
• No black box: Every piece of stored knowledge is visible and editable

Viewing and Editing Memory

You can browse and edit all memory files from the Files page in the sidebar, from the filesystem, or through conversation ("What do you know about me?"). See Workspace for details on browsing, editing, and file locations.

Context Window and Token Impact

Every conversation turn, the following is sent to the model as input tokens:

This means a fresh conversation starts at roughly 6,000-7,000 input tokens before you type anything. As the conversation grows, previous messages accumulate. Foxl uses automatic context compaction: when the conversation reaches about 70% of the model's window, the oldest part is summarized and the recent messages are kept, so a long session no longer hits the limit mid-turn and silently loses its history. Each compaction is written to the log with the message count before and after.

Tips for managing token usage

• Keep SOUL.md concise - every extra line costs input tokens on every turn
• Switch to the Minimal tool profile on the System tab of Settings > Connect > Integrations if you don't need every tool (9 tools, ~1,800 tokens instead of ~4,800). See Tool Profiles
• Long conversations cost more per turn because history accumulates
• Prompt caching reduces repeat costs - Foxl turns it on automatically for Claude on Bedrock and, since v0.6.25, on your own Anthropic key too, so the unchanging front of each request (system prompt and tool definitions) is billed at the cache-read rate rather than sent again at full price

Memory and cost

Memory save and recall are local operations - writing to SQLite or markdown files does not call the model and costs nothing. However, when the agent reads memory content back into the conversation, that content becomes part of the input tokens sent to the model. More stored memory means more tokens per turn, on whichever provider you connected.

Daily Summaries

Each day with activity gets a memory/YYYY-MM-DD.md file, filled in turn by turn and closed out with a session summary, as described above. These build up into a searchable journal of your interactions.