# benschneider/llm-lucid-memory architecture

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

- Interactive diagram: https://gitdiagram.com/benschneider/llm-lucid-memory
- Repository: https://github.com/benschneider/llm-lucid-memory

## Overview

##### Project Type and Purpose
- This is an open-source Python library plus CLI/GUI tool (“llm-lucid-memory”) designed to build a graph-based reasoning memory for LLMs. It chunks text or code, digests each chunk via LLM calls into structured “MemoryNode”s, links them into a graph, and provides retrieval (keyword/graph-traversal) to augment LLM prompts via a proxy server or direct pipeline.

##### File Structure Analysis
- Top-level:
- lucid_memory/ – core modules (chunker, digestor, processor, memory_graph, retriever, proxy_server, CLI & GUI controllers, managers)
- ui/ + streamlit_app.py – lightweight Tkinter & Streamlit interfaces
- examples/ – demo scripts for ingestion pipeline & client usage
- tests/ – pytest unit-test suite
- config & prompts: prompts.yaml, proxy_config.json
- Manager classes in lucid_memory/managers handle configuration, component wiring, and server lifecycle.
- Proxy server (FastAPI + uvicorn) sits between UI/CLI and the external LLM backend.
- Processor uses ThreadPoolExecutor for parallel digestion.
- MemoryGraph persists nodes (in memory_graph.json) and exposes traversal.

##### README Insights
- Purpose: overcome LLM context limits by structuring knowledge into chunks, digesting with multi-call LLM prompts, and linking into a reasoning graph.
- Supported modes: CLI (“lucid-memory”), Tkinter GUI, Streamlit app.
- Core flow: Chunk → Digest → MemoryNode creation → Graph linking → Retrieval → Proxy-augmented LLM calls → Chat UI.
- Tech stack: Python, FastAPI, uvicorn, PyYAML, requests, Tkinter, Streamlit.

- User Interfaces:
- CLI (lucid_memory/cli.py)
- Tkinter GUI (lucid_memory/gui.py + ui/)
- Streamlit App (streamlit_app.py)
- Controller & Managers:
- Controller (controller.py)
- ConfigManager, ComponentManager, ServerManager
- Ingestion Pipeline:
- Chunker (chunker.py)
- Digestor (digestor.py)
- Processor (processor.py)
- Memory Storage & Retrieval:
- MemoryNode (memory_node.py)
- MemoryGraph (memory_graph.py)
- Retriever (retriever.py)
- Proxy Layer:
- ProxyServer (proxy_server.py)
- ChainEngine (chain_engine.py) for assembling prompts & chains
- External Services:
- Local/Remote LLM API (e.g., Ollama, LMStudio, OpenAI-compatible)

1. User → CLI/GUI → Controller
2. Controller → ConfigManager loads proxy_config/prompts.yaml
3. Controller → Chunker splits input file → Processor parallelizes → Digestor invokes LLM → returns structured data
4. Structured data → MemoryNode → MemoryGraph stores and links nodes
5. User query (in chat) → ProxyServer receives → Retriever fetches relevant MemoryNode(s) via keyword & graph traversal
6. ProxyServer assembles context + user prompt via ChainEngine → forwards to LLM API → response → returns to UI

c. Architectural Patterns & Principles:
- Pipeline pattern for ingestion (chunker → digestor → processor).
- Manager pattern for configuration and service orchestration.
- Modular separation of concerns: ingestion, storage, retrieval, proxying, UI.
- Thread-pool parallelism in Processor for performance.
- Service-oriented: ProxyServer as a micro-service that wraps LLM calls.

