name	context-generation
description	Generate rich codebase context using maina's 4-layer retrieval with dynamic token budgets.
triggers	["generate context","codebase context","understand codebase","what does this code do"]

Context Generation

When to use

When you need to understand a codebase, explore how components relate, or gather context before making changes. The context engine builds a multi-layered picture of the code so that AI calls receive the most relevant information within a token budget.

Steps

Run context generation with maina context (or call the getContext MCP tool). This activates all four retrieval layers and returns a structured context document.
Working layer gathers immediate context: the current branch, staged/unstaged changes, and recently touched files. This is what you are actively working on.
Episodic layer retrieves historical context: past commit summaries, PR review feedback, and related discussions. Older memories decay using Ebbinghaus forgetting curves, keeping recent and significant events prominent.
Semantic layer builds structural understanding: tree-sitter parses source files into typed entities (functions, classes, interfaces), and a PageRank-scored dependency graph identifies the most connected and important modules.
Retrieval layer performs on-demand code search: when the other layers are insufficient, targeted searches fill gaps with specific code snippets, definitions, or usage examples.
Dynamic budget controls how many tokens each layer contributes:
- Focused (40%): For small, targeted changes where you know exactly what to modify.
- Default (60%): Balanced exploration suitable for most tasks.
- Explore (80%): For broad understanding, refactoring, or onboarding to unfamiliar code.

Example

# Default context generation (60% budget)
maina context

# Focused context for a specific file change
maina context --mode focused

# Broad exploration of a subsystem
maina context --mode explore

# Output structure:
# ## Working Context
# Branch: feature/auth-flow
# Changed files: src/auth/login.ts, src/auth/session.ts
#
# ## Episodic Context
# Recent: PR #42 added session refresh logic (3 days ago)
# Related: Commit abc123 refactored token validation (2 weeks ago)
#
# ## Semantic Context
# Key entities: AuthService (PageRank: 0.82), SessionManager (0.71)
# Dependency chain: login.ts -> AuthService -> SessionManager -> TokenStore
#
# ## Retrieved Snippets
# TokenStore.validate() — packages/core/src/auth/token-store.ts:58-72

Notes

Context is cached: identical queries with the same prompt version, context hash, and model never hit the AI twice.
Each maina command declares its own context needs via a selector, so maina review and maina plan automatically request different context shapes.
The semantic layer uses tree-sitter for language-aware parsing, supporting TypeScript, Python, Go, Rust, C#, Java, PHP, and more.
When logged into Maina Cloud (maina login), the episodic layer merges team entries automatically -- reviews your teammates accepted feed into your context. Entries are deduplicated by content hash and decay naturally over time.
All commands are available as both CLI (maina <command> or npx @mainahq/cli <command>) and MCP tools when running inside an AI coding tool.

Context Generation

When to use

Steps

Run context generation with maina context (or call the getContext MCP tool). This activates all four retrieval layers and returns a structured context document.

Working layer gathers immediate context: the current branch, staged/unstaged changes, and recently touched files. This is what you are actively working on.

Episodic layer retrieves historical context: past commit summaries, PR review feedback, and related discussions. Older memories decay using Ebbinghaus forgetting curves, keeping recent and significant events prominent.

Semantic layer builds structural understanding: tree-sitter parses source files into typed entities (functions, classes, interfaces), and a PageRank-scored dependency graph identifies the most connected and important modules.

Retrieval layer performs on-demand code search: when the other layers are insufficient, targeted searches fill gaps with specific code snippets, definitions, or usage examples.

Dynamic budget controls how many tokens each layer contributes:

Focused (40%): For small, targeted changes where you know exactly what to modify.
Default (60%): Balanced exploration suitable for most tasks.
Explore (80%): For broad understanding, refactoring, or onboarding to unfamiliar code.

Example

# Default context generation (60% budget) maina context # Focused context for a specific file change maina context --mode focused # Broad exploration of a subsystem maina context --mode explore # Output structure: # ## Working Context # Branch: feature/auth-flow # Changed files: src/auth/login.ts, src/auth/session.ts # # ## Episodic Context # Recent: PR #42 added session refresh logic (3 days ago) # Related: Commit abc123 refactored token validation (2 weeks ago) # # ## Semantic Context # Key entities: AuthService (PageRank: 0.82), SessionManager (0.71) # Dependency chain: login.ts -> AuthService -> SessionManager -> TokenStore # # ## Retrieved Snippets # TokenStore.validate() — packages/core/src/auth/token-store.ts:58-72

Notes

Context is cached: identical queries with the same prompt version, context hash, and model never hit the AI twice.

Each maina command declares its own context needs via a selector, so maina review and maina plan automatically request different context shapes.

The semantic layer uses tree-sitter for language-aware parsing, supporting TypeScript, Python, Go, Rust, C#, Java, PHP, and more.

When logged into Maina Cloud (maina login), the episodic layer merges team entries automatically -- reviews your teammates accepted feed into your context. Entries are deduplicated by content hash and decay naturally over time.

All commands are available as both CLI (maina <command> or npx @mainahq/cli <command>) and MCP tools when running inside an AI coding tool.

context-generation