# farzad-r/agentic-longterm-memory architecture

> Architecture diagram of the GitHub repository farzad-r/agentic-longterm-memory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/farzad-r/agentic-longterm-memory
- Repository: https://github.com/farzad-r/agentic-longterm-memory

## Overview

##### Project type and purpose
- This is a Python-based AI agent project demonstrating multiple approaches to long-term memory for chatbots. It provides:
- A terminal chatbot (src/chat_in_terminal.py)
- A Gradio UI chatbot (src/chat_in_ui.py)
- Memory back-ends using SQLite and a Vector DB (Chroma)
- Integration with external LLMs (OpenAI via LangChain)
- Tutorials and course code (langgraph/)
- A research prototype (letta/)

##### File structure
- Top-level directories:
- config/ – YAML configuration
- src/ – main application entry points, DB setup, utilities
- langgraph/ – course and website tutorials around LangGraph memory systems
- letta/ – alternative memory model implementation
- src/ breakdown:
- chat_in_terminal.py & chat_in_ui.py – user-facing frontends
- prepare_*.py & check_*.py – DB provisioning and inspection scripts
- utils/ – core logic: memory managers, system prompt builder, search manager, SQL & vector DB managers, user & chat history managers
- Key config files: requirements.txt, config/config.yml

##### README insights
- Purpose: explore agentic long-term memory (semantic, episodic, procedural)
- Tech stack: Python, OpenAI, LangChain, LangGraph, SQLite, Chroma, Gradio
- Visual assets: eight schema PNGs in images/ showing default LLM behavior, memory concept, 3 chatbot architectures, and LangGraph pipelines