d. Key Technologies & Libraries:
- FastAPI + uvicorn for proxy server
- PyYAML for prompt/config parsing
- AST module for Python code chunking
- ThreadPoolExecutor for concurrent digestion
- Tkinter & Streamlit for UI layers
- JSON storage for memory_graph.json
- Pytest for testing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces" 
        direction TB
        CLI["CLI Interface"]:::ui
        TKGUI["Tkinter GUI"]:::ui
        STREAM["Streamlit App"]:::ui
    end

    %% Controllers & Managers
    subgraph "Controller & Managers"
        direction TB
        CONTROLLER["Main Controller"]:::controller
        CONFIG["Config Manager"]:::manager
        COMPONENT["Component Manager"]:::manager
        SERVERM["Server Manager"]:::manager
    end

    %% Ingestion Pipeline
    subgraph "Ingestion Pipeline"
        direction TB
        CHUNKER["Chunker"]:::pipeline
        PROCESSOR["Processor"]:::pipeline
        DIGESTOR["Digestor"]:::pipeline
    end

    %% Memory Storage & Retrieval
    subgraph "Memory Storage & Retrieval"
        direction TB
        MEMNODE["MemoryNode"]:::storage
        MEMGRAPH["MemoryGraph"]:::storage
        RETRIEVER["Retriever"]:::storage
    end

    %% Proxy Layer
    subgraph "Proxy Layer"
        direction TB
        PROXYSVC["Proxy Server"]:::proxy
        CHAIN["Chain Engine"]:::proxy
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLM["LLM API"]:::external
    end

    %% Flow Connections
    CLI -->|uses| CONTROLLER
    TKGUI -->|uses| CONTROLLER
    STREAM -->|uses| CONTROLLER

    CONTROLLER -->|loads configs| CONFIG
    CONTROLLER -->|wires components| COMPONENT
    CONTROLLER -->|manages server| SERVERM

    CONTROLLER -->|splits input| CHUNKER
    CHUNKER -->|chunks →| PROCESSOR
    PROCESSOR -->|parallel digest →| DIGESTOR
    DIGESTOR -->|returns structured data| MEMNODE
    MEMNODE -->|stores/links| MEMGRAPH

    RETRIEVER -->|fetches nodes| MEMGRAPH

    %% Chat Flow
    CLI -->|query| PROXYSVC
    TKGUI -->|query| PROXYSVC
    STREAM -->|query| PROXYSVC

    PROXYSVC -->|retrieve| RETRIEVER
    PROXYSVC -->|assemble context| CHAIN
    CHAIN -->|forwards →| LLM
    LLM -->|response| PROXYSVC
    PROXYSVC -->|returns| CLI
    PROXYSVC -->|returns| TKGUI
    PROXYSVC -->|returns| STREAM

    %% Click Events
    click CLI "https://github.com/benschneider/llm-lucid-memory/blob/main/lucid_memory/cli.py"
    click TKGUI "https://github.com/benschneider/llm-lucid-memory/tree/main/ui/"
    click STREAM "https://github.com/benschneider/llm-lucid-memory/blob/main/streamlit_app.py"
    click CONTROLLER "https://github.com/benschneider/llm-lucid-memory/blob/main/lucid_memory/controller.py"
    click CONFIG "https://github.com/benschneider/llm-lucid-memory/blob/main/lucid_memory/managers/config_manager.py"
    click COMPONENT "https://github.com/benschneider/llm-lucid-memory/blob/main/lucid_memory/managers/component_manager.py"
    click SERVERM "https://github.com/benschneider/llm-lucid-memory/blob/main/lucid_memory/managers/server_manager.py"
    click CHUNKER "https://github.com/benschneider/llm-lucid-memory/blob/main/lucid_memory/chunker.py"
    click DIGESTOR "https://github.com/benschneider/llm-lucid-memory/blob/main/lucid_memory/digestor.py"
    click PROCESSOR "https://github.com/benschneider/llm-lucid-memory/blob/main/lucid_memory/processor.py"
    click MEMNODE "https://github.com/benschneider/llm-lucid-memory/blob/main/lucid_memory/memory_node.py"
    click MEMGRAPH "https://github.com/benschneider/llm-lucid-memory/blob/main/lucid_memory/memory_graph.py"
    click RETRIEVER "https://github.com/benschneider/llm-lucid-memory/blob/main/lucid_memory/retriever.py"
    click PROXYSVC "https://github.com/benschneider/llm-lucid-memory/blob/main/lucid_memory/proxy_server.py"
    click CHAIN "https://github.com/benschneider/llm-lucid-memory/blob/main/lucid_memory/chain_engine.py"
    click CONFIG "https://github.com/benschneider/llm-lucid-memory/blob/main/lucid_memory/prompts.yaml"
    click SERVERM "https://github.com/benschneider/llm-lucid-memory/blob/main/lucid_memory/proxy_config.json"
    click TESTS "https://github.com/benschneider/llm-lucid-memory/tree/main/tests/"
    click EXAMPLES "https://github.com/benschneider/llm-lucid-memory/tree/main/examples/"

    %% Styles
    classDef ui fill:#E8F1FA,stroke:#0366D6,stroke-width:1px
    classDef controller fill:#F0F4C3,stroke:#558B2F,stroke-width:1px
    classDef manager fill:#FFF9C4,stroke:#F9A825,stroke-width:1px
    classDef pipeline fill:#E1BEE7,stroke:#8E24AA,stroke-width:1px
    classDef storage fill:#C8E6C9,stroke:#2E7D32,stroke-width:1px
    classDef proxy fill:#FFCDD2,stroke:#C62828,stroke-width:1px
    classDef external fill:#CFD8DC,stroke:#455A64,stroke-width:1px
```
