Memory Types and Areas

Relevant source files

Purpose and Scope

This document describes the memory area system in Agent Zero, which organizes vector database memories into three distinct categories: MAIN, FRAGMENTS, and SOLUTIONS. Each area serves a specific purpose in knowledge management and agent learning.

For information about the vector database implementation and storage mechanics, see Vector Database. For details on memory operations (recall, consolidation, insertion), see Memory Operations. For knowledge file loading, see Knowledge Import.

Area Enumeration

Agent Zero defines memory areas as an enumeration in the Memory class:

Definition

Each memory document stored in FAISS includes an area metadata field that categorizes it. This field is used for:

Targeted search: Filter queries to specific knowledge types
Selective recall: Different recall strategies for different areas
Import routing: Automatic area assignment during knowledge loading
Consolidation scope: Area-specific memory management

Sources: python/helpers/memory.py56-59

Memory Area Types

MAIN Area

The MAIN area stores general, curated knowledge that should persist long-term.

Characteristics

Property	Value
Purpose	Permanent knowledge base
Content Source	Knowledge files (root directory)
Typical Content	Documentation, facts, instructions, domain knowledge
Recall Priority	Included in general memory searches
Consolidation	Less aggressive (preserves curated content)

Storage Location

Knowledge files placed in the root of a knowledge directory are automatically assigned to MAIN:

knowledge/
├── custom/
│   ├── my_notes.md          # → MAIN area
│   └── project_docs.txt     # → MAIN area

Sources: python/helpers/memory.py305-313 python/tools/knowledge_tool._py160-170

FRAGMENTS Area

The FRAGMENTS area stores extracted conversation snippets that capture useful information from agent interactions.

Characteristics

Property	Value
Purpose	Short-term learnings from conversations
Content Source	Automatic extraction during `monologue_end`
Typical Content	User preferences, context clues, learned facts
Recall Priority	Included in general memory searches
Consolidation	Aggressive (frequently merged/replaced)

Automatic Population

The MemorizeMemories extension automatically extracts fragments:

Extraction Prompt System

The utility LLM analyzes conversation history with:

System: memory.memories_sum.sys.md - Instructions for identifying memorable facts
Message: Full conversation history
Output: JSON array of memory strings

Sources: python/extensions/monologue_end/_50_memorize_fragments.py1-199 python/helpers/memory.py403-404

SOLUTIONS Area

The SOLUTIONS area stores successful problem-solving patterns that can be reused.

Characteristics

Property	Value
Purpose	Reusable solution patterns
Content Source	Automatic extraction during `monologue_end`
Typical Content	Problem-solution pairs, successful strategies
Recall Priority	Separate recall with distinct limits
Consolidation	Moderate (preserves distinct solutions)

Automatic Population

The MemorizeSolutions extension extracts solutions using a structured format:

Structured Solution Format

Solutions are stored with problem-solution structure:

# Problem
[Description of the problem that was solved]

# Solution
[Detailed solution steps and approach]

Sources: python/extensions/monologue_end/_51_memorize_solutions.py1-202 python/helpers/memory.py403-404

Area Assignment and Routing

Knowledge Import Routing

When knowledge files are imported, area assignment follows directory structure:

Implementation Details

The _preload_knowledge_folders method handles routing:

File Location	Assigned Area	Recursive
`knowledge/custom/*.md`	`MAIN`	No
`knowledge/custom/main/**`	`MAIN`	Yes
`knowledge/custom/fragments/**`	`FRAGMENTS`	Yes
`knowledge/custom/solutions/**`	`SOLUTIONS`	Yes

Sources: python/helpers/memory.py297-325

Document Metadata

Every document in FAISS includes area information in its metadata:

Default Area Assignment

When inserting documents without explicit area metadata:

Sources: python/helpers/memory.py403-404

Area-Based Operations

Filtered Search

Memory searches can filter by area using Python expressions:

Filter Syntax Examples

Recall Settings

The recall process uses area-aware limits:

Setting	MAIN + FRAGMENTS	SOLUTIONS
`memory_recall_memories_max_search`	12	-
`memory_recall_solutions_max_search`	-	8
`memory_recall_memories_max_result`	5	-
`memory_recall_solutions_max_result`	-	3

Sources: python/extensions/message_loop_prompts_after/_50_recall_memories.py119-136 python/helpers/settings.py554-557

Area-Specific Consolidation

Memory consolidation respects area boundaries:

Key Constraint

Consolidation only considers memories within the same area. A new FRAGMENTS memory will never be merged with a SOLUTIONS memory, maintaining semantic boundaries.

Configuration Differences

Area	Max Similar	Max LLM Context	Strategy
`FRAGMENTS`	8	4	Aggressive merging
`SOLUTIONS`	6	3	Conservative (preserve distinct solutions)
`MAIN`	-	-	Manual import only

Sources: python/helpers/memory_consolidation.py1-400 python/extensions/monologue_end/_50_memorize_fragments.py108-133 python/extensions/monologue_end/_51_memorize_solutions.py115-140