##### Essential details to capture
- The pipeline from user input → system prompt assembly → memory retrieval/insertion → LLM call → response post-processing
- Each memory subtype and how it reads/writes to its backing store
- Config management and how scripts initialize databases before runtime
- Extension points: course examples and LettA implementation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        style UI fill:#E0F7FA,stroke:#00796B
        Terminal["Terminal Client"]:::ui
        GradioUI["Gradio Web UI"]:::ui
    end

    %% Configuration
    subgraph "Configuration"
        style CFG fill:#FFF3E0,stroke:#E65100
        ConfigYAML["YAML Config"]:::infra
        ConfigLoader["Config Loader"]:::infra
    end

    %% Core Orchestration & Logic
    subgraph "Core Orchestration & Logic"
        style CORE fill:#E8F5E9,stroke:#2E7D32
        SystemPrompt["System Prompt & Orchestration"]:::core
        ChatHistory["Chat History Manager"]:::core
        SearchMgr["Search & Retrieval Orchestration"]:::core
        UserMgr["User & Session Management"]:::core
        Utils["Utility Helpers"]:::core
        BasicV1["Basic Chatbot v1"]:::core
        AgenticV2["Agentic Chatbot v2"]:::core
        AgenticV3["Agentic Chatbot v3"]:::core
    end

    %% Memory Subsystems
    subgraph "Memory Subsystems"
        style MEM fill:#FFFDE7,stroke:#F9A825
        SemanticMemory["Semantic Memory"]:::db
        EpisodicMemory["Episodic Memory"]:::db
        ProceduralMemory["Procedural Memory"]:::db
    end

    %% Database Layer
    subgraph "Database Layer"
        style DB fill:#FFF8E1,stroke:#FF8F00
        VectorDBMgr["Vector DB Manager"]:::db
        SQLMgr["SQL Manager"]:::db
    end

    %% External Services
    subgraph "External Services"
        style EXT fill:#F3E5F5,stroke:#6A1B9A
        OpenAI["OpenAI LLM API"]:::external
    end

    %% DevOps/Infra
    subgraph "DevOps/Infra"
        style INFRA fill:#ECEFF1,stroke:#546E7A
        ChromaPrep["Prepare Vector DB"]:::infra
        ChromaInspect["Inspect Vector DB"]:::infra
        SQLPrep["Prepare SQLite DB"]:::infra
        SQLInspect["Inspect SQLite DB"]:::infra
    end

    %% Extensions
    subgraph "Extensions"
        style EXTEN fill:#FBE9E7,stroke:#D84315
        LangGraphCourse["LangGraph Course Pipelines"]:::extension
        WebsiteTutorial["Website Tutorial Example"]:::extension
        LettA["LettA Memory Model Prototype"]:::extension
    end

    %% Connections: UI to Core
    Terminal -->|"User message"| SystemPrompt
    GradioUI -->|"User message"| SystemPrompt

    %% Config to Core
    ConfigYAML -->|"load settings"| ConfigLoader
    ConfigLoader -->|"provide config"| SystemPrompt

    %% Core orchestration flow
    SystemPrompt -->|"build prompt"| ChatHistory
    ChatHistory -->|"retrieve history"| SQLMgr
    ChatHistory -->|"retrieve history"| VectorDBMgr
    SystemPrompt -->|"orchestrate search"| SearchMgr
    SearchMgr -->|"query embeddings"| VectorDBMgr
    SearchMgr -->|"query SQL"| SQLMgr
    SystemPrompt -->|"choose logic"| BasicV1
    SystemPrompt -->|"choose logic"| AgenticV2
    SystemPrompt -->|"choose logic"| AgenticV3
    BasicV1 -->|"chat flow"| SystemPrompt
    AgenticV2 -->|"chat flow"| SystemPrompt
    AgenticV3 -->|"chat flow"| SystemPrompt

    %% Memory to Persistence
    SemanticMemory -->|"store/retrieve"| VectorDBMgr
    EpisodicMemory -->|"store/retrieve"| SQLMgr
    ProceduralMemory -->|"execute pipelines"| Utils

    %% Persistence to External Services
    VectorDBMgr -->|"Chroma SDK"| ChromaPrep
    VectorDBMgr -->|"Chroma SDK"| ChromaInspect
    SQLMgr -->|"SQLite3"| SQLPrep
    SQLMgr -->|"SQLite3"| SQLInspect

    %% Core to External API
    SystemPrompt -->|"LLM completion"| OpenAI
    OpenAI -->|"response"| SystemPrompt

    %% Extensions connections
    LangGraphCourse -->|"examples of pipelines"| ProceduralMemory
    WebsiteTutorial -->|"notebook demo"| ProceduralMemory
    LettA -->|"alternative model"| SystemPrompt

    %% Click Events
    click Terminal "https://github.com/farzad-r/agentic-longterm-memory/blob/master/src/chat_in_terminal.py"
    click GradioUI "https://github.com/farzad-r/agentic-longterm-memory/blob/master/src/chat_in_ui.py"
    click ConfigYAML "https://github.com/farzad-r/agentic-longterm-memory/blob/master/config/config.yml"
    click ConfigLoader "https://github.com/farzad-r/agentic-longterm-memory/blob/master/src/utils/config.py"
    click SystemPrompt "https://github.com/farzad-r/agentic-longterm-memory/blob/master/src/utils/prepare_system_prompt.py"
    click ChatHistory "https://github.com/farzad-r/agentic-longterm-memory/blob/master/src/utils/chat_history_manager.py"
    click BasicV1 "https://github.com/farzad-r/agentic-longterm-memory/blob/master/src/utils/basic_chatbot_v1.py"
    click AgenticV2 "https://github.com/farzad-r/agentic-longterm-memory/blob/master/src/utils/chatbot_agentic_v2.py"
    click AgenticV3 "https://github.com/farzad-r/agentic-longterm-memory/blob/master/src/utils/chatbot_agentic_v3.py"
    click VectorDBMgr "https://github.com/farzad-r/agentic-longterm-memory/blob/master/src/utils/vector_db_manager.py"
    click ChromaPrep "https://github.com/farzad-r/agentic-longterm-memory/blob/master/src/prepare_vectordb.py"
    click ChromaInspect "https://github.com/farzad-r/agentic-longterm-memory/blob/master/src/check_vectordb.py"
    click SQLMgr "https://github.com/farzad-r/agentic-longterm-memory/blob/master/src/utils/sql_manager.py"
    click SQLPrep "https://github.com/farzad-r/agentic-longterm-memory/blob/master/src/prepare_sqldb.py"
    click SQLInspect "https://github.com/farzad-r/agentic-longterm-memory/blob/master/src/check_sqldb.py"
    click SearchMgr "https://github.com/farzad-r/agentic-longterm-memory/blob/master/src/utils/search_manager.py"
    click UserMgr "https://github.com/farzad-r/agentic-longterm-memory/blob/master/src/utils/user_manager.py"
    click Utils "https://github.com/farzad-r/agentic-longterm-memory/blob/master/src/utils/utils.py"
    click LangGraphCourse "https://github.com/farzad-r/agentic-longterm-memory/tree/master/langgraph/online-course/"
    click WebsiteTutorial "https://github.com/farzad-r/agentic-longterm-memory/blob/master/langgraph/website-tutorial/chatbot_with_longterm_memory.ipynb"
    click LettA "https://github.com/farzad-r/agentic-longterm-memory/blob/master/letta/chatbot_with_longterm_memory.py"

    %% Styles
    classDef ui fill:#BBDEFB,stroke:#0D47A1
    classDef core fill:#C8E6C9,stroke:#1B5E20
    classDef db fill:#FFE0B2,stroke:#E65100
    classDef external fill:#E1BEE7,stroke:#4A148C
    classDef infra fill:#CFD8DC,stroke:#37474F
    classDef extension fill:#FFCCBC,stroke:#BF360C
```
