Core Concepts
How It Works
Gem Team wraps your AI with a structured delivery pipeline: task classification, planning, delegation, verification, debugging, and learning: so you get reliable results without depending on a single long prompt.
Work is batched, dependencies are serialized, and high-confidence learnings are saved for future runs.
Knowledge Layers
Gem Team organizes knowledge across six layers, each with a specific purpose:
| Layer | Location | Purpose |
|---|---|---|
| PRD | docs/PRD.yaml | Product requirements and approved decisions |
| AGENTS.md | AGENTS.md | Stable project conventions, rules, and agent instructions |
| Plan artifacts | docs/plan/{plan_id}/ | Per-task plans, context envelopes, task registries, evidence, and results |
| Memory | Memory tool / configured backend | Durable facts, decisions, gotchas, patterns, and failure modes |
| Skills | docs/skills/ | Reusable procedures extracted from successful repeated workflows |
| Derived docs | docs/knowledge/ | Reference notes, external docs, summaries, and research outputs |
Context Envelope
The context envelope is a progressive cache shared across all agents. It includes:
- Tech stack: languages, frameworks, libraries, and versions
- Architecture snapshot: component relationships, data flow, API contracts
- Conventions: coding style, naming, patterns, testing approach
- Constraints: platform, performance, security, accessibility requirements
- Research digest: findings from codebase exploration
- Prior decisions: architectural and design decisions with rationale
The envelope is enriched after each execution wave and filtered per-agent: each agent receives only the sections relevant to its task.
Three-Tier Memory
| Tier | Scope | Persistence |
|---|---|---|
| Repo | Workspace-scoped | Stored with the repository |
| Session | Conversation-scoped | Cleared after conversation ends |
| Global | User-scoped | Persists across all workspaces |
Facts are persisted only when confidence ≥ 0.85, with high-confidence items (≥ 0.90, stable, ≥ 3 uses) promoted to durable cache. Auto-eviction occurs after 90 days with no access (read or write).
Execution Model
Workflow depth adapts to complexity: from one-shot for trivial tasks to full DAG-based wave execution with validation gates for high-risk work. See Workflow → for the full pipeline.