# agiresearch/a-mem architecture

> Architecture diagram of the GitHub repository agiresearch/a-mem, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agiresearch/a-mem
- Repository: https://github.com/agiresearch/a-mem

## Overview

##### Main Components
- Core Memory System Module: Represented by the memory_system.py file, it likely defines the AgenticMemorySystem class and its API for creating, reading, updating, and deleting memories.
- LLM Interaction Layer: The llm_controller.py module is responsible for managing LLM interactions (selecting LLM backends, model invocation, etc.).
- Retrieval Mechanisms: The retrievers.py module implements hybrid search functionality (e.g., combining ChromaDB vector search with embedding-based retrieval) and deduplication/ranking.
- Testing & Validation: Although not part of runtime architecture, tests (from test_memory_system.py and tests/) illustrate key functionalities and can hint at usage patterns.
- External Dependencies: The README details the use of embedding models (e.g., all-MiniLM-L6-v2) and integration with LLM APIs (e.g., OpenAI for GPT-4).

##### Relationships & Interactions
- When a new memory is created (via the AgenticMemorySystem API), it triggers:
- Generation with structured attributes and contextual tagging.
- Analysis of existing memories to establish semantic links.
- The LLM Controller (llm_controller.py) mediates decisions and selects the backend for any natural language processing operations—as well as managing communications with external LLM providers.
- The Retriever component handles search queries: when retrieving memories, the system uses both semantic and traditional search techniques (as indicated by “Hybrid Search”).
- The Memory Evolution process automatically updates metadata and creates semantic connections among memories as new or updated data is processed.

##### Architectural Patterns & Design Principles
- Modularity: Different concerns (memory management, LLM interactions, retrieval) are clearly split into separate modules.
- Agent-based architecture: Emphasis on “agent-driven decision making” and dynamic adaptation of the memory system.
- Hybrid Search and Dynamic Indexing: Illustrates a layered retrieval mechanism where traditional search meets advanced semantic search indexing.
- Extensibility: Support for multiple LLM backends and flexible metadata signify that the system is built for adaptation and future enhancements.

##### Relevant Technologies & Frameworks
- Python (core implementation using memory_system.py, retrievers.py, llm_controller.py)
- LLM models (GPT-4, GPT-3.5, potentially others via Ollama)
- Embedding models (e.g., all-MiniLM-L6-v2) for semantic search
- ChromaDB (mentioned indirectly in the README for vector search functionality)

##### Instructing the Principal Software Engineer
- “LLM Controller” (llm_controller.py) next to or integrated with the memory system, indicating that it manages LLM interactions and backend selections.
- “Memory Evolution” as an internal process or sub-module within the Agentic Memory System to show the dynamic updating of memory metadata and connections.
- Apply clear labeling for each component and relation (e.g., “Memory Creation”, “LLM Query for Semantic Analysis”, “Hybrid Search Execution”).

##### Final Advice
- Be very detailed: Even if the project is compact, break down the system into as many meaningful components as possible.
- Don’t hesitate to add annotations that reflect the operational flow as detailed in the README (e.g., noting that memory creation triggers note generation, metadata extraction, keyword/context analysis, and semantic linking).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Global Entities
    A["Client / API Caller"]:::external

    %% Core Modules
    subgraph "Core Modules"
        B["Agentic Memory System"]:::core
        E["Memory Evolution"]:::process
        C["LLM Controller"]:::core
        D["Retrievers"]:::core
    end

    %% External Services
    subgraph "External Services"
        F["OpenAI / Ollama API"]:::external
        G["Embedding Service - all-MiniLM-L6-v2"]:::external
    end

    %% Testing & Validation
    subgraph "Testing & Validation"
        I["Test Memory System"]:::test
        J["Test Utils"]:::test
        K["Tests Directory"]:::test
    end

    %% Connections
    A -->|"CRUD_Memory"| B
    B -->|"Trigger_Metadata_Evolution"| E
    B -->|"LLM_Query"| C
    B -->|"Hybrid_Search"| D
    C -->|"Invoke_API"| F
    D -->|"Semantic_Retrieval"| G
    I -->|"Unit_Test"| B
    J -->|"Test_Utils"| B
    K -->|"Integration_Test"| B

    %% Click Events
    click B "https://github.com/agiresearch/a-mem/blob/main/memory_system.py"
    click C "https://github.com/agiresearch/a-mem/blob/main/llm_controller.py"
    click D "https://github.com/agiresearch/a-mem/blob/main/retrievers.py"
    click I "https://github.com/agiresearch/a-mem/blob/main/test_memory_system.py"
    click J "https://github.com/agiresearch/a-mem/blob/main/tests/test_utils.py"
    click K "https://github.com/agiresearch/a-mem/tree/main/tests/"

    %% Styles
    classDef core fill:#CDE7BE,stroke:#333,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef process fill:#85C1E9,stroke:#333,stroke-width:2px,stroke-dasharray: 5, 5;
    classDef test fill:#F5B7B1,stroke:#333,stroke-width:2px;
```
