Knowledge Items Architecture

Relevant source files

• Google/Antigravity/Fast Prompt.txt

Purpose and Scope

This document details Google Antigravity's Knowledge Items (KI) system, which provides persistent, distilled knowledge across conversations to prevent redundant research and enable cumulative learning. The KI architecture includes the mandatory KI-first research protocol, the dual-storage model (raw logs vs distilled knowledge), and the separate KNOWLEDGE SUBAGENT that maintains the knowledge base.

For information about conversation logs and the two-stage retrieval workflow, see page 3.3 (Conversation Logs and Persistent Context). For general Antigravity tool usage and workflow system, see page 3.4 (Workflow System and Turbo Annotations).

---

System Overview

The Knowledge Items system addresses a fundamental problem in stateless AI conversations: each new conversation starts from scratch, forcing the agent to rediscover information already learned in previous sessions. Antigravity solves this through a two-tier persistent storage architecture:

1. Raw conversation logs - Original conversation history in brain/<conversation_id>/.system_generated/logs/ containing overview.txt and task_*.log files
2. Distilled Knowledge Items - Curated topic knowledge in C:\Users\Lucas\.gemini\antigravity\knowledge\<topic_name>\ with metadata.json and artifacts/ subdirectories

The mandatory KI-first research protocol is defined at Google/Antigravity/Fast Prompt.txt102-110:

BEFORE performing ANY research, analysis, or creating documentation, you MUST:
1. Review the KI summaries already provided to you at conversation start
2. Identify relevant KIs by checking if any KI titles/summaries match your task
3. Read relevant KI artifacts using the artifact paths listed in the summaries 
   BEFORE doing independent research
4. Build upon KI by using the information from the KIs to inform your own research

This prevents redundant work by ensuring the agent checks existing knowledge before performing fresh research. The protocol is enforced through system prompt instructions, with violation examples shown at Google/Antigravity/Fast Prompt.txt112-136

Sources: Google/Antigravity/Fast Prompt.txt99-215

Knowledge Items Directory Structure

File System Layout

Diagram: KI File System Structure with Absolute Paths

Sources: Google/Antigravity/Fast Prompt.txt204-207 Google/Antigravity/Fast Prompt.txt272-295

metadata.json Structure

Each KI directory at C:\Users\Lucas\.gemini\antigravity\knowledge\<topic>\ contains a metadata.json file with the following structure:

Field	Type	Description	Example Value
summary	string	Distilled knowledge on the specific topic	"Game architecture patterns including module structure and player interfaces"
timestamps	object	Creation and last modification times	{"created": "2024-01-15", "modified": "2024-02-20"}
references	string[]	Links to original source conversations and files	["brain/1a2f082d.../logs/overview.txt", "src/game/core.ts"]
artifact_paths	string[]	Relative paths to documentation files in artifacts/	["architecture_overview.md", "implementation_patterns.md"]

The artifact_paths field is critical for the KI-first workflow - these paths are provided in the conversation start summaries, enabling the agent to immediately call view_file without needing to list_dir first.

artifacts/ Directory

The artifacts/ subdirectory contains documentation files generated by the KNOWLEDGE SUBAGENT. Common artifact naming patterns:

Pattern	Examples	Purpose
*_overview.md	architecture_overview.md, system_overview.md	High-level system explanations
*_patterns.md	implementation_patterns.md, design_patterns.md	Reusable code patterns
*_interface.md	ai_player_interface.md, api_interface.md	Interface/contract definitions
*_strategies.md	testing_strategies.md, caching_strategies.md	Approach documentation
*_guide.md	migration_guide.md, deployment_guide.md	Step-by-step procedures
*_diagram.md	class_diagram.md, flow_diagram.md	Visual representations

Sources: Google/Antigravity/Fast Prompt.txt204-207 Google/Antigravity/Fast Prompt.txt256-268 Google/Antigravity/Fast Prompt.txt282-288

metadata.json Structure

Each KI directory at C:\Users\Lucas\.gemini\antigravity\knowledge\<topic>\ contains metadata.json:

Field	Type	Description
summary	string	Distilled knowledge on the specific topic
timestamps	object	Creation and last modification times
references	array	Links to original source conversations and files
artifact_paths	array	Relative paths to documentation files in artifacts/

The artifact_paths field is critical - these paths are provided in conversation start summaries, enabling direct view_file calls without list_dir.

artifacts/ Directory

The artifacts/ subdirectory contains markdown documentation files:

Pattern	Examples	Purpose
*_overview.md	architecture_overview.md, system_overview.md	High-level explanations
*_patterns.md	implementation_patterns.md, design_patterns.md	Reusable patterns
*_interface.md	ai_player_interface.md, api_interface.md	Interface definitions
*_strategies.md	testing_strategies.md, caching_strategies.md	Approach documentation
*_guide.md	migration_guide.md, deployment_guide.md	Step-by-step procedures
*_diagram.md	class_diagram.md, flow_diagram.md	Visual representations

Sources: Google/Antigravity/Fast Prompt.txt204-207 Google/Antigravity/Fast Prompt.txt256-295

---

Mandatory KI-First Research Workflow

The Critical Rule

The system enforces strict ordering: summaries → KI artifacts → independent research. This prevents agents from recreating knowledge that already exists.

Diagram: KI-First Research Workflow with Tool Calls

Sources: Google/Antigravity/Fast Prompt.txt99-136

Anti-Pattern Example

From Google/Antigravity/Fast Prompt.txt112-121:

USER: Can you analyze the core engine module and document its architecture?
# BAD: Agent starts researching without checking KI summaries first
ASSISTANT: [Immediately calls list_dir and view_file to start fresh analysis]
ASSISTANT: [Creates new 600-line analysis document]
# PROBLEM: A "Core Engine Architecture" KI already existed in the summaries!

Correct Pattern Example

From Google/Antigravity/Fast Prompt.txt123-136:

USER: Can you analyze the core engine module and document its architecture?
# GOOD: Agent checks KI summaries first
ASSISTANT: Let me first check the KI summaries for existing analysis.
# From KI summaries: "Core Engine Architecture" with artifact: architecture_overview.md
ASSISTANT: I can see there's already a comprehensive KI on the core engine.
ASSISTANT: [Calls view_file to read the existing architecture_overview.md artifact]
TOOL: [Returns existing analysis]
ASSISTANT: There's already a detailed analysis. Would you like me to enhance it with specific details, or review this existing analysis?

Sources: Google/Antigravity/Fast Prompt.txt99-136

---

When to Use KIs vs Conversation Logs

Decision Matrix

Diagram: KI vs Conversation Log Decision Flow with Tool Invocations

Sources: Google/Antigravity/Fast Prompt.txt218-250

Usage Rules from System Prompt

Use Knowledge Items when: (Google/Antigravity/Fast Prompt.txt138-146)

• Before ANY research or analysis - FIRST check if a KI already exists on this topic
• Before creating documentation - Verify no existing KI covers this to avoid duplication
• When you see a relevant KI in summaries - If a KI title matches the request, READ the artifacts FIRST
• When encountering new concepts - Search for related KIs to build context
• When referenced in context - Retrieve KIs mentioned in conversations or other KIs

Use Conversation Logs when: (Google/Antigravity/Fast Prompt.txt226-239)

1. You have a new Conversation ID (from @mention or reading another conversation/KI), but only if the information is likely relevant
2. The USER explicitly mentions a specific conversation by topic or recency
3. The USER alludes to specific information likely discussed in a previous conversation, but you cannot identify the relevant conversation from summaries
   • Use file system research tools (codebase_search, list_dir, grep_search) to identify relevant conversation(s)

Do NOT use Conversation Logs when: (Google/Antigravity/Fast Prompt.txt233-239)

1. Researching a specific topic - Search for relevant KIs first
2. A conversation is referenced by KI/another conversation, and you know from summary it's not relevant
3. After reading overview.txt, you conclude the conversation is not relevant - Do NOT proceed to read task logs or artifacts

Sources: Google/Antigravity/Fast Prompt.txt138-250

---

Knowledge Items as Starting Points

Critical Distinction

From Google/Antigravity/Fast Prompt.txt208-215:

CRITICAL: KIs are snapshots from past work. They are valuable starting points, but NOT a substitute for independent research and verification.

• Always verify: Use the references in metadata.json to check original sources
• Expect gaps: KIs may not cover all aspects. Supplement with your own investigation
• Question everything: Treat KIs as clues that must be verified and supplemented

KI Content Categories

Based on the usage examples, KIs commonly store:

