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:

| AGENTS.md | Sub-agent configurations | | TOOLS.md | Tool usage notes and preferences | | HEARTBEAT.md | Heartbeat schedule configuration | | BOOTSTRAP.md | Initial setup instructions | | memory/YYYY-MM-DD.md | Auto-generated daily conversation summaries |

SOUL.md — Your System Prompt

The most important file. SOUL.md is injected as the system prompt (the system role in the API call) on every single conversation turn. This means 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 — Sub-Agent Definitions

Configure specialized sub-agents that the main agent can spawn for specific tasks. Each sub-agent can have its own system prompt, model, and tool restrictions.

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 — Scheduled Tasks

Configure the agent's heartbeat — periodic tasks that run on a schedule. The morning briefing, automated checks, and recurring workflows are defined here.

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

Auto-generated at the end of each day with activity. Contains a summary of conversations, decisions made, and action items. Builds 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 Workspace 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. Through conversation: Tell the agent "add to your rules: always use dark mode in code examples" and it will update SOUL.md

Changes take effect immediately — no restart needed. SOUL.md content is included in every conversation as the system prompt.

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. Generates daily summaries of what was discussed

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.

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 Workspace 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 5,000-6,000 input tokens before you type anything. As the conversation grows, previous messages accumulate. Foxl uses automatic context compaction — when the conversation approaches the context window limit, older messages are summarized to free up space.

Tips for managing token usage

• Keep SOUL.md concise — every extra line costs input tokens on every turn
• Use the Minimal tool profile (Settings > Tools) if you don't need all 21 tools (~800 tokens instead of ~4,200)
• Long conversations cost more per turn because history accumulates
• Prompt caching reduces repeat costs — Foxl enables this automatically

Memory and Credits

Memory save and recall are local operations — writing to SQLite or markdown files does not call the LLM and costs zero credits. 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 consumed per turn.

Daily Summaries

At the end of each day with activity, Foxl generates a summary file (memory/YYYY-MM-DD.md) capturing key topics, decisions, and action items from your conversations. These build up into a searchable journal of your interactions.