4.6. 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. After every N conversation turns (controlled by the extraction trigger interval), the app automatically extracts insights from the recent chat and appends them to the agent's workspace bank under an Insights section — no tool calls needed
4. The updated memory persists across tasks, building a knowledge base over time

Automatic Extraction¶

When memory_enabled is set for an agent, the backend runs an LLM extraction pass after every trigger_interval turns. Each extracted fact is classified as either project-scoped (Layer B) or experiential (Layer A) in the same LLM pass, then dual-routed to the appropriate sink. This is a fire-and-forget background operation: it does not block the chat response.

Extraction is skipped when the router is not running or the agent has fewer messages than the configured trigger interval.

Layer B: Project-Scoped Memory¶

Project-scoped facts land in the agent's workspace memory bank ({workspace}/memory/{agent}.md) under the Insights section. These are facts that only make sense inside the current project — file layouts, in-progress decisions, project-local conventions. They do not follow the agent into a different squad or project.

Layer A: Experiential Memory¶

Experiential facts are durable, cross-project learnings — user preferences, reusable skills, named entities tied to the user — that travel with the agent into future squads. Each agent gets a dedicated global MemoryNamespace (visible on the Memory page) named Agent Experience: <agent name>.

The namespace identity is keyed by the agent's source profile. Two squads instantiating the same profile share one Layer-A namespace, so the agent accumulates experience across projects rather than starting fresh each time. When an agent has no source profile, the namespace falls back to a per-(squad, agent-id) key, keeping its experiential memory scoped to that squad.

Layer-A namespaces start disabled by default. The global memory injection pipeline only surfaces enabled namespaces, so an agent's experiential memory does not auto-inject into other agents' chats or the main chat until you enable it manually from the Memory page. The per-agent chat path (described below) reads Layer-A content directly by resolved key and bypasses this flag, so the agent sees its own accumulated experience on every send regardless of the toggle state.

Memory Read-Back (Phase 3)¶

Each time you send a message in an agent chat, the backend assembles a fresh system prompt that folds the agent's accumulated Layer-A and Layer-B memory into a ## Agent Memory section appended after the static squad-context header. The agent sees its own experiential memory and workspace facts on every chat turn without any manual prompt engineering.

The combined budget for the injected memory block is controlled by memory.maxTokens (configured in Settings). That budget is split 60% to Layer A and 40% to Layer B: experiential memory gets priority because the agent's cross-project identity is more reusable across turns than workspace facts that are often visible in the recent conversation already. Layer B always receives at least 1 token when the total is 2 or more, so neither layer is silently dropped.

This per-agent budget is independent of the global [Supplementary Context] block built from enabled namespaces. A chat with memory.maxTokens = 2000 may include up to 2000 tokens of global context plus up to 2000 tokens of per-agent Layer-A + Layer-B memory alongside each other.

Layer-A namespaces remain enabled: false for the global pipeline even after Phase 3. The global pipeline keeps cross-agent isolation intact; the per-agent chat path is the only route that reads a Layer-A namespace without consulting the enabled flag.

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¶