antigravity-memory

name antigravity-memory description Create and optimize MEMORY.md memory files or .agent/rules/ modular rules for Antigravity projects. Comprehensive guidance on file hierarchy, content structure, path-scoped rules, best practices, and anti-patterns. Use when working with MEMORY.md files, .agent/rules directories, setting up new projects, or improving Antigravity's context awareness. Objective Master the creation of effective Antigravity memory systems using either MEMORY.md files or the modular .agent/rules/ directory. This skill covers file hierarchy, content structure, path-scoped rules, formatting, emphasis techniques, and common anti-patterns to avoid. Memory files are automatically loaded at session startup, consuming tokens from your 200k context window. Every instruction competes with Antigravity's ~50 built-in instructions, leaving ~100-150 effective instruction slots for your customizations. Two approaches available: MEMORY.md - Single file, simpler, best for small projects .agent/rules/ - Modular files with optional path-scoping, best for large projects Quick Start Bootstrap New Project Run /init in Antigravity to auto-generate a MEMORY.md with project structure. Or create manually at project root: # Project Name ## Tech Stack - [Primary language/framework] - [Key libraries] ## Commands - `npm run dev` - Start development - `npm test` - Run tests - `npm run build` - Build for production ## Code Conventions - [2-3 critical conventions] ## Important Context - [1-2 architectural decisions worth knowing] Quick Add Memory Press # during a Antigravity session to quickly add new memory items without editing the file directly. Edit Memory Use /memory command to open MEMORY.md in your system editor. File Hierarchy Antigravity loads MEMORY.md files in a specific order. Higher priority files are loaded first and take precedence. Loading Order Priority Location Purpose Scope 1 (Highest) /Library/Application Support/AntigravityCode/MEMORY.md (macOS) Enterprise policy (managed by IT) All org users 2 ./MEMORY.md or ./.agent/MEMORY.md Project memory (git-tracked) Team via git 2 ./.agent/rules/*.md Modular rules (git-tracked) Team via git 3 ~/.agent/MEMORY.md User preferences (global) All your projects 3 ~/.agent/rules/*.md Personal modular rules (global) All your projects 4 (Lowest) ./CLAUDE.local.md Personal project prefs (auto-gitignored) Just you Recursive Loading Antigravity recurses UP from current directory to root, loading all MEMORY.md files found. Running Antigravity in foo/bar/ loads: foo/bar/MEMORY.md foo/MEMORY.md Root-level files Antigravity also discovers MEMORY.md in SUBTREES when reading files in those directories. Monorepo Strategy For monorepos, use layered approach: root/ ├── MEMORY.md # Universal: tech stack, git workflow ├── apps/ │ ├── web/MEMORY.md # Frontend-specific patterns │ └── api/MEMORY.md # Backend-specific patterns └── packages/ └── shared/MEMORY.md # Shared library conventions Root file defines WHEN to use patterns; subtree files define HOW. Rules Directory The .agent/rules/ directory provides a modular alternative to monolithic MEMORY.md files. Instead of one large file, you organize instructions into multiple focused markdown files. When to Use Rules Use .agent/rules/ when: Project has many distinct concerns (testing, security, API, frontend) Different rules apply to different file types Team members maintain different areas You want to update one concern without touching others Use MEMORY.md when: Project is small/simple All rules are universal You prefer a single source of truth Rules Structure .agent/rules/ ├── code-style.md # Formatting and conventions ├── testing.md # Test requirements ├── security.md # Security checklist ├── frontend/ │ ├── react.md # React-specific patterns │ └── styles.md # CSS conventions └── backend/ ├── api.md # API development rules └── database.md # Database conventions Key points: All .md files are discovered recursively No imports or configuration needed Same priority as MEMORY.md Supports symlinks for sharing rules across projects Path Scoped Rules Rules can be scoped to specific files using YAML frontmatter: --- paths: src/api/**/*.ts --- # API Development Rules - All API endpoints must include input validation - Use the standard error response format Path patterns supported: Pattern Matches **/*.ts All TypeScript files in any directory src/**/* All files under src/ directory src/components/*.tsx React components in specific directory src/**/*.{ts,tsx} TypeScript and TSX files (brace expansion) {src,lib}/**/*.ts Files in multiple directories Rules without paths frontmatter load unconditionally for all files. User Level Rules Create personal rules that apply to all your projects: ~/.agent/rules/ ├── preferences.md # Your coding preferences ├── workflows.md # Your preferred workflows └── git.md # Your git conventions User-level rules load before project rules, giving project rules higher priority for overrides. Symlinks Support Share common rules across multiple projects using symlinks: # Symlink a shared rules directory ln -s ~/shared-claude-rules .agent/rules/shared # Symlink individual rule files ln -s ~/company-standards/security.md .agent/rules/security.md Circular symlinks are detected and handled gracefully. Content Framework Structure your MEMORY.md using the WHAT-WHY-HOW framework: WHAT - Project Context: Tech stack, directory structure, architecture WHY - Purpose: Architectural decisions, why patterns exist HOW - Workflow: Commands, testing, git workflow, verification steps ## Tech Stack - Next.js 15 with App Router - PostgreSQL via Prisma ORM ## Architecture Decisions - Server Components for data fetching - All forms use TanStack Form ## Commands - `pnpm dev` - Start dev server - `pnpm test:ci` - Run tests - `pnpm build` - Production build ## Git Workflow - Branch: `feature/name` or `fix/name` - Run tests before committing See resources/section-templates.md for complete templates. Emphasis Techniques Antigravity follows emphasized instructions more reliably. Use these techniques strategically for critical rules. Keyword Hierarchy Use emphasis keywords in order of severity: Keyword Use For Example CRITICAL Non-negotiable rules **CRITICAL**: Never commit secrets NEVER Absolute prohibitions NEVER: Push directly to main ALWAYS Mandatory behaviors ALWAYS: Run tests before pushing IMPORTANT Significant guidance IMPORTANT: Keep components under 300 lines YOU MUST Explicit requirements YOU MUST: Use TanStack Form for forms Formatting Patterns Bold + CRITICAL keyword: **CRITICAL** : Always run tests before pushing code Capitalized emphasis: IMPORTANT: Do not commit environment variables YOU MUST: Follow the git workflow outlined below NEVER: Include API keys in code ALWAYS: Use TypeScript strict mode Strikethrough for forbidden options: - `pnpm test:ci` - Run tests (use this) - ~~ `pnpm test` ~~ - NEVER use (interactive mode) Visual markers (use sparingly): ⚠️ WARNING: This affects production data 🔒 SECURITY: Never commit secrets to git Placement Strategy Order matters. Antigravity pays more attention to: First items in each section (put critical rules first) Repeated items across sections (repeat critical rules in context) Emphasized items with CRITICAL/NEVER/ALWAYS keywords Structure your file with critical rules first: ## Code Conventions ### Critical Rules - **NEVER** commit .env files - **ALWAYS** run tests before pushing - **CRITICAL** : Use TanStack Form for ALL forms ### General Guidelines - Prefer Server Components - Keep components under 300 lines Repetition For Emphasis For extremely important rules, repeat in multiple relevant contexts: ## Forms **CRITICAL** : Use TanStack Form for ALL forms ## Before Editing - **CRITICAL** : Use TanStack Form for forms ## Code Review Checklist - [ ] Forms use TanStack Form ( **CRITICAL** ) Writing Effective Instructions Golden Rule Show your MEMORY.md to someone with minimal project context. If they're confused, Antigravity will be too. Be Specific Vague instructions cause inconsistent behavior: ❌ VAGUE: - Format code properly - Write good tests - Follow best practices ✅ SPECIFIC: - Run `pnpm lint` before committing (Prettier configured) - Write tests in `__tests__/` using Vitest - Use TanStack Form for all forms (see `src/features/form/` ) Show Dont Tell When format matters, show examples: ❌ TELLING: Use conventional commits with type and description. ✅ SHOWING: ## Commit Format feat(auth): implement JWT authentication Add login endpoint and token validation Types: feat, fix, refactor, docs, test, chore Eliminate Ambiguity Replace vague phrases with clear directives: Ambiguous Clear Alternative "Try to..." "Always..." or "Never..." "Should probably..." "Must..." or "May optionally..." "Generally..." "Always... except when [condition]" "Consider..." "If [condition], then [action]" Define Edge Cases Anticipate questions and answer them: ❌ INCOMPLETE: Run tests before pushing. ✅ COMPLETE: ## Testing - Run `pnpm test:ci` before pushing - If tests fail, fix before committing - New features require tests in `__tests__/` - Minimum 80% coverage for new code Provide Decision Criteria When Antigravity must make choices, give criteria: ## Component Choice **Use Server Component when:** - Data fetching only - No user interaction needed **Use Client Component when:** - User interaction required - Browser APIs needed (localStorage, window) Separate Obligation Levels Clearly distinguish requirements from suggestions: ## API Development ### Must Have - Input validation with Zod - Error handling for all endpoints ### Nice to Have - Pagination for list endpoints - Caching headers ### Must Not - Expose internal errors to clients - Log sensitive data Size Constraints Limits Ideal : 100-200 lines maximum Practical max : 300 lines before splitting Universal items : Under 60 lines Why these limits matter: Antigravity reliably follows ~150-200 total instructions Antigravity's system prompt uses ~50 instructions Leaves ~100-150 slots for YOUR instructions Irrelevant content degrades instruction-following Scaling Strategy When exceeding limits: Move task-specific details to separate files Link from MEMORY.md with descriptions Use progressive disclosure pattern ## Detailed Guides - **API Routes** : See [ docs/api-patterns.md ]( docs/api-patterns.md ) - **Testing** : See [ docs/testing-guide.md ]( docs/testing-guide.md ) - **Deployment** : See [ docs/deployment.md ]( docs/deployment.md )