Area Usage in Prompts

Memory Injection

Recalled memories are injected into agent prompts with area awareness:

Separate Prompt Sections

The agent receives memories in distinct sections:

General Memories (agent.system.memories.md)
- Contains MAIN and FRAGMENTS results
- Formatted as a continuous text block
- Emphasizes recent learnings and facts
Solutions (agent.system.solutions.md)
- Contains only SOLUTIONS results
- Structured as problem-solution pairs
- Emphasizes reusable patterns

Sources: python/extensions/message_loop_prompts_after/_50_recall_memories.py212-219

Area Management Best Practices

When to Use Each Area

Scenario	Recommended Area	Rationale
User writes documentation	`MAIN`	Curated, permanent knowledge
Agent learns user preference	`FRAGMENTS`	Temporary, context-specific
Agent solves a complex problem	`SOLUTIONS`	Reusable pattern for future
Import existing docs	`MAIN`	Reference material
API documentation	`MAIN`	Stable, factual information

Directory Organization

Recommended Structure

usr/
└── knowledge/
    ├── README.md                      # → MAIN
    ├── api_reference.md               # → MAIN
    ├── main/                          # Explicit MAIN area
    │   ├── company_policies.md
    │   └── style_guide.md
    ├── fragments/                     # Manual FRAGMENTS (rare)
    │   └── temp_notes.txt
    └── solutions/                     # Manual SOLUTIONS (rare)
        └── deployment_patterns.md

Note: fragments/ and solutions/ subdirectories are rarely used manually, as these areas are typically populated automatically by the agent's learning extensions.

Area Filtering Implementation

Filter Expression Evaluation

The memory system uses simpleeval to evaluate filter expressions safely:

Supported Operators

Equality: area == 'main'
Inequality: area != 'solutions'
Boolean: area == 'main' or area == 'fragments'
Negation: not knowledge_source
Existence: 'field_name' in metadata

Sources: python/helpers/memory.py432-441

System Diagram: Complete Area Flow

Sources: python/helpers/memory.py54-60 python/extensions/message_loop_prompts_after/_50_recall_memories.py1-220 python/extensions/monologue_end/_50_memorize_fragments.py1-199 python/extensions/monologue_end/_51_memorize_solutions.py1-202

Memory Types and Areas

Relevant source files

Purpose and Scope

Area Enumeration

Agent Zero defines memory areas as an enumeration in the Memory class:

Definition

Each memory document stored in FAISS includes an area metadata field that categorizes it. This field is used for:

Targeted search: Filter queries to specific knowledge types
Selective recall: Different recall strategies for different areas
Import routing: Automatic area assignment during knowledge loading
Consolidation scope: Area-specific memory management

Sources: python/helpers/memory.py56-59

Memory Area Types

MAIN Area

The MAIN area stores general, curated knowledge that should persist long-term.

Characteristics

Property	Value
Purpose	Permanent knowledge base
Content Source	Knowledge files (root directory)
Typical Content	Documentation, facts, instructions, domain knowledge
Recall Priority	Included in general memory searches
Consolidation	Less aggressive (preserves curated content)

Storage Location

Knowledge files placed in the root of a knowledge directory are automatically assigned to MAIN:

knowledge/
├── custom/
│   ├── my_notes.md          # → MAIN area
│   └── project_docs.txt     # → MAIN area

Sources: python/helpers/memory.py305-313 python/tools/knowledge_tool._py160-170

FRAGMENTS Area

The FRAGMENTS area stores extracted conversation snippets that capture useful information from agent interactions.

Characteristics

Property	Value
Purpose	Short-term learnings from conversations
Content Source	Automatic extraction during `monologue_end`
Typical Content	User preferences, context clues, learned facts
Recall Priority	Included in general memory searches
Consolidation	Aggressive (frequently merged/replaced)

Automatic Population

The MemorizeMemories extension automatically extracts fragments:

Extraction Prompt System

The utility LLM analyzes conversation history with:

System: memory.memories_sum.sys.md - Instructions for identifying memorable facts
Message: Full conversation history
Output: JSON array of memory strings

Sources: python/extensions/monologue_end/_50_memorize_fragments.py1-199 python/helpers/memory.py403-404

SOLUTIONS Area

The SOLUTIONS area stores successful problem-solving patterns that can be reused.

Characteristics

Property	Value
Purpose	Reusable solution patterns
Content Source	Automatic extraction during `monologue_end`
Typical Content	Problem-solution pairs, successful strategies
Recall Priority	Separate recall with distinct limits
Consolidation	Moderate (preserves distinct solutions)

Automatic Population

The MemorizeSolutions extension extracts solutions using a structured format:

Structured Solution Format

Solutions are stored with problem-solution structure:

# Problem
[Description of the problem that was solved]

# Solution
[Detailed solution steps and approach]

Sources: python/extensions/monologue_end/_51_memorize_solutions.py1-202 python/helpers/memory.py403-404

