Core Concepts
| Term | Definition |
|---|---|
| Session | An independent, checkpointable, resumable workspace containing memories, files, tools, and sandbox. The fundamental unit of work in Maestro. |
| Turn | One complete cycle of user input, Maestro processing, tool execution, and result presentation. Sessions consist of many turns. |
| Agent | The AI entity that orchestrates models, tools, and validation to accomplish your goals within a session. |
| Capacity | The token-based limit on how much context (memories, files, tools) a session can maintain. Visible via capacity indicator in UI. |
Memory and Context
| Term | Definition |
|---|---|
| Memory | Dialog history and interaction records stored in a session. Includes user requests, agent replies, tool results, and validation outcomes. |
| Memory Compaction | Process of summarizing old dialog to reduce token usage while preserving key information. |
| Forgetting | Selective removal of turns or memory segments to free capacity and improve focus. |
| Token | Unit of text that models process. Roughly 3/4 of a word in English. Capacity and costs measured in tokens. |
| Context Window | The maximum number of tokens a model can process in one turn. Maestro manages context to stay within limits. |
Files and Storage
| Term | Definition |
|---|---|
| FileStore | The persistent storage system that maintains your session’s files with complete iteration history. |
| File Iteration | A snapshot of a file at a particular point in time. Every change creates a new iteration; history is complete. |
| File Activation | Making a file’s content visible to Maestro. Activated files consume capacity; others are indexed but not loaded. |
| Filetree | The hierarchical structure of all files in your session. Maestro can see the tree without loading all file contents. |
| Synchronized Files | Files that sync between session storage and sandbox. Includes text-based source code and certain media types. |
| Checkpoint | A point-in-time snapshot of complete session state (agent configuration and FileStore) enabling restoration. |
Tools and Capabilities
| Term | Definition |
|---|---|
| Tool | A capability Maestro invokes autonomously (e.g., View Files, Execute Command, Complex Reasoning). |
| Command | A user-invoked action (e.g., /clone, /forget, /tools) that controls session behavior or accesses utilities. |
| Proposal | A suggested code change created by Maestro using PROPOSE_NEW, PROPOSE_EDIT, or PROPOSE_OVERWRITE tags. |
| Apply Changes | The tool Maestro must use to commit all pending proposals to the codebase and sandbox. |
| Complex Coding | Advanced tool with high reasoning budget for implementing sophisticated multi-file code changes. |
| Complex Reasoning | Advanced tool for deep analytical problems requiring systematic thinking and extended reasoning. |
Sandbox
| Term | Definition |
|---|---|
| Sandbox | An isolated Ubuntu Linux execution environment where code runs, tests execute, and validation occurs. |
| Terminal Window | A named shell session within the sandbox. Multiple windows allow parallel processes and organized execution. |
| Terminal Streamer | UI component showing real-time output from sandbox terminal commands. |
| Preview URL | Public URL exposing sandbox port 8080, allowing access to web services running in sandbox. |
| Sandbox Instance | A specific sandbox configuration. Sessions can have multiple instances (default, custom resources, privileged, SSH). |
Source Control
| Term | Definition |
|---|---|
| Clone | Downloading a repository from GitHub into your session, making files immediately available to Maestro. |
| Overwrite Clone | Re-cloning an already-cloned repository to pull remote changes, creating new iterations for changed files. |
| Pull Request (PR) | A GitHub feature requesting merge of changes from feature branch to base branch. Maestro can create and update PRs. |
| Feature Branch | A git branch containing changes for a specific feature, typically merged via PR. |
| Base Branch | The target branch for a PR, usually main or develop. |
| Auto-Clone | Automatic cloning of newly created repository immediately after creation. |
Validation and Quality
| Term | Definition |
|---|---|
| Validation | Process of proving code correctness through tests, benchmarks, and analysis. Evidence-based, not assumption-based. |
| Baseline | Measurement of current system performance before optimizations, used for comparison after changes. |
| Benchmark | Systematic measurement of performance (latency, throughput, resource usage) under defined conditions. |
| Test Coverage | Percentage of code exercised by tests. Higher coverage indicates more thorough testing. |
| Regression | New bug introduced by changes, or performance degradation. Quality gates prevent regressions. |
| Edge Case | Unusual or extreme scenario that code must handle correctly. Comprehensive testing covers edge cases. |
| Quality Gate | Validation checkpoint that must be passed before proceeding (e.g., all tests must pass before creating PR). |
| Smoke Test | Quick, basic test verifying fundamental functionality works after deployment or major change. |
| Regression Test | Test verifying that previously working functionality still works after changes. |
| Integration Test | Test verifying correct interaction between components or services. |
| End-to-End Test (E2E) | Test validating complete user workflow from start to finish. |
Credentials and Security
| Term | Definition |
|---|---|
| Credential | Secret information (API key, token, password) needed to access external services. |
| Credential Activation | Making a credential available as environment variable in sandbox for a specific session. |
| Credential Manager | UI for registering, editing, and managing credentials. Accessed via top-right menu. |
| OAuth | Authentication protocol allowing secure authorization without sharing passwords. Used for GitHub, GitLab, etc. |
| Session-Scoped | Limited to one session only. Credentials are session-scoped (not shared across sessions). |
Billing
| Term | Definition |
|---|---|
| Credits | Consumable units purchased to pay for model usage, sandbox time, and storage. Different operations cost different credit amounts. |
| Auto-Reload | Automatic credit purchase when balance drops below threshold, preventing session interruption. |
| Plan Tier | Subscription level (Basic, Pro, Ultimate) determining features, resource limits, and included credit allocation. |
| Usage Analytics | Detailed breakdown of credit consumption by category (models, sandbox, storage). |
Workflow Patterns
| Term | Definition |
|---|---|
| Goal-Driven Request | Structuring requests around desired outcomes rather than implementation steps. |
| Evidence-Based Validation | Requiring proof (test output, benchmarks, logs) for all claims rather than accepting assertions. |
| Test-First Development (TDD) | Writing comprehensive tests before implementation, then implementing to satisfy tests. |
| Benchmark-Driven Optimization | Establishing baseline performance, implementing changes, measuring improvements with same test harness. |
| Specification-Driven Development | Creating complete technical specification before implementation, then implementing according to spec. |
Common Abbreviations
| Abbreviation | Full Name |
|---|---|
| API | Application Programming Interface |
| CI/CD | Continuous Integration/Continuous Deployment |
| CPU | Central Processing Unit |
| CRUD | Create, Read, Update, Delete |
| CSS | Cascading Style Sheets |
| E2E | End-to-End (testing) |
| GPU | Graphics Processing Unit |
| HTML | HyperText Markup Language |
| HTTP/HTTPS | HyperText Transfer Protocol (Secure) |
| IDE | Integrated Development Environment |
| I/O | Input/Output |
| JSON | JavaScript Object Notation |
| JWT | JSON Web Token |
| LLM | Large Language Model |
| OAuth | Open Authorization |
| ORM | Object-Relational Mapping |
| PR | Pull Request |
| RAM | Random Access Memory |
| REST | Representational State Transfer |
| SDK | Software Development Kit |
| SQL | Structured Query Language |
| SSH | Secure Shell |
| TDD | Test-Driven Development |
| TLS | Transport Layer Security |
| TUI | Text User Interface |
| UI/UX | User Interface/User Experience |
| URL | Uniform Resource Locator |
| VM | Virtual Machine |
| VPN | Virtual Private Network |
| WIP | Work In Progress |
| YAML | YAML Ain’t Markup Language |