fleet-memory/memory/operations

Memory Operations Modules

This directory contains specialized operation modules for the TemporalSemanticMemory class.

Refactoring Results

✅ Successfully Completed!

File Size Reduction:

• Before: 1,720 lines (temporal_semantic_memory.py)
• After: 1,420 lines (temporal_semantic_memory.py)
• Removed: 300 lines (17% reduction)

Modules Created:

• embedding_operations.py - Embedding generation with process pool parallelism
• link_operations.py - Entity, temporal, and semantic link creation (300+ lines)
• batch_operations.py - Placeholder for future extraction
• search_operations.py - Placeholder for future extraction

Architecture

The memory system now uses a mixin pattern for better code organization:

class TemporalSemanticMemory(
    EmbeddingOperationsMixin,
    LinkOperationsMixin,
):
    """
    Advanced memory system using temporal and semantic linking.

    Mixins provide:
    - EmbeddingOperationsMixin: _generate_embedding, _generate_embeddings_batch
    - LinkOperationsMixin: Entity, temporal, semantic link operations
    """
    # Core infrastructure and batch operations
    pass

What Was Extracted

EmbeddingOperationsMixin (embedding_operations.py)

• _generate_embedding() - Single embedding generation
• _generate_embeddings_batch() - Parallel batch embedding generation
• Process pool worker functions for CPU parallelism

LinkOperationsMixin (link_operations.py)

• _extract_entities_batch_optimized() - Entity resolution and linking
• _create_temporal_links_batch_per_fact() - Time-based connections
• _create_semantic_links_batch() - Meaning-based connections
• _insert_entity_links_batch() - Batch link insertion

Remaining in Main Class

• Database connection management (__init__, _get_pool, close)
• Batch storage operations (put, put_async, put_batch_async)
• Search operations (search, search_async, _apply_mmr)
• Document management (get_document, delete_document, delete_agent)
• Think operations (think_async)
• Deduplication (_find_duplicate_facts_batch)

Benefits Achieved

1. ✅ Better Organization - Related methods grouped in focused modules
2. ✅ Reduced Complexity - Main file is 17% smaller
3. ✅ Reusability - Mixins can be composed and tested independently
4. ✅ Maintainability - Easier to find and modify specific operations
5. ✅ All Tests Pass - No breaking changes to public API

Usage

The public API remains unchanged:

from memory import TemporalSemanticMemory

memory = TemporalSemanticMemory()

# All operations work exactly as before
result = await memory.think_async(
    agent_id="agent_1",
    query="What have I done?"
)

results, trace = await memory.search_async(
    agent_id="agent_1",
    query="example query",
    fact_type="world"
)

Future Work (Optional)

The foundation is now in place for further extraction:

• Extract batch operations to batch_operations.py
• Extract search operations to search_operations.py
• Split large methods into smaller, focused functions

Design Principles Followed

1. ✅ Preserved batch mechanisms - Performance maintained
2. ✅ No breaking changes - All tests pass
3. ✅ Clear separation - Each mixin has focused responsibility
4. ✅ Gradual refactoring - Can continue incrementally