# realhenrylan/mneme architecture

> Architecture diagram of the GitHub repository realhenrylan/mneme, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/realhenrylan/mneme
- Repository: https://github.com/realhenrylan/mneme

## Overview

Mneme is a local-document RAG application: users add documents, ask questions in the terminal UI or CLI, and receive generated answers with source citations. Its principal workflow spans document loading and chunking, manifest-consistent indexing, query planning, hybrid retrieval (optionally expanded with Graph RAG), evidence/context assembly, and LLM generation. The graph preserves documented capabilities; some connections are based on README descriptions because the corresponding implementation excerpts were not sampled.

Main entry points: [`src/rag.py`](https://github.com/realhenrylan/mneme/blob/main/src/rag.py) (Query planning), [`tui/service.py`](https://github.com/realhenrylan/mneme/blob/main/tui/service.py) (TUI service), [`src/llm_gateway.py`](https://github.com/realhenrylan/mneme/blob/main/src/llm_gateway.py) (LLM gateway), [`tui/app.py`](https://github.com/realhenrylan/mneme/blob/main/tui/app.py) (Terminal UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_tui["Terminal UI<br/>[app.py]"]
  node_tui_service["TUI service<br/>[service.py]"]
  node_cli["RAG CLI<br/>[rag.py]"]
end

subgraph group_indexing["Document indexing"]
  node_loaders["Document loaders"]
  node_chunking["Chunking<br/>[chunking.py]"]
  node_indexing_runtime["Index management<br/>[rag.py]"]
  node_index_store[("Vector index<br/>[rag.py]")]
end

subgraph group_answering["Question answering"]
  node_query_planning["Query planning<br/>[rag.py]"]
  node_decomposer["Query decomposition"]
  node_rewriter["History rewrite"]
  node_retrieval["Hybrid retrieval<br/>[retrieval.py]"]
  node_lexical["BM25 search<br/>[lexical.py]"]
  node_graph_rag["Graph expansion<br/>[graph_rag.py]"]
  node_evidence["Evidence assembly<br/>[rag.py]"]
  node_citations["Citations<br/>[citations.py]"]
  node_llm_gateway["LLM gateway<br/>[llm_gateway.py]"]
end

subgraph group_operations["Operations and safeguards"]
  node_watcher["Directory watcher<br/>[file_watcher.py]"]
  node_observability[("Diagnostic traces")]
end

node_user(("User"))
node_llm_endpoint{{"LLM endpoint"}}

node_user -->|"starts session"| node_tui
node_user -->|"runs query"| node_cli
node_tui -->|"uses service"| node_tui_service
node_tui -->|"starts indexing"| node_tui_service
node_tui_service -->|"adds or removes"| node_indexing_runtime
node_indexing_runtime -->|"loads files"| node_loaders
node_indexing_runtime -->|"splits text"| node_chunking
node_indexing_runtime -->|"updates index"| node_index_store
node_tui_service -->|"starts watching"| node_watcher
node_watcher -->|"signals changes"| node_tui_service
node_tui_service -->|"runs query"| node_query_planning
node_cli -->|"runs query"| node_query_planning
node_query_planning -->|"decomposes query"| node_decomposer
node_query_planning -->|"rewrites follow-up"| node_rewriter
node_query_planning -->|"retrieves candidates"| node_retrieval
node_retrieval -->|"searches vectors"| node_index_store
node_retrieval -->|"searches keywords"| node_lexical
node_query_planning -.->|"expands graph mode"| node_graph_rag
node_graph_rag -->|"reads indexed chunks"| node_index_store
node_query_planning -->|"prepares evidence"| node_evidence
node_evidence -->|"formats sources"| node_citations
node_query_planning -->|"requests answer"| node_llm_gateway
node_decomposer -->|"requests decomposition"| node_llm_gateway
node_rewriter -->|"requests rewrite"| node_llm_gateway
node_llm_gateway -->|"calls model"| node_llm_endpoint
node_query_planning -.->|"records opted-in diagnostics"| node_observability

click node_tui "https://github.com/realhenrylan/mneme/blob/main/tui/app.py"
click node_tui_service "https://github.com/realhenrylan/mneme/blob/main/tui/service.py"
click node_cli "https://github.com/realhenrylan/mneme/blob/main/src/rag.py"
click node_loaders "https://github.com/realhenrylan/mneme/tree/main/src/loaders"
click node_chunking "https://github.com/realhenrylan/mneme/blob/main/src/chunking.py"
click node_indexing_runtime "https://github.com/realhenrylan/mneme/blob/main/src/rag.py"
click node_index_store "https://github.com/realhenrylan/mneme/blob/main/src/rag.py"
click node_query_planning "https://github.com/realhenrylan/mneme/blob/main/src/rag.py"
click node_decomposer "https://github.com/realhenrylan/mneme/blob/main/src/rag_query_decomposer.py"
click node_rewriter "https://github.com/realhenrylan/mneme/blob/main/src/rag_query_rewriter.py"
click node_retrieval "https://github.com/realhenrylan/mneme/blob/main/src/retrieval.py"
click node_lexical "https://github.com/realhenrylan/mneme/blob/main/src/lexical.py"
click node_graph_rag "https://github.com/realhenrylan/mneme/blob/main/src/graph_rag.py"
click node_evidence "https://github.com/realhenrylan/mneme/blob/main/src/rag.py"
click node_citations "https://github.com/realhenrylan/mneme/blob/main/src/citations.py"
click node_llm_gateway "https://github.com/realhenrylan/mneme/blob/main/src/llm_gateway.py"
click node_watcher "https://github.com/realhenrylan/mneme/blob/main/tui/file_watcher.py"
click node_observability "https://github.com/realhenrylan/mneme/blob/main/src/production_observability.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tui,node_tui_service,node_cli,node_user toneBlue
class node_loaders,node_chunking,node_indexing_runtime,node_index_store toneAmber
class node_query_planning,node_decomposer,node_rewriter,node_retrieval,node_lexical,node_graph_rag,node_evidence,node_citations,node_llm_gateway toneMint
class node_watcher,node_observability toneRose
class node_llm_endpoint toneIndigo
```

## Components

### User interfaces

- [Terminal UI](https://github.com/realhenrylan/mneme/blob/main/tui/app.py): `tui/app.py`
- [TUI service](https://github.com/realhenrylan/mneme/blob/main/tui/service.py): `tui/service.py`
- [RAG CLI](https://github.com/realhenrylan/mneme/blob/main/src/rag.py): `src/rag.py`

### Document indexing

- [Document loaders](https://github.com/realhenrylan/mneme/tree/main/src/loaders): `src/loaders`
- [Chunking](https://github.com/realhenrylan/mneme/blob/main/src/chunking.py): `src/chunking.py`
- [Index management](https://github.com/realhenrylan/mneme/blob/main/src/rag.py): `src/rag.py`
- [Vector index](https://github.com/realhenrylan/mneme/blob/main/src/rag.py): `src/rag.py`

### Question answering

- [Query planning](https://github.com/realhenrylan/mneme/blob/main/src/rag.py): `src/rag.py`
- [Query decomposition](https://github.com/realhenrylan/mneme/blob/main/src/rag_query_decomposer.py): `src/rag_query_decomposer.py`
- [History rewrite](https://github.com/realhenrylan/mneme/blob/main/src/rag_query_rewriter.py): `src/rag_query_rewriter.py`
- [Hybrid retrieval](https://github.com/realhenrylan/mneme/blob/main/src/retrieval.py): `src/retrieval.py`
- [BM25 search](https://github.com/realhenrylan/mneme/blob/main/src/lexical.py): `src/lexical.py`
- [Graph expansion](https://github.com/realhenrylan/mneme/blob/main/src/graph_rag.py): `src/graph_rag.py`
- [Evidence assembly](https://github.com/realhenrylan/mneme/blob/main/src/rag.py): `src/rag.py`
- [Citations](https://github.com/realhenrylan/mneme/blob/main/src/citations.py): `src/citations.py`
- [LLM gateway](https://github.com/realhenrylan/mneme/blob/main/src/llm_gateway.py): `src/llm_gateway.py`

### Operations and safeguards

- [Directory watcher](https://github.com/realhenrylan/mneme/blob/main/tui/file_watcher.py): `tui/file_watcher.py`
- [Diagnostic traces](https://github.com/realhenrylan/mneme/blob/main/src/production_observability.py): `src/production_observability.py`

### Other components

- **User**
- **LLM endpoint**

## Connections

- User → Terminal UI: starts session
- User → RAG CLI: runs query
- Terminal UI → TUI service: uses service
- Terminal UI → TUI service: starts indexing
- TUI service → Index management: adds or removes
- Index management → Document loaders: loads files
- Index management → Chunking: splits text
- Index management → Vector index: updates index
- TUI service → Directory watcher: starts watching
- Directory watcher → TUI service: signals changes
- TUI service → Query planning: runs query
- RAG CLI → Query planning: runs query
- Query planning → Query decomposition: decomposes query
- Query planning → History rewrite: rewrites follow-up
- Query planning → Hybrid retrieval: retrieves candidates
- Hybrid retrieval → Vector index: searches vectors
- Hybrid retrieval → BM25 search: searches keywords
- Query planning → Graph expansion: expands graph mode
- Graph expansion → Vector index: reads indexed chunks
- Query planning → Evidence assembly: prepares evidence
- Evidence assembly → Citations: formats sources
- Query planning → LLM gateway: requests answer
- Query decomposition → LLM gateway: requests decomposition
- History rewrite → LLM gateway: requests rewrite
- LLM gateway → LLM endpoint: calls model
- Query planning → Diagnostic traces: records opted-in diagnostics