4.4. Workspace & Memory¶

Each squad has a dedicated workspace directory and a per-agent memory system that enables context retention and knowledge sharing across tasks.

Workspace¶

The workspace is a directory on your filesystem that the squad owns. It stores plans, task outputs, agent files, and metadata.

Workspace Structure¶

When a squad is created, the workspace is initialized with a structured layout:

my-squad-workspace/
├── .squad-config.json    # Squad manifest (for restore)
├── plans/                # Generated plans
├── tasks/                # Task outputs and artifacts
├── agents/               # Per-agent files
│   ├── planner/
│   │   └── memory.md     # Planner's memory file
│   ├── developer/
│   │   └── memory.md     # Developer's memory file
│   └── reviewer/
│       └── memory.md     # Reviewer's memory file
└── logs/                 # Execution logs

Browsing Files¶

The Workspace Explorer lets you browse the workspace directory tree directly in the app:

• Navigate the file tree with expand/collapse
• Preview text, Markdown, and JSON files inline
• View file sizes and modification timestamps
• Monitor total workspace size and file count

Searching Files¶

Use workspace search to find content across all files in the workspace. This performs full-text search and returns matching files with highlighted results.

Workspace Health¶

The monitoring dashboard displays workspace health metrics:

Memory¶

Each agent in a squad can have a persistent memory file — a Markdown document organized into sections that the agent reads at the start of each task and can update during execution.

How Memory Works¶

1. When an agent starts a task, its memory file is loaded into context
2. During execution, the agent can write new observations, decisions, or learned patterns to memory
3. The updated memory persists across tasks, building a knowledge base over time

Memory Sections¶

Memory files are organized into named sections:

# Project Context
This project uses React with TypeScript and Zustand for state management.

# Coding Conventions
- Use functional components with hooks
- Follow BEM naming for CSS classes
- All API calls go through src/lib/api.ts

# Decisions Made
- Chose JWT for authentication (Task #3)
- Database schema uses snake_case column names (Task #5)

Agents can read, append to, or replace individual sections without affecting the rest of the memory file.

Cross-Agent Memory Search¶

The Memory Search feature lets you search across all agents' memory files simultaneously:

• Enter a search query to find matching content
• Filter by specific agents or memory sections
• Toggle case-sensitive matching
• View context lines around each match for better understanding

This is useful for finding decisions, conventions, or knowledge that a specific agent recorded during a previous task.

When to Enable Memory¶