Category	Examples	When to Check
Architectural Patterns	game_architecture_patterns with architecture_overview.md, implementation_patterns.md, class_diagram.md	Before designing "new" features, when adding to core abstractions
Implementation Details	randomized_ai_implementation with random_player.md, ai_player_interface.md, testing_strategies.md	When planning similar implementations
Known Issues	Bug documentation, gotchas, edge cases	Before debugging unexpected behavior
Best Practices	Resource management patterns, configuration precedence	When experiencing resource issues, config problems
Integration Patterns	Caching patterns, data layer integration, async operations	Before integrating components, adding common functionality

Sources: Google/Antigravity/Fast Prompt.txt148-215 Google/Antigravity/Fast Prompt.txt254-295

---

The KNOWLEDGE SUBAGENT

Separation of Concerns

The Knowledge Items system employs a separate KNOWLEDGE SUBAGENT that maintains the KI database. This architectural separation ensures:

1. Main Antigravity agent - Handles user tasks, reads KIs via view_file, never modifies KIs
2. KNOWLEDGE SUBAGENT - Reads conversation logs from brain/<conv_id>/.system_generated/logs/, creates/updates metadata.json and artifacts/ in knowledge/<topic>/

From Google/Antigravity/Fast Prompt.txt240-242:

They are generated by a separate KNOWLEDGE SUBAGENT that reads the conversations and then distills the information into new KIs or updates existing KIs as appropriate.

Diagram: Agent Separation and Tool-to-Path Mapping

Agent Tool Permissions Table

Agent	File Operations (Read)	File Operations (Write)	Edit Operations
Antigravity (Main)	view_file(AbsolutePath) on: • C:\Users\Lucas\.gemini\antigravity\knowledge\<topic>\metadata.json • C:\Users\Lucas\.gemini\antigravity\knowledge\<topic>\artifacts\*.md list_dir(DirectoryPath) on: • C:\Users\Lucas\.gemini\antigravity\knowledge\ grep_search(SearchPath, Query) on: • C:\Users\Lucas\.gemini\antigravity\knowledge\ codebase_search(Query, TargetDirectories) on: • ["C:\Users\Lucas\.gemini\antigravity\knowledge"]	write_to_file(TargetFile, CodeContent) on: • C:\Users\Lucas\.gemini\antigravity\brain\<conv_id>\.system_generated\logs\* ONLY	❌ None on knowledge/ paths
KNOWLEDGE SUBAGENT	view_file(AbsolutePath) on: • C:\Users\Lucas\.gemini\antigravity\brain\<conv_id>\.system_generated\logs\overview.txt • C:\Users\Lucas\.gemini\antigravity\brain\<conv_id>\.system_generated\logs\task_*.log	write_to_file(TargetFile, CodeContent) on: • C:\Users\Lucas\.gemini\antigravity\knowledge\<topic>\metadata.json • C:\Users\Lucas\.gemini\antigravity\knowledge\<topic>\artifacts\*.md	replace_file_content(TargetFile, TargetContent, ReplacementContent) on: • knowledge\<topic>\metadata.json • knowledge\<topic>\artifacts\*.md multi_replace_file_content(TargetFile, ReplacementChunks) on: • Same paths as above

Tool Type Definitions Referenced:

• write_to_file - Google/Antigravity/Fast Prompt.txt593-610
• replace_file_content - Google/Antigravity/Fast Prompt.txt462-489
• multi_replace_file_content - Google/Antigravity/Fast Prompt.txt438-461
• view_file - Google/Antigravity/Fast Prompt.txt571-582
• list_dir - Google/Antigravity/Fast Prompt.txt412-419
• grep_search - Google/Antigravity/Fast Prompt.txt394-411
• codebase_search - Google/Antigravity/Fast Prompt.txt338-347

The main agent never invokes write/edit tools on paths under C:\Users\Lucas\.gemini\antigravity\knowledge\. The KNOWLEDGE SUBAGENT operates asynchronously after conversations complete, preventing race conditions and ensuring the main agent always reads consistent KI state.

Sources: Google/Antigravity/Fast Prompt.txt218-242 Google/Antigravity/Fast Prompt.txt338-347 Google/Antigravity/Fast Prompt.txt394-411 Google/Antigravity/Fast Prompt.txt412-419 Google/Antigravity/Fast Prompt.txt438-461 Google/Antigravity/Fast Prompt.txt462-489 Google/Antigravity/Fast Prompt.txt571-582 Google/Antigravity/Fast Prompt.txt593-610

---

Detailed Usage Examples

Example 1: Multiple KIs Required

From Google/Antigravity/Fast Prompt.txt254-268:

