Mental Models & Architecture
Understand how Cursor IDE thinks — tools, models, rules/skills/hooks, and context indexing.
title: "Mental Models & Architecture" description: "Understand how Cursor IDE thinks — tools, models, rules/skills/hooks, and context indexing." section: "Full Guide" readTime: "12 min"
Mental Models & Architecture
Before diving into Cursor, understand how it thinks. This mental model unlocks everything else.
The Tool Selection Matrix
| Tool | Shortcut | Scope | When to Use |
|---|---|---|---|
| Tab | Tab | Single token | Boilerplate, repetitive patterns, known APIs (~320ms) |
| Inline Edit | Cmd/Ctrl+K | Single file | Refactor a function, rename, small fixes |
| Composer / Agent | Cmd/Ctrl+I | Multi-file | Large refactors, migrations, architectural changes |
| Chat | Cmd/Ctrl+L | Conversational | Q&A, planning, cross-cutting queries |
| Debug Mode | Agent submenu | Any | Elusive bugs, race conditions, runtime issues |
| Parallel Agents | Agent panel | Git worktrees | Explore multiple approaches simultaneously |
| Visual Editor | Right-click element | Browser | UI work, real-time CSS editing |
Thumb rule: Tab for speed, Inline for precision, Agent for correctness.
Chat has three sub-modes:
- Ask — read-only Q&A and planning
- Edit — apply changes directly to files
- Agent — autonomous: file creation, search, terminal commands
How Cursor Actually Works
Cursor is an orchestration layer, not a monolithic LLM:
- No memory between completions — full history is fed each request
- Tools run client-side (Cursor orchestrates, the LLM just calls them)
- Context window management is critical — garbage in, garbage out
- Connects to external systems via MCP (Model Context Protocol)
Model Selection Guide (2026)
| Phase | Recommended Model | Why |
|---|---|---|
| Planning / analysis | Claude 4.5 Sonnet | Deep reasoning, 200k ctx |
| Multi-file execution | Cursor Composer 1 | 4x faster, optimized for edits |
| Full codebase review | Gemini 3 Pro | 1M token context |
| Fast iteration | GPT-5.1 Codex Max | Code-optimized, 272k ctx |
Workflow: Sonnet to plan → Composer 1 to execute → Gemini 3 Pro to review.
The Three-Tier Guidance System
| Type | Location | Purpose | Always Active? |
|---|---|---|---|
| Rules | .cursor/rules/*.md | Non-negotiable constraints | Yes (enforced) |
| Skills | .cursor/skills/*/SKILL.md | Optional reusable workflows | Conditional |
| Instructions | instructions.md (root) | Project context & background | Yes (informational) |
Three-question decision framework:
- Must this always hold? → Rule (e.g., "never use
anytypes") - Is this a reusable workflow? → Skill (e.g., TDD test-fix loop)
- Does this explain context or intent? → Instructions (e.g., "why we chose Fastify")
Codebase Indexing
Cursor embeds your code into a vector DB (Turbopuffer):
- ~8,000 lines max context per request
- Embeddings use obfuscated paths — your code never leaves your machine
- Incremental updates via Merkle Tree every 10 minutes
- Clean index = ~30% faster responses — configure
.cursorignorewell
When @codebase is triggered: query embedding computed locally → vector search → client reads local files → sent to LLM.
MCP (Model Context Protocol)
Connect Cursor to external live systems via .cursor/mcp.json:
- Context7 (built-in, no setup) — live version-specific docs for 10,000+ libraries
- Custom servers — Google Drive, Slack, GitHub, PostgreSQL, Kubernetes
- 40 tool limit per session; execution is client-side (secure)
Context7 beats @Docs when: a library updates frequently, you need a specific version (e.g., React Query v5.62.0), or training data is over 6 months old.
Watch for the 🔧 tool indicator to confirm Context7 was invoked. Ask the agent to cite a version number — if it shows the exact recent version, Context7 was used.