# sup3rus3r/omnex architecture

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

- Interactive diagram: https://gitdiagram.com/sup3rus3r/omnex
- Repository: https://github.com/sup3rus3r/omnex

## Overview

Omnex is a self-hosted AI memory system: users ingest local files, which are classified, processed and enriched into searchable memory, then recall them through natural-language queries. Its API also exposes memory to agents and federates instances; the UI supports identity management, timeline, setup and voice features. The README documents the broader capabilities; sampled source confirms selected API, ingestion and UI wiring, so unsampled subsystem links are omitted where ownership is uncertain.

Main entry points: [`api/main.py`](https://github.com/sup3rus3r/omnex/blob/main/api/main.py) (FastAPI application), [`api/routes/ingest.py`](https://github.com/sup3rus3r/omnex/blob/main/api/routes/ingest.py) (Ingestion endpoints), [`api/routes/query.py`](https://github.com/sup3rus3r/omnex/blob/main/api/routes/query.py) (Query endpoints), [`api/query_engine.py`](https://github.com/sup3rus3r/omnex/blob/main/api/query_engine.py) (Query engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_ui["Omnex interface<br/>[page.tsx]"]
  node_ingest_ui["Ingestion controls<br/>[IngestionPanel.tsx]"]
  node_dashboard["Ingestion dashboard"]
  node_query_ui["Recall query<br/>[QueryBar.tsx]"]
  node_results_ui["Result presentation<br/>[ResultGrid.tsx]"]
  node_identity_ui["Identity manager"]
end

subgraph group_api["API and integrations"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_ingest_api["Ingestion endpoints<br/>[ingest.py]"]
  node_query_api["Query endpoints<br/>[query.py]"]
  node_query_engine["Query engine<br/>[query_engine.py]"]
  node_agent_api["Agent and MCP API<br/>[mcp.py]"]
  node_federation_api["Federation API<br/>[federation.py]"]
  node_timeline_api["Timeline API<br/>[timeline.py]"]
  node_voice_api["Voice API<br/>[tts.py]"]
end

subgraph group_memory["Memory pipeline"]
  node_file_router["File detection and routing<br/>[router.py]"]
  node_processors["Media processors"]
  node_embeddings["Multimodal embeddings"]
  node_tagging["Semantic tagging<br/>[semantic_tagger.py]"]
end

subgraph group_state["Memory state"]
  node_mongo[("Metadata and sessions<br/>[mongo.py]")]
  node_vectors[("Vector index<br/>[leann_store.py]")]
  node_binary[("Binary content store<br/>[binary_store.py]")]
end

node_user(("Human user"))
node_agent(("AI agent"))
node_external_llm{{"Configured LLM"}}
node_remote_instance{{"Peer Omnex instance"}}

node_user -->|"uses"| node_ui
node_ui -->|"opens"| node_ingest_ui
node_ui -->|"opens"| node_query_ui
node_ingest_ui -->|"uploads or triggers"| node_ingest_api
node_dashboard -->|"starts and polls"| node_ingest_api
node_ingest_api -->|"routes files"| node_file_router
node_file_router -->|"selects processor"| node_processors
node_processors -->|"embeds content"| node_embeddings
node_processors -->|"enriches chunks"| node_tagging
node_ingest_api -->|"tracks ingestion"| node_mongo
node_ingest_api -->|"deletes vectors"| node_vectors
node_ingest_api -->|"deletes blobs"| node_binary
node_query_ui -->|"submits query"| node_query_api
node_query_api -->|"runs search"| node_query_engine
node_query_api -->|"loads and saves sessions"| node_mongo
node_query_engine -->|"searches index"| node_vectors
node_query_engine -->|"expands source"| node_mongo
node_query_api -->|"returns results"| node_results_ui
node_identity_ui -->|"requests identity data"| node_api_app
node_api_app -->|"mounts routes"| node_query_api
node_api_app -->|"mounts routes"| node_ingest_api
node_agent -->|"reads and writes memory"| node_agent_api
node_api_app -->|"mounts routes"| node_agent_api
node_api_app -->|"mounts routes"| node_federation_api
node_federation_api -.->|"federates"| node_remote_instance
node_api_app -->|"mounts routes"| node_timeline_api
node_api_app -->|"mounts routes"| node_voice_api
node_query_engine -.->|"generates answers"| node_external_llm

click node_ui "https://github.com/sup3rus3r/omnex/blob/main/interface/app/page.tsx"
click node_ingest_ui "https://github.com/sup3rus3r/omnex/blob/main/interface/components/IngestionPanel/IngestionPanel.tsx"
click node_dashboard "https://github.com/sup3rus3r/omnex/blob/main/interface/components/IngestionDashboard/IngestionDashboard.tsx"
click node_query_ui "https://github.com/sup3rus3r/omnex/blob/main/interface/components/QueryBar/QueryBar.tsx"
click node_results_ui "https://github.com/sup3rus3r/omnex/blob/main/interface/components/ResultGrid/ResultGrid.tsx"
click node_identity_ui "https://github.com/sup3rus3r/omnex/blob/main/interface/components/IdentityManager/IdentityManager.tsx"
click node_api_app "https://github.com/sup3rus3r/omnex/blob/main/api/main.py"
click node_ingest_api "https://github.com/sup3rus3r/omnex/blob/main/api/routes/ingest.py"
click node_query_api "https://github.com/sup3rus3r/omnex/blob/main/api/routes/query.py"
click node_query_engine "https://github.com/sup3rus3r/omnex/blob/main/api/query_engine.py"
click node_agent_api "https://github.com/sup3rus3r/omnex/blob/main/api/routes/mcp.py"
click node_federation_api "https://github.com/sup3rus3r/omnex/blob/main/api/routes/federation.py"
click node_timeline_api "https://github.com/sup3rus3r/omnex/blob/main/api/routes/timeline.py"
click node_voice_api "https://github.com/sup3rus3r/omnex/blob/main/api/routes/tts.py"
click node_file_router "https://github.com/sup3rus3r/omnex/blob/main/ingestion/router.py"
click node_processors "https://github.com/sup3rus3r/omnex/tree/main/ingestion/processors"
click node_embeddings "https://github.com/sup3rus3r/omnex/tree/main/embeddings"
click node_tagging "https://github.com/sup3rus3r/omnex/blob/main/ingestion/semantic_tagger.py"
click node_mongo "https://github.com/sup3rus3r/omnex/blob/main/storage/mongo.py"
click node_vectors "https://github.com/sup3rus3r/omnex/blob/main/storage/leann_store.py"
click node_binary "https://github.com/sup3rus3r/omnex/blob/main/storage/binary_store.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_ui,node_ingest_ui,node_dashboard,node_query_ui,node_results_ui,node_identity_ui,node_user toneBlue
class node_api_app,node_ingest_api,node_query_api,node_query_engine,node_agent_api,node_federation_api,node_timeline_api,node_voice_api toneAmber
class node_file_router,node_processors,node_embeddings,node_tagging toneMint
class node_mongo,node_vectors,node_binary toneRose
class node_agent,node_external_llm,node_remote_instance toneIndigo
```

## Components

### User experience

- [Omnex interface](https://github.com/sup3rus3r/omnex/blob/main/interface/app/page.tsx): `interface/app/page.tsx`
- [Ingestion controls](https://github.com/sup3rus3r/omnex/blob/main/interface/components/IngestionPanel/IngestionPanel.tsx): `interface/components/IngestionPanel/IngestionPanel.tsx`
- [Ingestion dashboard](https://github.com/sup3rus3r/omnex/blob/main/interface/components/IngestionDashboard/IngestionDashboard.tsx): `interface/components/IngestionDashboard/IngestionDashboard.tsx`
- [Recall query](https://github.com/sup3rus3r/omnex/blob/main/interface/components/QueryBar/QueryBar.tsx): `interface/components/QueryBar/QueryBar.tsx`
- [Result presentation](https://github.com/sup3rus3r/omnex/blob/main/interface/components/ResultGrid/ResultGrid.tsx): `interface/components/ResultGrid/ResultGrid.tsx`
- [Identity manager](https://github.com/sup3rus3r/omnex/blob/main/interface/components/IdentityManager/IdentityManager.tsx): `interface/components/IdentityManager/IdentityManager.tsx`

### API and integrations

- [FastAPI application](https://github.com/sup3rus3r/omnex/blob/main/api/main.py): `api/main.py`
- [Ingestion endpoints](https://github.com/sup3rus3r/omnex/blob/main/api/routes/ingest.py): `api/routes/ingest.py`
- [Query endpoints](https://github.com/sup3rus3r/omnex/blob/main/api/routes/query.py): `api/routes/query.py`
- [Query engine](https://github.com/sup3rus3r/omnex/blob/main/api/query_engine.py): `api/query_engine.py`
- [Agent and MCP API](https://github.com/sup3rus3r/omnex/blob/main/api/routes/mcp.py): `api/routes/mcp.py`
- [Federation API](https://github.com/sup3rus3r/omnex/blob/main/api/routes/federation.py): `api/routes/federation.py`
- [Timeline API](https://github.com/sup3rus3r/omnex/blob/main/api/routes/timeline.py): `api/routes/timeline.py`
- [Voice API](https://github.com/sup3rus3r/omnex/blob/main/api/routes/tts.py): `api/routes/tts.py`

### Memory pipeline

- [File detection and routing](https://github.com/sup3rus3r/omnex/blob/main/ingestion/router.py): `ingestion/router.py`
- [Media processors](https://github.com/sup3rus3r/omnex/tree/main/ingestion/processors): `ingestion/processors`
- [Multimodal embeddings](https://github.com/sup3rus3r/omnex/tree/main/embeddings): `embeddings`
- [Semantic tagging](https://github.com/sup3rus3r/omnex/blob/main/ingestion/semantic_tagger.py): `ingestion/semantic_tagger.py`

### Memory state

- [Metadata and sessions](https://github.com/sup3rus3r/omnex/blob/main/storage/mongo.py): `storage/mongo.py`
- [Vector index](https://github.com/sup3rus3r/omnex/blob/main/storage/leann_store.py): `storage/leann_store.py`
- [Binary content store](https://github.com/sup3rus3r/omnex/blob/main/storage/binary_store.py): `storage/binary_store.py`

### Other components

- **Human user**
- **AI agent**
- **Configured LLM**
- **Peer Omnex instance**

## Connections

- Human user → Omnex interface: uses
- Omnex interface → Ingestion controls: opens
- Omnex interface → Recall query: opens
- Ingestion controls → Ingestion endpoints: uploads or triggers
- Ingestion dashboard → Ingestion endpoints: starts and polls
- Ingestion endpoints → File detection and routing: routes files
- File detection and routing → Media processors: selects processor
- Media processors → Multimodal embeddings: embeds content
- Media processors → Semantic tagging: enriches chunks
- Ingestion endpoints → Metadata and sessions: tracks ingestion
- Ingestion endpoints → Vector index: deletes vectors
- Ingestion endpoints → Binary content store: deletes blobs
- Recall query → Query endpoints: submits query
- Query endpoints → Query engine: runs search
- Query endpoints → Metadata and sessions: loads and saves sessions
- Query engine → Vector index: searches index
- Query engine → Metadata and sessions: expands source
- Query endpoints → Result presentation: returns results
- Identity manager → FastAPI application: requests identity data
- FastAPI application → Query endpoints: mounts routes
- FastAPI application → Ingestion endpoints: mounts routes
- AI agent → Agent and MCP API: reads and writes memory
- FastAPI application → Agent and MCP API: mounts routes
- FastAPI application → Federation API: mounts routes
- Federation API → Peer Omnex instance: federates
- FastAPI application → Timeline API: mounts routes
- FastAPI application → Voice API: mounts routes
- Query engine → Configured LLM: generates answers