USER: I need to add a new AI player to my tic-tac-toe game that uses minimax 
algorithm and follows the existing game architecture patterns.

# The ASSISTANT already has KI summaries available that include artifact paths.
# No need to search or list directories.

# From the summaries, the ASSISTANT can see multiple KIs:
# - game_architecture_patterns KI with artifacts: architecture_overview.md, 
#   implementation_patterns.md, class_diagram.md
# - randomized_ai_implementation KI with artifacts: random_player.md, 
#   ai_player_interface.md, testing_strategies.md
# - database_schema KI with artifacts: schema_design.md, migration_guide.md
# - ui_components KI with artifacts: button_styles.md, layout_system.md

# The ASSISTANT should focus only on relevant KIs and their artifacts

ASSISTANT: I can see from the KI summaries that `game_architecture_patterns` 
and `randomized_ai_implementation` are relevant to implementing an AI player. 
I'll review the key artifacts from these KIs.

ASSISTANT: [parallel view_file calls to read architecture_overview.md, 
implementation_patterns.md, ai_player_interface.md from the KI summaries]

TOOL: [File contents are returned]

ASSISTANT: Based on the patterns in these KIs, here's how to implement your 
AI player...

Key points:

• KI summaries provided at conversation start include artifact paths
• Agent identifies relevant KIs (game_architecture_patterns, randomized_ai_implementation) and ignores irrelevant ones (database_schema, ui_components)
• Uses parallel view_file calls to read multiple artifacts efficiently
• Builds implementation on existing patterns from KIs

Example 2: Conversation Logs + KI Required

From Google/Antigravity/Fast Prompt.txt270-295:

SYSTEM: Here are some recent conversation IDs and titles:
1a2f082d-72a2-b281-0081-8b9cad0e1f20: Refactoring game logic into separate module
f81d4fae-7dec-11d0-a765-00a0c91e6bf6: Designing game frontend

USER: The refactoring we just did to extract the game logic into a separate 
module broke the unit tests.

# User implicitly references recent conversation 
# 1a2f082d-72a2-b281-0081-8b9cad0e1f20

ASSISTANT: Let me check our conversation for context on yesterday's refactoring.

ASSISTANT: [calls list_dir on 
C:\Users\Lucas\.gemini\antigravity\brain\1a2f082d-72a2-b281-0081-8b9cad0e1f20\.system_generated\logs]

TOOL OUTPUT: [List of files including overview.txt and task_*.log files]

ASSISTANT: [calls view_file to read log files]

# The ASSISTANT already has KI summaries showing multiple KIs with artifact paths:
# - game_logic KI with artifacts: module_structure.md, core_functions.md, 
#   state_management.md
# - testing KI with artifacts: unit_test_patterns.md, test_fixtures.md, 
#   mocking_guide.md
# - database_design KI (irrelevant)
# - frontend KI (irrelevant)

ASSISTANT: I see the module extraction changes. From the KI summaries, I can 
see `game_logic` and `testing` KIs are relevant. I'll review the specific 
artifacts listed in their summaries.

ASSISTANT: [parallel view_file calls to read module_structure.md, 
core_functions.md, unit_test_patterns.md from the KI summaries]

TOOL: [File content is returned]

ASSISTANT: [Tool calls to read original source files, run tests, view terminal 
logs, etc.]

ASSISTANT: I see the issues. We introduced a bug in the refactoring. Let me 
fix it...

Key points:

• Agent reads conversation logs when user explicitly references recent work
• Uses overview.txt as first check before reading full task logs
• Checks KI summaries for relevant topic-based knowledge (game_logic, testing)
• Combines conversation-specific details with topic-based KI knowledge
• Ignores irrelevant KIs (database_design, frontend)

Sources: Google/Antigravity/Fast Prompt.txt254-295

---

KI-First Mandate Scenarios

When KI Check is MANDATORY

The system prompt explicitly requires checking KIs in these scenarios (Google/Antigravity/Fast Prompt.txt148-215):

1. Debugging and Troubleshooting:

• Before debugging unexpected behavior - Check for KIs documenting known bugs/gotchas
• Resource issues (memory, file handles, connection limits) - Check for best practices KIs
• Config changes don't take effect - Check for configuration precedence/override KIs
• Utility functions behave unexpectedly - Check for known bugs KIs

2. Following Architectural Patterns:

