Memory & Skills

Agents have persistent storage in their workspace directory that survives across conversations and restarts. This is split into two systems: memory for freeform knowledge and skills for structured capabilities.

Workspace layout

workspace/
├── memory/
│   ├── MEMORY.md          # Long-term memory
│   └── 2026-02-23.md      # Daily notes (date-stamped)
├── skills/
│   └── my-skill/
│       └── SKILL.md       # Skill definition
├── images/                # Generated images
├── HEARTBEAT.md           # Periodic task instructions (optional)
└── ...                    # Any other files the agent creates

The workspace path defaults to /opt/baal-agent/workspace and is configured via the WORKSPACE_PATH environment variable.

Memory system

The agent’s memory is file-based. The agent can read and write memory files using its standard file tools (read_file, write_file, edit_file). Memory content is automatically loaded into the system prompt context on every turn.

Long-term memory

workspace/memory/MEMORY.md stores persistent knowledge that the agent should always have access to: user preferences, project context, important facts, and recurring patterns.

The agent is instructed (via its system prompt) to save important information here. For example, if a user says “I prefer Python over JavaScript,” the agent might append that to MEMORY.md so it remembers in future conversations.

Daily notes

workspace/memory/YYYY-MM-DD.md files hold session-specific notes tied to a particular day. These are useful for tracking ongoing work, temporary context, and daily task lists.

Only today’s daily notes are loaded into context. Older daily notes remain on disk and can be read on demand, but are not injected automatically.

How memory is loaded

On each conversation turn, the context builder reads:

1. memory/MEMORY.md — included under a “Long-term Memory” heading
2. memory/<today>.md — included under a “Today’s Notes” heading

Both are injected as dynamic context near the end of the message list (just before the latest user message) to preserve KV cache efficiency. See Context & Compaction for details.

Skills system

Skills are structured capability definitions that teach the agent how to perform specific tasks. Each skill lives in its own directory under workspace/skills/.

Skill format

workspace/skills/my-skill/
└── SKILL.md

A SKILL.md file can use either format:

Frontmatter format (recommended):

---
name: "Data Analysis"
description: "Analyze CSV data and generate charts"
---

## Instructions

When asked to analyze data:
1. Read the CSV file
2. Identify key metrics
3. Generate a summary with charts
...

Legacy format (heading + first paragraph):

# Data Analysis

Analyze CSV data and generate charts.

## Instructions
...

How skills are loaded

The context builder scans workspace/skills/*/SKILL.md and extracts a summary for each skill:

• From frontmatter: uses the name and description fields
• From legacy format: uses the directory name and the first non-heading paragraph

These summaries are included in the dynamic context as a bullet list:

## Available Skills

- **Data Analysis**: Analyze CSV data and generate charts (read `workspace/skills/data-analysis/SKILL.md` for details)
- **Web Scraping**: Extract structured data from websites (read `workspace/skills/web-scraping/SKILL.md` for details)

The agent sees the summary of every skill on every turn, but the full skill content is only loaded when the agent explicitly reads the SKILL.md file. This keeps the context small while making skills discoverable.

Skill directory contents

A skill directory can contain any files the agent needs — not just SKILL.md. For example, a skill might include template files, configuration snippets, or reference data. The SKILL.md file serves as the entry point.

Heartbeat

The heartbeat system allows agents to perform periodic background work. If HEARTBEAT_INTERVAL is set to a value greater than 0 (default: 1800 seconds / 30 minutes), the agent checks workspace/HEARTBEAT.md at that interval.

If the file contains actionable content (non-empty, non-comment lines or unchecked checkboxes), the agent runs a turn to process the instructions. Results are delivered to the owner as pending messages.

The heartbeat file supports:

• Plain text instructions
• Markdown task lists (- [ ] task for pending, - [x] task for completed)
• Comments (<!-- ... -->) and headings are ignored when checking for actionable content