Area Assignment and Routing

Knowledge Import Routing

When knowledge files are imported, area assignment follows directory structure:

Implementation Details

The _preload_knowledge_folders method handles routing:

File Location	Assigned Area	Recursive
`knowledge/custom/*.md`	`MAIN`	No
`knowledge/custom/main/**`	`MAIN`	Yes
`knowledge/custom/fragments/**`	`FRAGMENTS`	Yes
`knowledge/custom/solutions/**`	`SOLUTIONS`	Yes

Sources: python/helpers/memory.py297-325

Document Metadata

Every document in FAISS includes area information in its metadata:

Default Area Assignment

When inserting documents without explicit area metadata:

Sources: python/helpers/memory.py403-404

Area-Based Operations

Filtered Search

Memory searches can filter by area using Python expressions:

Filter Syntax Examples

Recall Settings

The recall process uses area-aware limits:

Setting	MAIN + FRAGMENTS	SOLUTIONS
`memory_recall_memories_max_search`	12	-
`memory_recall_solutions_max_search`	-	8
`memory_recall_memories_max_result`	5	-
`memory_recall_solutions_max_result`	-	3

Sources: python/extensions/message_loop_prompts_after/_50_recall_memories.py119-136 python/helpers/settings.py554-557

Area-Specific Consolidation

Memory consolidation respects area boundaries:

Key Constraint

Consolidation only considers memories within the same area. A new FRAGMENTS memory will never be merged with a SOLUTIONS memory, maintaining semantic boundaries.

Configuration Differences

Area	Max Similar	Max LLM Context	Strategy
`FRAGMENTS`	8	4	Aggressive merging
`SOLUTIONS`	6	3	Conservative (preserve distinct solutions)
`MAIN`	-	-	Manual import only

Sources: python/helpers/memory_consolidation.py1-400 python/extensions/monologue_end/_50_memorize_fragments.py108-133 python/extensions/monologue_end/_51_memorize_solutions.py115-140

Area Usage in Prompts

Memory Injection

Recalled memories are injected into agent prompts with area awareness:

Separate Prompt Sections

The agent receives memories in distinct sections:

General Memories (agent.system.memories.md)
- Contains MAIN and FRAGMENTS results
- Formatted as a continuous text block
- Emphasizes recent learnings and facts
Solutions (agent.system.solutions.md)
- Contains only SOLUTIONS results
- Structured as problem-solution pairs
- Emphasizes reusable patterns

Sources: python/extensions/message_loop_prompts_after/_50_recall_memories.py212-219

Area Management Best Practices

When to Use Each Area

Scenario	Recommended Area	Rationale
User writes documentation	`MAIN`	Curated, permanent knowledge
Agent learns user preference	`FRAGMENTS`	Temporary, context-specific
Agent solves a complex problem	`SOLUTIONS`	Reusable pattern for future
Import existing docs	`MAIN`	Reference material
API documentation	`MAIN`	Stable, factual information

Directory Organization

Recommended Structure

usr/
└── knowledge/
    ├── README.md                      # → MAIN
    ├── api_reference.md               # → MAIN
    ├── main/                          # Explicit MAIN area
    │   ├── company_policies.md
    │   └── style_guide.md
    ├── fragments/                     # Manual FRAGMENTS (rare)
    │   └── temp_notes.txt
    └── solutions/                     # Manual SOLUTIONS (rare)
        └── deployment_patterns.md

Note: fragments/ and solutions/ subdirectories are rarely used manually, as these areas are typically populated automatically by the agent's learning extensions.

Area Filtering Implementation

Filter Expression Evaluation

The memory system uses simpleeval to evaluate filter expressions safely:

Supported Operators

Equality: area == 'main'
Inequality: area != 'solutions'
Boolean: area == 'main' or area == 'fragments'
Negation: not knowledge_source
Existence: 'field_name' in metadata

Sources: python/helpers/memory.py432-441

Memory Types and Areas

Purpose and Scope

Area Enumeration

Memory Area Types

MAIN Area

FRAGMENTS Area

SOLUTIONS Area

Area Assignment and Routing

Knowledge Import Routing

Document Metadata

Area-Based Operations

Filtered Search

Area-Specific Consolidation

Area Usage in Prompts

Memory Injection

Area Management Best Practices

When to Use Each Area

Directory Organization

Area Filtering Implementation

Filter Expression Evaluation

System Diagram: Complete Area Flow

On this page

Memory Types and Areas

Purpose and Scope

Area Enumeration

Memory Area Types

MAIN Area

FRAGMENTS Area

SOLUTIONS Area

Area Assignment and Routing

Knowledge Import Routing

Document Metadata

Area-Based Operations

Filtered Search

Area-Specific Consolidation

Area Usage in Prompts

Memory Injection

Area Management Best Practices

When to Use Each Area

Directory Organization

Area Filtering Implementation

Filter Expression Evaluation

System Diagram: Complete Area Flow

On this page