• Before designing "new" features - Check if similar patterns already exist
• Especially for: system extensions, configuration points, data transformations, async operations
• When adding to core abstractions - Check for refactoring pattern KIs (plugin systems, handler patterns)
• When implementing common functionality - Check for established patterns (caching, validation, serialization, authentication)

3. Complex Implementation:

• When planning multi-phase work - Check for workflow example KIs
• When uncertain about approach - Check for similar past implementations in KIs
• Before integrating components - Check for integration pattern KIs

Deceptively Simple Requests

From Google/Antigravity/Fast Prompt.txt189-201:

If a request sounds "simple" but involves core infrastructure, ALWAYS check KI summaries first. The simplicity might hide:

• Established implementation patterns
• Known gotchas and edge cases
• Framework-specific conventions
• Previously solved similar problems

Common "deceptively simple" requests:

• "Add a field to track X" → Likely has an established pattern for metadata/instrumentation
• "Make this run in the background" → Check async execution patterns
• "Add logging for Y" → Check logging infrastructure and conventions

Sources: Google/Antigravity/Fast Prompt.txt148-215

---

Tool Integration

File System Access Tools

The agent accesses KIs using file system tools defined in Google/Antigravity/Fast Prompt.txt320-611:

Diagram: Tool Call Patterns for KI Retrieval

Tool Function Signatures for KI Access

The agent uses file system tools defined in the functions namespace Google/Antigravity/Fast Prompt.txt320-611 to access KIs:

Tool Parameter Reference Table

Tool	Required Parameters	Optional Parameters	Return Type	Definition
view_file	AbsolutePath: string	StartLine?: number EndLine?: number waitForPreviousTools?: boolean	File contents as string	Google/Antigravity/Fast Prompt.txt571-582
list_dir	DirectoryPath: string	waitForPreviousTools?: boolean	Array of file/directory names	Google/Antigravity/Fast Prompt.txt412-419
grep_search	SearchPath: string Query: string	Includes?: string[] MatchPerLine?: boolean CaseInsensitive?: boolean IsRegex?: boolean waitForPreviousTools?: boolean	Pattern matches with line numbers	Google/Antigravity/Fast Prompt.txt394-411
codebase_search	Query: string TargetDirectories: string[]	waitForPreviousTools?: boolean	Semantically ranked code snippets	Google/Antigravity/Fast Prompt.txt338-347
search_in_file	AbsolutePath: string Query: string	waitForPreviousTools?: boolean	Relevant code snippets from file	Google/Antigravity/Fast Prompt.txt534-543

Common KI Access Patterns

Sources: Google/Antigravity/Fast Prompt.txt320-611 Google/Antigravity/Fast Prompt.txt338-347 Google/Antigravity/Fast Prompt.txt394-411 Google/Antigravity/Fast Prompt.txt412-419 Google/Antigravity/Fast Prompt.txt534-543 Google/Antigravity/Fast Prompt.txt571-582

Parallel Artifact Reads

Diagram: Parallel view_file Execution Pattern

The waitForPreviousTools parameter controls parallel execution Google/Antigravity/Fast Prompt.txt314-316:

Parallel Execution Control

Parameter	Behavior	Latency	Use Case
waitForPreviousTools: false	Execute immediately	1× (all parallel)	Independent KI artifact reads
waitForPreviousTools: true	Wait for previous completion	N× (sequential)	Dependent operations
Omitted	Same as false	1× (all parallel)	Default pattern

Sources: Google/Antigravity/Fast Prompt.txt256-268 Google/Antigravity/Fast Prompt.txt314-316 Google/Antigravity/Fast Prompt.txt571-582

---

Summary

The Knowledge Items architecture in Google Antigravity implements a sophisticated persistent knowledge system with these key characteristics:

1. Dual storage model - Raw conversation logs separate from distilled KIs
2. Mandatory KI-first protocol - Always check KI summaries before independent research
3. Structured storage - Each KI contains metadata.json with references and artifacts/ directory with detailed documentation
4. Separation of concerns - Main agent reads KIs, separate KNOWLEDGE SUBAGENT maintains them
5. Starting points, not ground truth - KIs must be verified and supplemented with independent research
6. Efficient retrieval - Parallel reads of multiple KI artifacts when needed
7. Scenario-based usage - Specific rules for when to use KIs vs conversation logs

This architecture prevents the "research from scratch" anti-pattern and enables cumulative learning across conversations, making Antigravity increasingly effective over time as its knowledge base grows.

Sources: Google/Antigravity/Fast Prompt.txt99-295